Repository layout: what belongs on GitHub

This page explains which directories are source, which are generated locally, and what never gets pushed. Goal: no confusion between docs/, site/, build/, venvs, optional local scratch trees, and vendored upstream trees.

Single sources of truth

What	Where	On GitHub?
Human-written documentation (MkDocs)	`docs/` (`mkdocs.yml` at repo root)	Yes — this is the doc source.
`VENDOR.md` (component revisions for CMake / `csr version`)	`VENDOR.md` at repo root (see also Vendor table (VENDOR.md))	Yes — required for builds and version strings.
Automation & CI	`.github/workflows/`	Yes — only this `.github` tree is CSRetro’s; see below.
Build / dev entry	`tools.sh` (repo root)	Yes

Generated or local-only (gitignored — not on GitHub)

Path	What it is	Safe to delete?
`site/`	MkDocs output from `mkdocs build` (HTML for GitHub Pages is produced in CI, not from your local `site/` folder).	Yes — regenerated anytime.
`build/`, `build-debug/`	CMake build trees.	Yes — use `./tools.sh build:clean`.
`game-test/`	Installed engine + `cstrike/` after `./tools.sh install:*` / `build:full`.	Yes — recreated by build/install.
`logs/`	Build and run logs.	Yes.
`docs/_upstream_mirror/` (if present)	Gitignored. Optional local scratch; do not commit upstream HTML dumps. Prefer storing comparison snapshots outside the repo.	Yes — delete anytime.
`.venv/`	Recommended Python virtualenv for MkDocs (`pip install -r requirements-docs.txt`).	Yes — recreate with `python3 -m venv .venv`.

Do not commit the paths above. They are listed in the repo root .gitignore.

Python environment (one venv name)

Use one venv at the repo root for documentation tooling:

python3 -m venv .venv
.venv/bin/pip install -r requirements-docs.txt

If you previously created a separate folder (e.g. .venv-docs/), delete it and use .venv/ only to avoid duplicate environments.

`.cursor/` — plans and rules vs local junk

Versioned in this repo: .cursor/plans/ (project plans) and .cursor/rules/ (shared editor rules for contributors).
Still ignored: other Cursor-only files under .cursor/ that are machine-specific.

So the Plans you care about live under .cursor/plans/ and are tracked when you commit — they are not “mystery duplicates” of docs/; docs/ remains the MkDocs documentation, plans are roadmaps / checklists.

Vendored upstream trees (`3rdparty/`, `engine/`, …)

Folders like 3rdparty/metamod/ or 3rdparty/nodemod/ are full upstream snapshots merged into CSRetro. They may contain their own .github/, CMakeLists.txt, or workflows from the original project. Those files are not CSRetro’s CI; they exist so merging future upstream updates stays diff-friendly.

Do not delete them without a tested sync strategy — see Architecture (section Vendor tree hygiene).

CSRetro’s own GitHub Actions live only under .github/workflows/ at the repository root.

Mental model

flowchart TB
  subgraph tracked [Committed to Git]
    docsMd[docs Markdown]
    mkdocsYml[mkdocs.yml]
    vendorMd[VENDOR.md]
    toolsSh[tools.sh]
    ghWorkflows[.github/workflows]
    cursorShared[.cursor plans and rules]
  end
  subgraph localOnly [Local only gitignored]
    siteOut[site output]
    buildDirs[build directories]
    gameTest[game-test]
    scratchDir[ignored scratch dirs]
    pyvenv[.venv]
  end
  docsMd --> mkdocsYml
  mkdocsYml --> siteOut