Add a few readmes/files to direct AI agents around

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+Guidance for AI coding assistants working in this repository. 
+This file is the entry point — read it first. Topic-specific
+detail lives under [`Skills/`](Skills/) and is linked from the relevant section below.
+
+## What this project is
+
+Fling Engine is a cross-platform Vulkan game engine in C++, currently built as one
+CMake project with a `FlingEngine` library, a `Sandbox` game/editor, and a `FlingTests`
+Catch2 test target. See the root [README.md](README.md) for the project pitch and
+platform setup (Vulkan SDK, GLFW, etc.).
+
+## Build
+
+- First time in a fresh clone: `./Init.sh` (Linux) / `Init.bat` (Windows). This pulls
+  git submodules, builds/installs Catch2 locally, and configures CMake into `build/`.
+- Day to day: `./build-debug.sh`, `./build-release.sh`, or `./build-shipping.sh`, then
+  build with your generator (e.g. `cmake --build build --parallel`).
+- `-DDEFINE_SHIPPING=ON` strips dev-only code gated behind `#ifdef FLING_SHIPPING`.
+- Full detail: [`Skills/building.md`](Skills/building.md).
+
+## Tests
+
+- Tests use Catch2 3, target `FlingTests`, source under `FlingTests/src`.
+- Run the built binary directly, e.g. `./build/FlingTests/bin/FlingTests` on Linux
+  (see `.github/workflows/build.yml` for the exact per-platform paths).
+- Full detail, including how to add a new test file: [`Skills/testing.md`](Skills/testing.md).
+
+## Coding style
+
+- Canonical style doc: [`docs/CodingStyle.md`](docs/CodingStyle.md) — documentation
+  comment conventions (no `@brief`, no `/*!`), enforced by
+  `python3 scripts/check_comment_style.py`.
+- Layout/formatting is enforced by `.clang-format` at the repo root (run
+  `clang-format`, not manual formatting judgment).
+- Applies to first-party code only (`FlingEngine/`, `Sandbox/`, `FlingTests/`).
+  **Never edit code under `external/`** — it's vendored third-party code.
+- AI-assistant-focused summary and common pitfalls: [`Skills/coding-style.md`](Skills/coding-style.md).
+
+## Architecture / module layout
+
+- Current folder layout and the in-progress module split (Core, Graphics, Gameplay,
+  Resources, Editor) are documented in [`docs/BuildModules.md`](docs/BuildModules.md) —
+  read it before restructuring includes or CMake targets, it records locked decisions.
+- Orientation for where things live today: [`Skills/architecture.md`](Skills/architecture.md).
+
+## Contribution conventions
+
+- Branching: feature branches off `main`, PR back into `main` when done and tested.
+- CI (`.github/workflows/build.yml`) builds on Linux (GCC/Clang) and Windows
+  (MSVC/MinGW) and runs `FlingTests` plus the comment-style check on every PR —
+  make sure changes pass locally first.
+
+## For Claude Code specifically
+
+`CLAUDE.md` at the repo root imports this file directly (`@AGENTS.md`), so there is
+nothing Claude-specific to duplicate here.

CLAUDE.md

@@ -0,0 +1 @@
+See @AGENTS.md for project guidance (build, tests, coding style, architecture).

FlingEngine/Resources/inc/JsonArchive.h

@@ -15,6 +15,9 @@ namespace Fling
 		T& Value;
 	};
 
+	/**
+	 * Makes a Name Value Pair (NVP) which can be used to serialize as a JSON key/value.
+	 */
 	template<typename T>
 	NamedRef<T> MakeNVP(const char* name, T& value)
 	{

README.md

@@ -69,15 +69,15 @@ Notice the `-DDEFINE_SHIPPING` option is set to `ON`. This sets a definiton that
 #endif
 ```
 
-### Wanna contribute?
-
-If you have any contributions or fixes that you want to contribute, then feel free to open 
-an issue or a pull request! I'm happy to talk about the project, so feel free to reach out
-to me on [Twitter](https://twitter.com/BenjaFriend?lang=en) or here on GitHub.
-
 See [docs/CodingStyle.md](docs/CodingStyle.md) for documentation-comment conventions and
 how to run the comment-style check / clang-format. 
 
+## AI coding assistants
+
+If you're using Claude Code, Cursor, Copilot, or another AI coding assistant on this
+project, start at [AGENTS.md](AGENTS.md) — it covers build/test commands, coding
+style, and architecture, and links into [Skills/](Skills/) for topic-specific detail.
+
 ## Branching Strategy
 We use a pretty basic branching strategy. Make a feature branch off of `Main` for something like "add-support-for-x", and then that feature is done and tested create a pull request to get it into Main.
 

Skills/README.md

@@ -0,0 +1,16 @@
+# Skills
+
+Topic-specific guidance for AI coding assistants working in Fling Engine. Start at
+[`AGENTS.md`](../AGENTS.md) in the repo root — it links into the files here for
+detail on a given topic. These files are meant to be read on demand, not all at once.
+
+| File | Covers |
+|------|--------|
+| [`building.md`](building.md) | Init scripts, build modes, CMake flags, per-platform setup |
+| [`testing.md`](testing.md) | Running FlingTests, adding new Catch2 tests |
+| [`coding-style.md`](coding-style.md) | Doc-comment conventions, formatting, what not to touch |
+| [`architecture.md`](architecture.md) | Current folder/module layout, where new code belongs |
+
+These are supplementary to, not a replacement for, the canonical docs they
+reference (`docs/CodingStyle.md`, `docs/BuildModules.md`) — when in doubt, the
+canonical doc wins.

Skills/architecture.md

@@ -0,0 +1,41 @@
+# Architecture / where things live
+
+This is orientation for today's layout, not a design doc. For the in-progress
+module split (Core/Resources/Gameplay/Graphics/Editor as separate CMake targets)
+and its locked decisions, read [`docs/BuildModules.md`](../docs/BuildModules.md)
+before touching CMake targets, `FLING_ENGINE_INC()`, or cross-folder includes —
+several things that look like cleanups are explicitly deferred or ruled out there.
+
+## Today
+
+- `FlingEngine/` — the engine, currently one CMake library (`FlingEngine`) built
+  from almost every source file under this tree via glob. Subfolders already hint
+  at future module boundaries (`Core`, `Graphics`, `Gameplay`, `Resources`, `Utils`,
+  `Platform`, `Editor`, `Foundation`) but CMake/includes still treat it as one target
+  — `FLING_ENGINE_INC()` adds every engine `inc/` dir to consumers, so folder
+  location doesn't currently enforce isolation.
+- `Sandbox/` — the sample game + editor, one executable today (editor support is
+  toggled by a project-wide `WITH_EDITOR` define, which `docs/BuildModules.md`
+  plans to remove in favor of two separate executables).
+- `FlingTests/` — Catch2 tests, links the full `FlingEngine` library. See
+  [`testing.md`](testing.md).
+- `external/` — vendored third-party dependencies (submodules). Never modified.
+- `docs/` — human-facing docs; `docs/CodingStyle.md` and `docs/BuildModules.md`
+  are the two that matter for day-to-day work. (Most other files in `docs/` are
+  generated Doxygen HTML output, not hand-maintained.)
+- `scripts/` — repo tooling (`check_comment_style.py`, the one-time
+  `migrate_doxygen_comments.py` migration).
+- `CMake/` — CMake helper modules (e.g. `FlingEngineInc.cmake`).
+
+## Rules that hold regardless of the module-split's progress
+
+- Gameplay code (`Transform`, `Camera`, `World`, `Game`) must not include Graphics
+  headers (`MeshRenderer.h`, Vulkan-facing types). Graphics may include Gameplay.
+- Editor is a leaf: `Engine` and `Graphics` must not include `BaseEditor` or any
+  Editor header. If you find yourself adding such an include, that's the bug
+  `docs/BuildModules.md` calls out explicitly — look for the debug-UI hook pattern
+  it describes instead.
+- Don't add a new module folder or CMake target without reading the "Locked
+  decisions" section of `docs/BuildModules.md` first — several plausible-looking
+  approaches (per-module PCH, merging Foundation into something else, git
+  submodules per system) are explicitly rejected there.

Skills/building.md

@@ -0,0 +1,60 @@
+# Building Fling Engine
+
+## First-time setup
+
+Run once per fresh clone (or after `external/` submodule updates):
+
+```bash
+./Init.sh    # Linux/macOS
+Init.bat     # Windows
+```
+
+This does three things:
+
+1. `git submodule update --init --recursive` — pulls all vendored deps under `external/`.
+2. Builds and installs Catch2 locally to `external/Catch2/install` (no `sudo` needed;
+   `find_package(Catch2 3 REQUIRED)` in `FlingTests/CMakeLists.txt` needs this).
+3. Configures CMake into `build/` with default settings.
+
+Linux also needs system packages before this will configure cleanly (GLFW, Vulkan
+headers, X11/Wayland dev libs) — see the root [README.md](../README.md) for the
+`apt-get` list, or `.github/workflows/build.yml` for the CI package list.
+
+## Day-to-day builds
+
+Three convenience scripts reconfigure CMake for a given mode (they do **not**
+build — build separately):
+
+```bash
+./build-debug.sh      # -DCMAKE_BUILD_TYPE=Debug
+./build-release.sh    # -DCMAKE_BUILD_TYPE=Release
+./build-shipping.sh   # -DCMAKE_BUILD_TYPE=Release -DDEFINE_SHIPPING=ON
+```
+
+Then build with your generator, e.g.:
+
+```bash
+cmake --build build --parallel
+```
+
+## `DEFINE_SHIPPING`
+
+`-DDEFINE_SHIPPING=ON` sets `FLING_SHIPPING`, used in first-party code to strip
+dev-only paths:
+
+```cpp
+#ifdef FLING_SHIPPING
+// shipping-only behavior
+#else
+// dev behavior, verbose logging, etc.
+#endif
+```
+
+It also switches Asset paths from absolute (convenient for iterating without
+reconfiguring) to relative, so a shipped executable is portable.
+
+## CI reference
+
+`.github/workflows/build.yml` is the ground truth for exactly what gets built and
+with which flags across Linux GCC, Linux Clang, Windows MSVC (Debug + Release), and
+Windows MinGW64 — check it if a build works locally but fails in CI, or vice versa.

Skills/coding-style.md

@@ -0,0 +1,56 @@
+# Coding Style
+
+The canonical reference is [`docs/CodingStyle.md`](../docs/CodingStyle.md) — read
+that first. This file is a quick-reference summary plus the pitfalls an AI assistant
+is most likely to hit.
+
+Scope: first-party code only — `FlingEngine/`, `Sandbox/`, `FlingTests/`.
+**Never reformat, refactor, or "clean up" anything under `external/`** — it's
+vendored third-party code and is left alone, full stop.
+
+## Documentation comments
+
+- Modern Doxygen-style blocks, plain description first, no `@brief` line.
+- Never use `/*!` — always `/**`.
+- Only add `@param` / `@return` / `@see` when they say something the signature
+  doesn't already make obvious. Don't generate `@return float GetTimef`-style noise.
+
+```cpp
+/**
+ * Holds onto the command line arguments passed to this application.
+ *
+ * @param Argc  Number of arguments
+ * @param ArgV  Argument values
+ * @return True if successfully initialized
+ */
+bool Init(const int32 Argc, const char* ArgV[]);
+```
+
+Trivial members/accessors can use a one-line `/** ... */`.
+
+## Enforcement — check before considering work done
+
+- **Comment content**: `python3 scripts/check_comment_style.py` — rejects leftover
+  `@brief` / `/*!` in first-party sources. Run this after adding or editing any
+  doc comment.
+- **Layout/formatting**: `.clang-format` at the repo root. Run `clang-format`
+  rather than hand-formatting:
+
+  ```bash
+  find FlingEngine Sandbox FlingTests -type f \( -name '*.h' -o -name '*.hpp' -o -name '*.cpp' \) \
+    | xargs clang-format -i
+  ```
+
+  clang-format handles layout only — it does not check comment *content*, that's
+  what `check_comment_style.py` is for. Both checks run in CI
+  (`.github/workflows/build.yml`, `comment-style` job runs the Python script;
+  formatting is expected to already be clean going in).
+
+## Naming / conventions to preserve
+
+- Flat include names (`#include "Logger.h"`, not `#include "Core/Logger.h"`) are
+  intentional, even across the module split described in
+  [`docs/BuildModules.md`](../docs/BuildModules.md). Don't "fix" these to
+  path-qualified includes.
+- `pch.h` is being deleted per the module-split plan — don't add new `#include "pch.h"`
+  to public headers, and don't rely on it as a kitchen-sink include.

Skills/testing.md

@@ -0,0 +1,44 @@
+# Testing
+
+Fling Engine uses [Catch2 3](https://github.com/catchorg/Catch2) for first-party
+tests. The test target is `FlingTests`, built from `FlingTests/src`, and links the
+full `FlingEngine` library (plus `Foundation`), so tests can exercise real engine
+code, not just isolated units.
+
+## Running tests
+
+Build the `FlingTests` target as part of a normal build, then run the resulting
+binary directly:
+
+```bash
+# Linux
+./build/FlingTests/bin/FlingTests
+
+# Windows (path includes the build config)
+build\FlingTests\bin\<Debug|Release>\FlingTests.exe
+```
+
+Catch2's CLI flags work as usual, e.g. `./build/FlingTests/bin/FlingTests "[tag]"`
+to filter, or `--list-tests` to see everything.
+
+`Logs/` should exist before running (CI does `mkdir -p Logs` first) — the engine
+writes runtime logs there.
+
+## Adding a new test
+
+- Add a new `.cpp` under `FlingTests/src` (see existing files like
+  `ResourceTests.cpp`, `UtilsTests.cpp`, `RendererTests.cpp` for structure/naming).
+  `FlingTests/CMakeLists.txt` globs sources, so a new file is picked up automatically —
+  no CMake edit needed for a new test file, just re-run CMake configure if it doesn't
+  show up.
+- Use Catch2's `TEST_CASE` / `SECTION` macros; follow the coding-style rules in
+  [`coding-style.md`](coding-style.md) for any doc comments you add.
+- Prefer testing first-party engine code (`FlingEngine/`). Do not add tests that
+  exercise `external/` internals directly.
+
+## CI
+
+Every PR runs `FlingTests` on Linux (GCC + Clang) and Windows (MSVC Debug/Release +
+MinGW64) via `.github/workflows/build.yml`. A test that only passes on one platform
+is not done — check for platform-specific assumptions (path separators, endianness,
+float precision) before considering a new test finished.