Project documentation

July 6, 2026 · View on GitHub

This directory is the entry point for maintained documentation. Legacy reports and historical summaries may still exist in the repository; prefer the pages below for current setup and architecture.

Current documentation map

  • Architecture — framework-first architecture, package responsibilities, lifecycle, memory/cache, CPU strategy.
  • Development — local workflow, framework-first placement, validation gates.
  • Testing — unit, integration, private-server, quality gates, and mocking conventions.
  • Deployment — local deploy, GitHub Actions deploy, secrets, dry runs, rollback.
  • Operations — monitoring, stats, CPU/bucket expectations, runtime triage.
  • Game strategy — economy-first doctrine, remotes, defense, expansion, combat, labs, market, intershard.
  • Packages — package purpose, dependency boundaries, and test commands.
  • ADRs — architecture decision records only.
  • Framework guide — framework package usage and contribution notes.

Source of truth

  • ROADMAP.md governs gameplay strategy and swarm architecture.
  • AGENTS.md governs agent/development workflow and safety rules.
  • package.json scripts are authoritative for local commands.
  • Package README.md files document package-specific public APIs.

Documentation build

npm run build:docs

The build aggregates docs into wiki/ for optional GitHub wiki publishing. wiki/ is generated output and should not be hand-edited.

GitHub Pages is the canonical automated documentation publication path (.github/workflows/docs.yml). The wiki publish workflow (.github/workflows/wiki-publish.yml) is best-effort: it builds docs, checks whether the repository wiki is available to GITHUB_TOKEN, and skips the wiki upload with a clear workflow summary when ${owner}/${repo}.wiki is absent or inaccessible.

Writing rules

  • Add clear titles to every Markdown file.
  • Prefer relative links.
  • Keep setup instructions aligned with Node.js 24 and npm workspaces.
  • Put new architecture decisions in docs/adr/ only when they record a real decision and trade-off.
  • Keep package-specific details in package README/docs; link from docs/packages/README.md.