Wreck Squad Wiki Implementation Seed

Decision

Build the Wreck Squad wiki as the private GitHub repository BrickLeaf/Wreck-Squad-Wiki, checked out directly at Tank Game/Docs and ignored by the parent Tank Game repository.

This is an intentionally independent nested checkout, not a Git submodule. The two repositories have separate commits and pull requests. Cross-repository changes reference one another by repository and commit or pull-request URL when traceability matters.

Markdown files and Git history are canonical. MkDocs Material is a replaceable human-facing view. Agents read and edit the repository directly with filesystem, search, and Git tools.

Why this differs from the generic seed

Tank Game already has a substantial Docs/ corpus and source-code references to paths beneath Docs/. Moving everything into another kb/ subtree would create churn without improving retrieval. The KB repository root therefore serves as the content root, preserving current paths.

The split is justified because the KB now covers Unreal gameplay code, UI, EOS, Nakama, Edgegap, deployment behavior, operational evidence, and cross-repository decisions. Independent history keeps documentation work reviewable without adding noise to large binary-heavy game commits.

Repository contract

• GitHub repository: https://github.com/BrickLeaf/Wreck-Squad-Wiki
• Visibility: private
• Default branch: main
• Local checkout: Tank Game/Docs
• Parent integration: /Docs/ is ignored by Tank Game Git
• Canonical content: Markdown and repository assets
• Presentation: MkDocs Material
• Editing: normal filesystem and Git workflows; no database or web editor requirement
• Generated site and search indexes are derived artifacts and are never authoritative

Do not convert this checkout into a submodule unless the team explicitly chooses mandatory revision pinning. The current design favors always-available local knowledge and independent documentation commits.

Information architecture

The initial corpus has been classified and moved into this hierarchy. The repository root is reserved for entry-point and repository support files:

architecture/
backend/
  nakama/
  edgegap/
multiplayer/
  house-lifecycle/
  selection/
  matchmaking/
  rehost/
gameplay/
  definitions/
  minions/
  networking/
ui/
plugins/
  patches/
debugging/
research/
decisions/
operations/
conventions/

Every mature section should have an index.md that explains scope, terminology, major relationships, and the best starting pages. An index is a context map, not a generated directory listing.

Future moves require a clear canonical scope and simultaneous updates to inbound wiki links, navigation, validation manifests, and known source references. The detailed rules live in conventions/naming-and-structure.md.

Page contract

Use ordinary Markdown with lightweight YAML frontmatter:

---
title: Human-readable title
summary: One or two sentences describing the page's durable value.
tags:
  - relevant-tag
status: active
updated: YYYY-MM-DD
---

Allowed status values:

• active: current authoritative project knowledge
• draft: incomplete and not yet authoritative
• experimental: an active experiment or provisional design
• deprecated: superseded; retain only when its history remains useful
• historical: evidence or context that does not describe current behavior

Paths remain the primary identity. Do not add UUIDs or mandatory ownership fields. Optional fields such as related_code, source_commit, or superseded_by are allowed only when they materially improve traceability.

Knowledge authority

When pages disagree, use this order:

1. Verified current runtime behavior and current source/backend implementation.
2. Active canonical KB pages describing that behavior.
3. Accepted ADRs for the reason behind a decision.
4. Experimental and research pages.
5. Historical or deprecated pages.

A contradiction is a documentation defect. Resolve it by updating the canonical page and marking or linking superseded material; do not leave competing active explanations.

Project-specific content boundaries

The KB should capture knowledge that cannot be recovered cheaply from one source file, including:

• LS, DS, EOS, Nakama, and Edgegap lifecycle contracts
• authority boundaries and immutable launch snapshots
• RPC ownership, idempotency, batching, rate limits, and abuse gates
• House freeze, matchmaking admission, travel, rehost, recovery, and reset behavior
• Unreal replication and PlayerState/PlayerController timing constraints
• UI transition gates across world travel
• failure symptoms, log signatures, causal diagnosis, and verified fixes
• deployment and operational rules that span Tank Game and Nakama repositories
• architectural decisions and rejected alternatives

Do not duplicate obvious declarations or generic Unreal documentation. Link to source when a durable explanation depends on it.

Never paste raw chat transcripts into the KB. Convert them into verified facts, decisions, constraints, or clearly labelled hypotheses. Logs may be referenced as evidence, but secrets, tokens, user identifiers, deployment credentials, and expiring local paths must not be committed.

Agent retrieval workflow

Agents should use progressive disclosure:

1. Read this repository's README.md.
2. Read the most relevant section index.
3. Search filenames and content with rg or equivalent.
4. Read only the likely canonical pages.
5. Follow related-page links and inspect Git history when provenance matters.
6. Compare against current code or runtime evidence before asserting unstable implementation details.

Agents should search before creating pages, update the canonical page when possible, and create a new page only for a substantial topic with an independent lifecycle or when the existing page would become hard to navigate.

Source and KB Git workflow

The source and KB repositories cannot share an atomic commit. For a change that affects both:

1. Update code and KB in their respective repositories.
2. Use focused commits in each repository.
3. Add reciprocal commit or pull-request links when ordering or traceability matters.
4. Never claim documentation is updated until the KB commit exists.

Preferred KB commit forms:

docs: document House launch admission lifecycle
docs: correct DS-to-LS rehost failure handling
adr: choose Nakama-authoritative House freeze roster

MkDocs implementation

Use MkDocs Material with a deliberately small configuration. Because the KB content remains at repository root, keep build tooling isolated under tooling/ and configure the content root explicitly rather than moving canonical pages.

Initial features:

• hierarchical navigation and section indexes
• page table of contents and breadcrumbs
• local full-text search
• syntax highlighting
• Mermaid diagrams
• tags
• dark/light palette
• repository edit/history links
• last-modified metadata when it can be derived reliably from Git

Provide reproducible commands for local setup, strict build, and mkdocs serve. Pin Python documentation dependencies in a small requirements file or lock file.

The generated site directory must be outside the canonical content tree or explicitly excluded from discovery and Git. Never commit generated HTML.

CI and publication

Use GitHub Actions to:

1. install pinned documentation dependencies;
2. run a strict MkDocs build;
3. validate internal links and frontmatter with lightweight checks;
4. deploy the static site to Cloudflare Pages from main.

CI retains the build artifact independently of deployment. Cloudflare Access is the intended authentication boundary; the initial public deployment is only a proof of concept. Deployment remains replaceable, and repository Markdown remains fully usable without the site.

Pull requests should fail for broken internal links, malformed required frontmatter on newly standardized pages, or MkDocs build errors. Legacy pages may be migrated progressively rather than blocking the initial import.

Migration policy

The current corpus is imported unchanged, including its useful Git working-tree edits. The initial repository commit establishes a lossless baseline plus the KB rules and this implementation seed.

After the lossless baseline, the first organization pass classified the corpus, created section maps, adopted lowercase kebab-case paths, and updated known links. Further migration remains progressive:

• classify existing pages as active, research, historical, or deprecated;
• add frontmatter when a page is substantively reviewed;
• maintain section indexes as pages move or change authority;
• split oversized backend pages only at stable responsibility boundaries;
• preserve redirects or update every known inbound reference when paths change.

backend/inventory-selection.md remains a broad backend reference. Focused pages such as multiplayer/house-lifecycle/launch-protocol.md own detailed lifecycle material and should be linked from the broad overview instead of repeatedly expanding it.

Explicit non-goals

Do not initially build:

• a wiki database or custom CMS
• browser WYSIWYG or realtime collaborative editing
• a custom MCP server
• embeddings or a vector database
• a graph database or elaborate ontology
• per-page ACLs
• automated content generation from chat logs
• large custom MkDocs themes or plugins without an observed need

Semantic indexes, backlinks, stale-page reports, and source-to-KB automation may be added only after normal filesystem search and section indexes demonstrate a concrete limitation. Any future index remains derived from Markdown.

Acceptance criteria for implementation

The first implementation is complete when:

• the standalone private repository is the only Git owner of Tank Game/Docs;
• Tank Game ignores the nested checkout;
• existing documents and local documentation edits are preserved;
• agents can find the House launch flow through the root and section indexes;
• a representative page can be found, edited, linked, committed, and reviewed without MkDocs;
• MkDocs serves locally and builds strictly in CI;
• internal link validation covers standardized pages;
• the site can deploy privately through GitHub Pages, or CI retains a build artifact when private Pages is unavailable;
• no generated site output or secret operational data is committed.