Getting started

designed · Phase 1 (#29, #33, #39, #40) · PLAN §13.1, §22.7, §22.8

Two processes, no orchestrator, no containers (PLAN §13.1). Everything the engine needs is .NET 10; the clients need Node 22.

Run the stack

dotnet run --project src/NextIteration.Api       # engine + API on http://localhost:5000
npm run dev --prefix clients/app                 # Vite dev server on http://localhost:3000, proxies /api → 5000

or both at once:

scripts/dev.ps1     # Windows
scripts/dev.sh      # macOS / Linux

Open http://localhost:3000/ for the Universe Viewer and http://localhost:3000/dev for the Developer Studio. Create a universe with the village scenario from the Studio, or:

POST /universes  { "config": { "seed": 42 }, "scenario": "village" }
POST /universes/{id}/start

Run the tests

dotnet test                                   # unit + integration, full intended duration
dotnet test tests/NextIteration.Harness --filter milestone=phase-1    # the Phase 1 story milestone

Run the harness

dotnet run --project tests/NextIteration.Harness -- village --seeds 10 --days 10 --out out/
dotnet run --project tests/NextIteration.Harness -- village --seeds 1 --days 10 --golden --processes 2

The first writes summary.md, report.json and chronicle excerpts; the second is the determinism gate. See Harness.

Write a system

A system is one class implementing ISimulationSystem plus a manifest. The complete walkthrough is SYSTEM_DEVELOPMENT.md in the repository root; the contract is on Tick pipeline and systems; the rules that bite are on Determinism and in CLAUDE.md's invariants. Register it inactive by default until its increment's done-when passes (CLAUDE.md → PROGRESS TRACKING).

Edit this wiki

pip install mkdocs-material
mkdocs serve        # http://127.0.0.1:8000/, live reload
mkdocs build --strict

Section references like §7.3 are checked by scripts/check-docs.sh against PLAN.md's headings; links are checked by the strict build.

Publishing is automatic: a push to main that touches docs/ or mkdocs.yml builds the site in Actions, commits it to the site branch and deploys it to nextiteration.maurer.nu within about a minute (.github/workflows/docs.yml). Pull requests only build; nothing is published from a branch. Which version am I reading? The footer of every page names the source commit, the build time and the latest phase-* tag; /version.json carries the same; the site branch's history is the list of every published state, each commit named after the source commit it was built from.