Naming and structure¶
Paths¶
Use lowercase kebab-case for directories and Markdown filenames. Name a page for
its durable subject, such as house-chat.md or lifecycle-gates.md; omit type
suffixes such as _KB, _notes, _handoff, _analysis, and version labels.
Put dates and lifecycle state in frontmatter or Git history rather than filenames.
Use index.md only as a section context map. An index defines scope, terminology,
canonical pages, and a useful reading order. It should not duplicate the section's
detailed content. Keep the repository root limited to README.md, agent guidance,
and repository support files.
Top-level sections¶
| Directory | Scope |
|---|---|
architecture/ |
Cross-cutting ownership, subsystem boundaries, and system design |
backend/ |
Nakama, Edgegap, persistence, RPCs, and backend data contracts |
multiplayer/ |
House, selection, matchmaking, travel, rehost, and recovery flows |
gameplay/ |
Runtime game systems, teams, minions, definitions, and networking behavior |
ui/ |
UI subsystem behavior and presentation readiness |
plugins/ |
Project-specific plugin integration, patches, and debugging |
debugging/ |
Reusable diagnosis procedures and verified failure investigations |
research/ |
Unaccepted investigations, alternatives, and experiments |
decisions/ |
Accepted architectural decisions and implementation seeds |
operations/ |
Build, release, deployment, and operational checks |
conventions/ |
Rules for writing, retrieving, validating, and publishing the wiki |
Choose the section by the page's primary owner and purpose. Link to related systems rather than copying a page into several sections. Add a nested folder when a subject has multiple pages or needs its own context map; avoid single-page folders unless the subject is expected to grow immediately.
Titles and links¶
Use a human-readable title in frontmatter and a matching level-one heading. Prefer relative Markdown links. Link to a section index when directing readers to a subject area and directly to a page when citing a specific contract or finding. Do not rely on raw filenames as prose.
When moving a page, use git mv, update wiki links, MkDocs navigation, tooling
manifests, and known references in related repositories in the same change.
Search both the old filename and old path before committing. Preserve a redirect
only when an external consumer cannot be updated atomically.
Status and document shape¶
Use the frontmatter and status vocabulary in the wiki implementation decision. New pages must be standardized. Legacy pages may retain their original body until reviewed, but their section index must describe whether they are active, historical, experimental, or pending verification.