Overview

For: anyone opening this repository for the first time, or returning to it after enough time away that the layout has gone.

Grafted Wars is a persistent-universe space strategy game. One universe holds every account, human and synthetic alike; play is mining, building, researching and sending ships at other colonies, continuously and in real time. The domain language the code actually uses is defined in CONTEXT.md, and the decisions behind the shape of the thing are in docs/adr/.

How the code is laid out

Six directories carry the product. Each has one owner and one subject, and a change that spans two of them is a change that needs a reason.

Directory	Holds
src/engine/	Procedural generation and rendering mathematics — world, planet and system generation, the hex lattice, tile libraries, geology, biomes.
src/catalog/	The data behind the rules: units, buildings, research, costs, prerequisites.
src/gameplay/	The formulas that consume the catalog.
src/server/	The Cloudflare Worker and the Universe Durable Object — routes, missions, economy, authentication, the event stream.
app/src/game/	The React client: pages, panels, themes, styles and client data modules, written against the data contract in app/src/game/data/contract.mjs.
platforms/	The desktop and mobile shells that wrap the client.

Around them sit tools/ and scripts/, which are the repository's own machinery rather than the product: the gate's checks, the test runner, the deploy paths and the tracker driver. Every one of those has a reference page under Contributor tooling, Operator tooling or Agent tooling.

Three environments

The product runs in three places, from one build with environment-selected configuration and three separate stores.

Environment	What it is	Store
dev	The local loop on a developer machine.	Disposable, wiped at will.
staging	A deployment identical to production, where release candidates soak.	Its own Durable Object namespace, seeded and reset freely.
production	Real players.	Never wiped; schema changes arrive as migrations only.

Synthetic players run in dev and staging and never in production. Unwired surfaces are shown in dev and staging and hidden in production. The reasoning is in docs/adr/0011-three-environments.md and docs/adr/0010-live-surfaces-render-server-truth-or-marked-absence.md.

The commands that move a build between those three are in the Runbook, which also holds the credentials map, the platform builds and the data-access routes.

The gate

One command decides whether a change may land:

npm run check

It runs the type check and the linter, then the comment and glossary lints. The citation, catalog, art registry and vendor checks follow. The test suites and the build come next, and the browser and dev-loop suites come last. Continuous integration runs the same command.

A claim about this repository is proved by a spec the gate re-runs. A passing run leaves nothing behind on disk.

Where to go next

You want to	Start at
find the entry point for a job	Get things done
run, deploy or debug the product	Runbook
change the repository's own code	Contributor tooling
ship a release	Operator tooling
act on the tracker or a pull request	Agent tooling
understand a domain word	CONTEXT.md
understand why something is shaped as it is	docs/adr/