built template

docs/tooling.md

@@ -0,0 +1,45 @@
+# Tooling details
+
+## Editor setup
+
+Open the new project root in your editor. `.editorconfig` defines UTF-8, LF, final newlines, no trailing whitespace, and four-column tabs for Lua/Luau. `stylua.toml` defines formatting; `.luaurc` sets strict analysis by default.
+
+The optional `.vscode` files recommend Luau Language Server, StyLua, and EditorConfig, associate both source extensions with Luau, and enable format-on-save. Install these extensions yourself. Ensure the editor and extensions can locate tools from `nix-shell`, for example by launching the editor from that shell. An already-running editor may retain its old environment.
+
+The editor configuration disables Rojo-based sourcemap autogeneration because Argon generates `sourcemap.json`. Run Argon with `--sourcemap` or run `tools/check.sh` before expecting instance-aware requires to resolve. Editor Roblox definitions are managed by the language-server extension; the CLI check supplies its own definitions explicitly.
+
+## Roblox definitions and analysis
+
+On first use, `tools/check.sh` downloads `globalTypes.d.luau` from luau-lsp into `.cache/`. This requires internet access. Later checks reuse the cached file. To use your own downloaded or pinned definitions, pass an absolute path:
+
+```sh
+ROBLOX_TYPES=/absolute/path/globalTypes.d.luau nix-shell --run 'bash tools/check.sh'
+```
+
+For reproducible CI, pin compatible tooling and the definitions revision together. The default download follows upstream `main`; refresh `.cache/globalTypes.d.luau` deliberately when upgrading tools. A nonempty cache is reused, so delete that file to fetch an updated copy. `ROBLOX_TYPES` replaces the source project's game-specific `PONG_ROBLOX_TYPES` name.
+
+The check command analyzes runtime source, then executes native tests. Runtime modules use Roblox instance requires, whereas standalone tests use relative file requires. Roblox services and globals such as `game`, `Instance`, and `Vector3` do not exist in the standalone runtime merely because the analyzer knows their types.
+
+## Test strategy
+
+Prefer pure modules for algorithms that can be tested directly with `luau`. `tests/numbers.luau` demonstrates this using the starter module. Add test files directly under `tests/` with a `.luau` extension for automatic execution by the check script. Organize more elaborate suites behind their own entry points when needed.
+
+Use Studio for engine behavior. If you need external integration tests, design explicit mocks and a loader for your own game's Roblox dependencies. The parent project's Lua mocks, Jolt integration harness, and declaration stubs are tied to its game and are intentionally not included here.
+
+## Optional Darklua / Lua 5.4 path
+
+The shell includes Darklua and Lua 5.4 to support the parent project's testing approach. `tools/darklua.json` removes types, if-expressions, compound assignments, and `continue`, producing readable output. This step is optional and is not part of the starter check script:
+
+```sh
+mkdir -p output
+nix-shell --run 'darklua process src output/lua -c tools/darklua.json'
+nix-shell --run 'lua -e '\''assert(_VERSION == "Lua 5.4")'\'''
+```
+
+Always transform into a separate generated directory. Studio runs the original strict Luau source. These transformations do not emulate Roblox, rewrite all instance-based requires, or guarantee compatibility for every Luau feature. Lua 5.4 tests need appropriate mocks, module loading, and compatibility helpers; native Luau is preferable when those adaptations are unnecessary.
+
+## Dependencies and future tools
+
+Place runtime dependencies in `Modules/Libraries/External` under the appropriate shared or server-only source tree; Argon already maps these directories. First-party libraries belong in `Modules/Libraries/Internal`. `.styluaignore` keeps third-party formatting intact. The type checker still analyzes source under `src`, including external libraries. If luau-lsp cannot analyze a dependency, add narrowly scoped declarations or an analysis strategy for that dependency; analysis stubs never replace its runtime implementation. Document versions and licenses. Wally or other package managers can be added later, but this template uses no dependency installer or generated package tree.
+
+This shell does not install Selene. StyLua checks formatting and luau-lsp checks types; add a linter and its Roblox configuration explicitly if desired. Keep builds, downloaded types, and sourcemaps out of source control. Commit the project mapping, source, tests, shell, and formatter settings.