built template

docs/argon.md

@@ -0,0 +1,48 @@
+# Argon setup
+
+1. Install the Argon Studio plugin using the official [Argon documentation](https://argon.wiki/docs/intro). Enable it in Studio's Plugins tab. The Nix shell supplies the CLI; the Studio plugin is installed separately.
+2. Open a new or backed-up place in Studio. Set `name` in `default.project.json` to your game's name. The project tree defines which filesystem paths sync to which services.
+3. From the project root, start the server:
+
+   ```sh
+   nix-shell --run 'argon serve default.project.json --sourcemap'
+   ```
+
+4. In the Studio plugin, connect to the address and port printed by the CLI. Review the proposed changes before syncing. Allow any plugin permissions Studio requests for the connection. The starter owns its mapped instances; importing an existing place requires reconciling its instance tree with the filesystem first.
+5. Keep the command running while editing, and press Play in Studio to run the game. Stop play and restart clients/server after startup or protocol changes. Stop Argon with Ctrl+C when done.
+
+For different machines or a VM, configure a reachable host and port with `argon serve --host <address> --port <port>`. Use `argon serve --help` for your installed version's options. Use a trusted network and the printed port; a remote Studio instance cannot connect through its own `localhost` to another machine.
+
+## File conventions
+
+- `Name.server.lua` or `.server.luau` becomes a Script.
+- `Name.client.lua` or `.client.luau` becomes a LocalScript.
+- `Name.lua` or `.luau` becomes a ModuleScript.
+- A directory containing `init.lua` or `init.luau` becomes a ModuleScript with children. Otherwise it becomes a Folder. Script variants such as `init.server.lua` set the corresponding script class.
+
+For example, require the shared example as `require(ReplicatedStorage.Modules.Libraries.Internal.Numbers)`. Require a third-party module as `require(ReplicatedStorage.Modules.Libraries.External.Vendor)`. Filesystem-relative requires in native Luau tests are separate from Roblox instance-based requires in runtime code.
+
+## Sourcemaps and builds
+
+The sourcemap connects filesystem source to Roblox instance paths for luau-lsp; it is not runtime code. `--sourcemap` updates it while serving. Generate it without Studio with:
+
+```sh
+nix-shell --run 'argon sourcemap default.project.json --output sourcemap.json'
+```
+
+The check script runs this automatically. Generated maps are ignored by Git. Rebuild the map when adding, moving, or deleting modules; stale maps can cause incorrect require diagnostics.
+
+To build a local place artifact:
+
+```sh
+mkdir -p output
+nix-shell --run 'argon build default.project.json --output output/MyGame.rbxlx'
+```
+
+Building is separate from publishing to Roblox. Use Studio to inspect, playtest, and publish the resulting place.
+
+## Adding packages or services
+
+Put third-party runtime code in `src/ReplicatedStorage/Modules/Libraries/External/<Vendor>/`, retaining its license. Put your own reusable modules in `src/ReplicatedStorage/Modules/Libraries/Internal/`. For server-only libraries, use the equivalent directories under `src/ServerStorage/Modules/Libraries/`. These directories are already mapped, so no additional project entries are needed. A vendor's `init.lua` or `init.luau` becomes its module entry point. Import the runtime source rather than an entire vendor repository with tooling and examples. Do not run two sync sessions that own the same instances. `.styluaignore` excludes external libraries from first-party formatting commands.
+
+To add file-based UI or other services, add the corresponding directory and `$path` mapping. Avoid copying game-specific device orientation, mouse lock, assets, or package mounts into every new game; choose those per project.

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.