cluaupp 1.5.2 → 2.0.0-beta.1

package/scripts/postinstall-native.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const https = require("node:https");
+
+const pkg = require("../package.json");
+const root = path.resolve(__dirname, "..");
+const exe = process.platform === "win32" ? "cluaupp.exe" : "cluaupp";
+const outDir = path.join(root, "native", "bin");
+const outFile = path.join(outDir, exe);
+
+if (process.env.CLUAUPP_INSTALL_NATIVE !== "1") {
+	process.exit(0);
+}
+
+if (fs.existsSync(outFile)) {
+	process.exit(0);
+}
+
+if (process.env.CLUAUPP_SKIP_NATIVE_DOWNLOAD === "1") {
+	console.log("cluaupp: native download skipped by CLUAUPP_SKIP_NATIVE_DOWNLOAD=1");
+	process.exit(0);
+}
+
+const version = String(pkg.version || "0.0.0");
+const fileName = `cluaupp-${version}-${process.platform}-${process.arch}${process.platform === "win32" ? ".exe" : ""}`;
+const url = `https://github.com/KartzRbx/Cluaupp/releases/download/v${version}/${fileName}`;
+
+fs.mkdirSync(outDir, { recursive: true });
+
+https
+	.get(url, (res) => {
+		if (res.statusCode !== 200) {
+			console.warn(`cluaupp: native binary not found for ${process.platform}-${process.arch} (${res.statusCode}), fallback to Node runtime`);
+			res.resume();
+			return;
+		}
+		const file = fs.createWriteStream(outFile, { mode: 0o755 });
+		res.pipe(file);
+		file.on("finish", () => {
+			file.close(() => {
+				if (process.platform !== "win32") {
+					try {
+						fs.chmodSync(outFile, 0o755);
+					} catch {
+						// ignore chmod errors
+					}
+				}
+				console.log(`cluaupp: native installed at ${path.relative(root, outFile)}`);
+			});
+		});
+	})
+	.on("error", (err) => {
+		console.warn(`cluaupp: native download failed (${err.message}), fallback to Node runtime`);
+	});

package/skills/README.md

@@ -1,13 +1,13 @@
 # CL++ agent skills
 
-Cursor skills that teach the agent how to write CL++ and Cluaupp schemas.
+Cursor skills that teach the agent how to write CL++ on the **Cluaupp Roblox target** (`.clp`, `link`, top-level scripts).
 
 `cluaupp init` copies this folder to `.cursor/skills/` in the game.
 
 | Skill | When |
 | --- | --- |
-| `clpp-language` | `.clpp` / `.clh` / schemas, compile, accessors |
+| `clpp-language` | `.clp` / schemas, `link`, compile, accessors |
 | `clpp-style` | professional layout, named callbacks, no leftover diagnostics |
 | `clpp-hive-flare` | Hive ECS + Flare packets, server authority |
 
-CL++ highlighting still comes from `clpp setup`. Schema highlighting (`.hive`, `.flare`, …) comes from `cluaupp intellisense`.
+Syntax highlighting: CL++ (`clp`) via the Cluaupp/CL++ extension. Schema files (`.hive`, `.flare`, …) via `cluaupp intellisense`.

package/skills/clpp-hive-flare/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: clpp-hive-flare
-description: Design server-authoritative systems with Hive ECS and Flare packets. Use when editing .hive, .flare, CombatServer, CombatClient, hitboxes, AttackIntent, or when the user mentions Hive, Flare, ECS, snapshot, or hitbox.
+description: Design server-authoritative systems with Hive ECS and Flare packets. Use when editing .hive, .flare, combat services, hitboxes, AttackIntent, or when the user mentions Hive, Flare, ECS, snapshot, or hitbox.
 ---
 
 # Hive + Flare
 
-Server writes Hive columns and owns gameplay. Client sends intent and plays visuals.
+Server writes Hive columns and owns gameplay. Client sends intent and plays visuals. **Ward** gates inbound client buffers.
 
 ## Schema
 
-`.hive`:
+`src/ReplicatedStorage/Shared/PlayerECS.hive`:
 
 ```
 opt name = PlayerECS
@@ -21,7 +21,7 @@ component Combo { i32 stage }
 component Alive { i32 flag }
 ```
 
-`.flare`:
+`src/ReplicatedStorage/Shared/Net.flare`:
 
 ```
 opt name = Net
@@ -32,48 +32,52 @@ packet CombatHello(i32 entityId, i32 health) from Server
 packet HitResult(Player attacker, Player victim, i32 damage, i32 combo) from Server
 ```
 
-Do not edit generated `.clh`. Change the schema and rebuild.
+Edit schemas, run `cluaupp build`, then `link` the generated modules — do not hand-edit `out/` Luau.
 
 ## Authority
 
-- One `Schema.New()` on the **server** struct.
-- Map `Player → entity` with `Roster` (`Roster.New()`). Do not write `new Roster()` — CL++ emits `Instance.new("Roster")` and Studio crashes.
-- Allocate ids with `NextEntity` (see clpp-language compiler notes).
-- Client never `Set`s Hive columns. Client stores replica fields from server packets.
+- One `PlayerECS.New()` (or generated name) on the **server**.
+- Map `Player → entity` with `Roster`.
+- Allocate ids with `NextEntity` (see [compiler.md](../clpp-language/compiler.md)).
+- Client never `Set`s authoritative Hive columns; mirror from server packets.
 - `Ward.Allow(player, channel, rate, burst)` on every attack remote.
 
 ## Hitbox
 
 On each accepted click:
 
-1. Client `AttackIntent.FireServer()` then spawn local Part with `CanTouch = false`.
+1. Client `Net.AttackIntent.FireServer()` then spawn local Part with `CanTouch = false`.
 2. Server validates alive + cooldown + Ward, advances combo, spawns Part with `CanTouch = true`.
-3. `Touched` lambda only calls `@this.OnHitboxTouched(...)`.
-4. `OnHitboxTouched` resolves a player victim, dedupes with `Roster`, then `ApplyHit`.
-5. `ApplyHit` writes Hive Health, assigns `humanoid.Health`, `HitResult.FireAll`.
+3. `Touched ~>` lambda only calls `@this.OnHitboxTouched(...)`.
+4. `OnHitboxTouched` resolves victim, dedupes with `Roster`, then `ApplyHit`.
+5. `ApplyHit` writes Hive Health, assigns `humanoid.Health`, `Net.HitResult.FireAll(...)`.
 
 Destroy hitboxes with `spawn { task::wait(life); hitbox.Destroy(); }`.
 
 ## Handshake
 
-Client `init`: construct the struct, init fields, bind input, `CombatReady.FireServer()`.
-Server `OnReady`: ensure fighter row, `CombatHello.Fire(player, entity, health)`.
+Client boot (`*.client.clp`): `link` Net, bind input, `Net.CombatReady.FireServer()`, listen for `Net.CombatHello`.
 
-## Includes
+Server boot (`*.server.clp`):
 
-Server header may include `"ReplicatedStorage/Shared/Net/Net.clh"` and the generated Hive header.
+```clp
+link @clpp.roblox;
+link @ReplicatedStorage.Shared.Net as Net;
+link @ReplicatedStorage.Shared.PlayerECS as PlayerECS;
 
-Client compiling script includes Net itself:
-
-```clpp
-#include "ReplicatedStorage/Shared/Net/Net.clh"
-#include "../../../ReplicatedStorage/Shared/Services/Combat/CombatClient.clh"
+Net.CombatReady ~> func (Player player) {
+	<< ensure fighter row, Net.CombatHello.Fire(player, entityId, health);
+};
 ```
 
-After `cluaupp build`, client Luau must read:
+## Links
 
-```luau
-const Net = require(ReplicatedStorage.Shared.Net.Net)
+```clp
+link @clpp.roblox;
+link @ReplicatedStorage.Shared.Net as Net;
+link @ReplicatedStorage.Shared.PlayerECS as PlayerECS;
+link @clpp.libs.hive as Hive;
+link @clpp.libs.ward as Ward;
 ```
 
-If it still says `script.Parent.Parent.Parent.Parent.ReplicatedStorage`, Play will error `ReplicatedStorage is not a valid member of Players`.
+After `cluaupp build`, client Luau must `require` via `ReplicatedStorage` paths — not `script.Parent…Players.ReplicatedStorage`. Cluaupp postprocess rewrites bad chains; if `out/` still shows a broken path, fix the `link` and rebuild.

package/skills/clpp-language/SKILL.md

@@ -1,59 +1,82 @@
 ---
 name: clpp-language
-description: Write valid CL++ (Cluaupp) that compiles to Luau. Always rebuild and fix unused-parameter and compile errors until cluaupp build is clean. Use when editing .clpp, .clh, .clp, .hive, .flare, .mint, .bloom, .helm, .shift, or .axiom files, compiling with cluaupp/clpp, or when the user mentions CL++, Cluaupp, Hive, or Flare.
+description: Write valid CL++ on the Cluaupp Roblox target (.clp, link-only, top-level scripts). Always rebuild until cluaupp build is clean. Use when editing .clp, .hive, .flare, .mint, .bloom, .helm, .shift, .axiom, compiling with cluaupp, or when the user mentions CL++, Cluaupp, Hive, or Flare.
 ---
 
-# CL++ language
+# CL++ on Cluaupp (Roblox target)
 
-CL++ **0.8+** is C++-inspired source that `clpp` emits as Luau. Cluaupp orchestrates Rojo, includes, Hive, and Flare. There is no `int main()`. Scripts enter at `void init()`.
+**CL++ 0.10** is the language. **Cluaupp** in this repo parses `.clp`, checks Roblox APIs, and emits Luau + Rojo. There is no `int main()` and **no `void init()`** on the Roblox target — entry scripts run **top-level** code when they load.
 
-Read [compiler.md](compiler.md) before using Hive `Entity` / `Has` / `Despawn`, `Humanoid.TakeDamage`, `Vector3::new`, or `namespace`.
+Read [compiler.md](compiler.md) before Hive `Entity` / `Has` / `Despawn`, `Humanoid.TakeDamage`, `Vector3::new`, or legacy emit quirks.
 
 ## Files
 
 | Source | Runtime |
 | --- | --- |
-| `*.server.clpp` | Script |
-| `*.client.clpp` | LocalScript |
-| untagged `.clpp` / `.clp` | ModuleScript — do not put `init()` unless require should run it |
-| `.clh` in `src/` | types/modules; prefer `import { } from` |
-| `#include <clpp/...>` | IntelliSense only; emits `CluauppLibs` require |
-| `.flare` `.hive` `.mint` `.bloom` `.helm` `.shift` `.axiom` | schemas; do not edit the generated `.clh` |
+| `*.server.clp` | Script |
+| `*.client.clp` | LocalScript |
+| untagged `*.clp` under `src/ReplicatedStorage/…` | ModuleScript — shared `func` and constants |
+| `.flare` `.hive` `.mint` `.bloom` `.helm` `.shift` `.axiom` | schemas; edit schema, run `cluaupp build` |
 
-Entry scripts: `#pragma strict` then imports/includes then functions then `void init()`.
-Headers: `#pragma once`, structs, field defaults, method prototypes. Bodies live in `.clpp`.
+Default tree: `cluaupp init` → `templates/game-modern` with `rootDir: "src"` in `cluaupp.config.json`.
 
-## Accessors (law)
+Legacy `.clpp` / `.clh` / `#include` / `import { } from` may still exist in old games — **do not** use them in new Roblox code.
+
+## Modules (`link` only)
+
+```clp
+link @clpp.roblox;
+link @clpp.libs.ward as Ward;
+link @clpp.libs.keep as Keep;
+link @ReplicatedStorage.Shared.CombatRules as CombatRules;
+link @ReplicatedStorage.Shared.Net as Net;
+```
+
+- `@clpp.roblox` — prelude / engine bindings
+- `@clpp.libs.<name>` — CluauppLibs (`require(ReplicatedStorage.CluauppLibs.*)`)
+- `@ReplicatedStorage…` / `@ServerScriptService…` — project modules (Rojo paths)
+
+No `export` keyword — top-level declarations are the module API. Cycles → diagnostic.
+
+Desktop-only links (`@clpp.window`, `@clpp.gfx`, `@clpp.gui`) are **rejected** on the Roblox target.
+
+## Script body
+
+```clp
+link @clpp.roblox;
+link @clpp.libs.sweep as Sweep;
+
+Sweep life = Sweep.New();
+Players players = GetService<Players>();
+
+players.PlayerAdded ~> func (Player player) {
+	life.LinkToInstance(player.Character);
+};
+```
+
+Use `@server` / `@client` / `@parallel` on `func` when one file mixes contexts (rare — prefer separate `.server.clp` / `.client.clp`).
+
+Comments: prefer `<<` (CL++ 0.10 parity). `//` may parse; do not teach it in new code.
+
+## Accessors
 
 CL++ has no `->`. Instances are `Player player`, never `Player*`.
 
 | Write | Meaning |
 | --- | --- |
-| `player.Name` / `player.Kick()` | property / instance method (`.` still passes self) |
-| `player:Kick()` | protected `pcall` form — do not use as normal method call |
-| `task::wait` / `Class::Method` | static, method definition, call on the struct table |
-| `signal~>Connect(fn)` | Sweep janitor Connect |
+| `player.Name` / `player.Kick()` | property / instance method |
+| `player:Kick()` | protected `pcall` — not normal calls |
+| `task::wait` / `Class::Method` | static / method definition |
+| `signal ~> handler` | connect (often Sweep-owned) |
 | `"hi " .: name` | concat |
 | `expr?` | Result try (not optional chaining) |
-| `Enum.UserInputType.MouseButton1` | enum |
-| `@this` / `@World` / `@janitor` | receiver / field **inside** `Class::Method` only, never in `init()` |
+| `@this` / `@janitor` | receiver / field **inside** `Class::Method` only |
 
 Lambdas: `func (Player player) { }`. Not `[]() {}`.
 
-## Modules
-
-```clpp
-import { Wallet } from "./PlayerData.clh";
-import { PlayerData as Data } from "./PlayerData.clh";
-```
-
-No `export` keyword — top-level is importable. Angle `#include <clpp/…>` is host only. Cycles → CLPP1001.
-
-Cluaupp host: resolves imports for Rojo/`require`, AUTH001, project graph, and incremental cache deps (`src/clpp/modules.ts`). Prefer `import` for app modules; keep `#include <clpp/libs/…>` for CluauppLibs.
-
 ## Option / Result
 
-```clpp
+```clp
 Result<int, string> r = Ok(1);
 int n = r?;
 match (r) {
@@ -63,61 +86,31 @@ match (r) {
 optional<int> o = Some(1);
 ```
 
-CLPP0202 = Result→plain assign. CLPP1101 = `?` on non-Result. CLPP1102 = non-exhaustive match.
-
-## Constructs to use
-
-```clpp
-guard (player) else {
-	return;
-}
-
-spawn {
-	task::wait(0.18);
-	hitbox.Destroy();
-};
-
-for (Player player in players.GetPlayers()) {
-	@this.RegisterFighter(player);
-}
-
-Part hitbox = new Part(workspace);
-Vector3 size = Vector3(5, 6, 4);
-CFrame offset = CFrame(0, 0, -3.2);
-Color3 color = Color3(1, 0.25, 0.2);
-Players players = GetService<Players>();
-```
+## Services
 
-## Constructs that do not exist
+`GetService<T>()` is **Cluaupp Roblox Target** (registry, Context Safety, `CLUAU_SVC001`) — use `link @clpp.roblox;` first. Do not write `game:GetService` in `.clp`.
 
-`namespace` (use `struct`), `->`, `do/while`, C++ `try/catch` (use Result/`?` or `pcall`), `goto`, `Player*`, ISO `std::`, C++ captures `[&]`, invented `export` keyword.
+## Constructs that do not exist (Roblox target)
 
-`wait()` as a free function is unreliable — use `task::wait` inside `spawn { }`.
-`delay(n, fn)` is unreliable — use `spawn { task::wait(n); ... }`.
+`#include`, `import { } from`, `void init()` as entry, `.clh` headers as the module system, `namespace` (use `struct`), `->`, C++ `try/catch` (use Result/`?`), `Player*`, invented `export`.
 
-Reserved Intent (do not teach as shipped): `requires`, `ensures`, `effect`, `newtype`, `unique`, `move`.
+`wait()` as a free function is unreliable — `task::wait` inside `spawn { }`.
 
 ## Types and init
 
-Prefer `auto` only for `FindFirstChild` / `FindFirstChildWhichIsA` results and Hive worlds (`auto World = PlayerECS.New()`). Method parameters and other struct fields always have a named type (`InputObject`, `Player`). Do not type fields as `HiveWorld` — that name is an IntelliSense stub and is not imported into the generated module. Initialize every field: `int coins = 0;`, never `int coins;`.
-`null` is Luau `nil`.
-`post` / `warn` / `report` → print / warn / error.
+Initialize every local and field: `int coins = 0;`. Method parameters need named types (`InputObject`, not bare `auto` except documented cases). `null` is Luau `nil`. `post` / `warn` / `report` → print / warn / error.
 
-## Includes
+## Flare / Hive generated API
 
-- Prefer `import { Name } from "./X.clh"` for language deps
-- Quoted path from **src root** for generated modules: `#include "ReplicatedStorage/Shared/Net/Net.clh"`
-- Relative quoted `.clh` next to the script: `#include "CombatServer.clh"` (legado / same-stem splice)
-- Never quoted-include Net/Hive generated headers from a Shared `.clh` that a LocalScript also includes — the require path follows the compiling file
-- Library: `#include <clpp/libs/ward.clh>` in the **compiling** `.clpp` if the runtime require must appear in that script
+Edit `src/ReplicatedStorage/Shared/*.flare` or `*.hive`, then `cluaupp build`. Gameplay uses `link @ReplicatedStorage.Shared.Net as Net` (names follow schema `opt name = …`). Do not hand-edit generated `out/` Luau.
 
 ## Fix until clean
 
-After writing CL++, run `cluaupp build`. Unused parameters, bad includes, and type errors are blockers — change the code until the compiler is silent. Nested `func` captures do not count as uses; see [compiler.md](compiler.md).
+Run `cluaupp build`. Unused parameters, bad `link`, and type errors are blockers. Nested `func` captures do not count as uses — see [compiler.md](compiler.md).
 
 ## Layout
 
-- Server systems: `src/ServerScriptService/Services/`
-- Client controllers: `src/StarterPlayer/StarterPlayerScripts/Controllers/`
-- Shared types/schemas: `src/ReplicatedStorage/Shared/`
-- If it needs `DataStoreService`, it is server. If it needs `UserInputService`, it is client.
+- Server: `src/ServerScriptService/`
+- Client: `src/StarterPlayer/StarterPlayerScripts/`
+- Shared: `src/ReplicatedStorage/Shared/`
+- DataStore / authoritative logic → server. `UserInputService` / billboards → client.

package/skills/clpp-language/compiler.md

@@ -1,10 +1,10 @@
-# CL++ compiler workarounds
+# Cluaupp compiler workarounds
 
-These are emit bugs, not style. Prefer the workaround until `clpp` generates a colon call.
+These are emit/checker quirks, not style. Prefer the workaround until the compiler fixes the root cause.
 
 ## Hive
 
-`World.Entity()`, `World.Has(...)`, `World.Despawn(...)` often emit `.Entity()` / `.Has()` / `.Despawn()` (no self).
+`World.Entity()`, `World.Has(...)`, `World.Despawn(...)` may emit without `self`.
 
 | Need | Write |
 | --- | --- |
@@ -12,73 +12,61 @@ These are emit bugs, not style. Prefer the workaround until `clpp` generates a c
 | membership | `auto value = @World.Get(entity, Comp); if (!value) return;` |
 | despawn | `@World.Remove(entity, Comp);` per component |
 
-`PlayerECS.New()` is authoritative. Only the server writes columns. Client worlds do not spawn rows.
+`PlayerECS.New()` is authoritative on the server. Client worlds do not spawn authoritative rows.
 
-Generated `PlayerECS.clh` may contain `namespace PlayerECS`. Do not copy that into hand-written `.clh`. Use the generated names as `PlayerECS.Health`.
+Use generated schema types (`PlayerECS.Health`) from `link @ReplicatedStorage.Shared.PlayerECS as PlayerECS;` — do not invent a `HiveWorld` field type unless the checker already knows it.
 
 ## Roblox instances
 
-`humanoid.TakeDamage(n)` may emit without colon. Write `humanoid.Health = currentHealth;`.
+`humanoid.TakeDamage(n)` may emit without colon. Prefer `humanoid.Health = currentHealth;`.
 
-`Vector3::new(x, y, z)` fails semantic check. Write `Vector3(x, y, z)`. Same for `CFrame(...)` and `Color3(...)`.
+`Vector3::new(x, y, z)` may fail semantic check. Write `Vector3(x, y, z)`. Same for `CFrame(...)` and `Color3(...)`.
 
-Player-local hitbox offset is CFrame multiply, not LookVector math and not `ToWorldSpace` in source:
+Player-local hitbox offset:
 
-```clpp
+```clp
 return rootPart.CFrame * CFrame(0, 0, @HITBOX_FORWARD);
 ```
 
-Native CL++ still emits `.ToWorldSpace(` without colon (`self` becomes the offset at world origin). Cluaupp postprocess rewrites that to `:ToWorldSpace(`. Prefer `*` in source.
-
 Cluaupp reindents emitted Luau (tabs). Do not hand-fix `out/` indent.
 
-`~>` Connect: Cluaupp hoists the method Sweep to `self.janitor` (one per controller). Hitbox/player binds `LinkToInstance` so they die with that instance. Do not add a second `new Sweep()` next to `~>`.
+`~>` Connect: Cluaupp hoists the method Sweep to `self.janitor` where applicable. Instance binds should `LinkToInstance` so they die with that instance.
 
 ## Flare
 
-`FireAll` on generated packets is a function on the packet table (`api.FireAll`), so `.FireAll(...)` is correct.
-
-`Fire` / `FireServer` take self — `.Fire(player, ...)` is the CL++ instance-method form.
-
-Connect packets with Sweep: `Net.AttackIntent~>Connect(func (Player player) { @this.OnAttack(player); });`
+Generated packets: `Net.Hit.FireServer(...)`, server `Net.Hit ~> func (Player player, …) { }`, queries `Net.GetCoins.On` / `Net.GetCoins.Invoke()`.
 
-`clpp` emits `require(script.Parent.Parent...ReplicatedStorage.Shared.Net.Net)`. Under `PlayerScripts` that path is `Players.ReplicatedStorage` and crashes. Cluaupp postprocess rewrites those requires to `require(ReplicatedStorage.Shared...)`. After a build, client files must show `game:GetService("ReplicatedStorage")`, never a `script.Parent` chain into `ReplicatedStorage`.
+`clpp` legacy emit may use `script.Parent…ReplicatedStorage` requires. Cluaupp postprocess rewrites to `ReplicatedStorage` paths. After build, client `out/` must not walk into `Players.ReplicatedStorage`.
 
-Do not put `table.pack(...)` inside a nested `function()` in Flare — `...` is only valid in the vararg function. Pack first, then `pcall`.
+Do not put `table.pack(...)` inside a nested `function()` in generated Flare glue — `...` is only valid in the vararg function.
 
 ## Callbacks
 
-Keep `func (...) { }` as a one-line dispatch to a named `Class::Method`. Business logic belongs in the method so `@this` and fields work.
+Keep `func (...) { }` as a one-line dispatch to a named `Class::Method` or top-level `func`. Business logic belongs there so `@this` and fields work.
 
-Call other methods with a dot on the receiver. `@Name(...)` emits `pcall` (`self:Name`) and hides errors.
-
-```clpp
-hitbox.Touched~>Connect(func (BasePart hitPart) {
+```clp
+hitbox.Touched ~> func (BasePart hitPart) {
 	@this.OnHitboxTouched(hitPart, attacker, attackerCharacter, attackerEntity, struckPlayers);
-});
+};
 ```
 
-## Struct export types
-
-`auto` on a method parameter emits a nameless type (`input,` with no annotation). Use a real type: `InputObject input`, never `auto input`.
-
-`const void Method();` emits `(self: T),` — invalid Luau, missing `-> ()`. Declare procedures as `const bool Method();`, `return false` on guard failure, `return true` at the end.
+## Struct / export types
 
-Uninitialized fields emit `nil` in the constructor. Write `int ComboStage = 0;`, never `int ComboStage;`.
+`auto` on a method parameter may emit a nameless type. Use `InputObject input`, not `auto input`.
 
-`auto World` emits `World: any`. Do **not** type the field as `HiveWorld` — that name is only an IntelliSense stub in `hive.clh`. It is not imported into the generated module.
+Uninitialized fields emit `nil` in constructors. Write `int ComboStage = 0;`.
 
-Construct with `Roster.New()`. Do not write `new Roster()` — CL++ emits `Instance.new("Roster")`, which is not a Roblox class. Cluaupp also rewrites leftover `Instance.new("Roster")` to `Roster.new()`.
+Construct with `Roster.New()` / `Sweep.New()` — not `Instance.new("Roster")`. Cluaupp rewrites common mistakes in postprocess.
 
 ## Unused parameters
 
-A name used only inside `func () { }` is unused. The compiler still flags it. Bind it in the outer `guard` (or assign it to a field) so the diagnostic disappears. Do not ignore unused errors.
+A name used only inside `func () { }` is unused. Bind it in the outer `guard` (or assign to a field) so the diagnostic clears.
 
 ## Multiline return
 
 Do not write `return (` across lines. Split into locals:
 
-```clpp
+```clp
 bool isMouse = input.UserInputType == Enum.UserInputType.MouseButton1;
 bool isTouch = input.UserInputType == Enum.UserInputType.Touch;
 return isMouse || isTouch;
@@ -86,4 +74,4 @@ return isMouse || isTouch;
 
 ## Verify
 
-After every edit run `cluaupp build`. If it fails, fix the source and build again. Do not leave unused-parameter, type, or include errors visible. Open the matching `out/**/*.luau` and confirm `require` paths and `:` method calls.
+After every edit run `cluaupp build`. Open matching `out/**/*.luau` and confirm `require` paths and `:` method calls.

package/skills/clpp-style/SKILL.md

@@ -1,32 +1,32 @@
 ---
 name: clpp-style
-description: Write professional CL++ with small named functions, semantic identifiers, header/script split, and named callbacks. Always fix compiler diagnostics (unused parameters, types) instead of leaving them on screen. Use when refactoring .clpp/.clh, organizing combat or services, extracting lambdas, or when the user asks for código profissional, boa conduta, nomenclatura, or organização.
+description: Write professional CL++ with small named functions, semantic identifiers, top-level boot scripts, and named callbacks. Always fix compiler diagnostics instead of leaving them on screen. Use when refactoring .clp, organizing combat or services, extracting lambdas, or when the user asks for código profissional, boa conduta, nomenclatura, or organização.
 ---
 
-# CL++ professional style
+# CL++ professional style (Roblox target)
 
-Apply this whenever writing or refactoring CL++.
+Apply whenever writing or refactoring `.clp` for Cluaupp.
 
 ## Conduct
 
 1. Initialize everything. `int comboStage = 0;`, never an uninitialized local.
 2. Small functions. One behavior, named after the behavior.
-3. No magic numbers. `const float HITBOX_LIFE = 0.18;` on the struct.
+3. No magic numbers. `const float HITBOX_LIFE = 0.18;` next to the struct or file scope.
 4. Early return. `guard (cond) else { return; }` — no nested pyramids.
-5. Headers declare, scripts define. Prototypes in `.clh`, bodies in `.clpp`.
-6. Do not share mutable statics across server and client. Net or Keep, never a shared writeable singleton.
-7. Procedures are `const bool`, never `const void` — void emits a broken Luau function type. Parameters always have a named type (`InputObject`, not `auto`).
+5. **One concern per file.** Shared APIs live in untagged `src/ReplicatedStorage/…/*.clp`; boot and wiring live in `*.server.clp` / `*.client.clp` with top-level statements (no `void init()`).
+6. Do not share mutable statics across server and client. Net, Keep, or Flare — never a shared writeable singleton.
+7. Procedures return `bool` when you need a Luau-callable shape; parameters always have a named type (`InputObject`, not `auto`).
 
 ## Callbacks
 
-Never put combat/network logic inside `func () { }`.
+Never put combat/network logic inside anonymous `func () { }` bodies.
 
-The lambda only forwards to a named method. Call methods as `@this.Name(...)` (dot). `@Name(...)` emits a `pcall` and swallows errors.
+The lambda only forwards to a named function or method. Call methods as `@this.Name(...)` (dot). `@Name(...)` emits a `pcall` and swallows errors.
 
-```clpp
-hitbox.Touched~>Connect(func (BasePart hitPart) {
+```clp
+hitbox.Touched ~> func (BasePart hitPart) {
 	@this.OnHitboxTouched(hitPart, attacker, attackerCharacter, attackerEntity, struckPlayers);
-});
+};
 ```
 
 Name event handlers `On` + event: `OnAttack`, `OnHitboxTouched`, `OnCharacterSpawned`, `OnReady`.
@@ -41,55 +41,42 @@ Name factories `Create` / `Spawn` / `Resolve` / `Try`.
 | method | PascalCase verb | `ResolveVictim`, `AdvanceCombo` |
 | local / param | camelCase, role-first | `attackerEntity`, `hitPart`, `struckPlayers` |
 | constant | SCREAMING_SNAKE | `ATTACK_INTERVAL`, `MAX_HEALTH` |
-| player refs | role | `attacker`, `victim`, `player` — not `p`, `plr`, `currentPlayer` unless needed |
+| player refs | role | `attacker`, `victim`, `player` |
 | Hive ids | `*Entity` | `fighterEntity`, `victimEntity` |
 
-Do not abbreviate (`hp` → `currentHealth`, `box` → `hitbox`, `gp` → `gameProcessed`).
+Do not abbreviate (`hp` → `currentHealth`, `box` → `hitbox`).
 
-## Header layout
+## Module layout
 
-Group prototypes on the struct in this order:
+Group shared `func` and constants in ReplicatedStorage modules in this order when it helps readers:
 
-1. Session bind / lifecycle
+1. Constants / types
 2. Queries (`IsFighterAlive`, `CanAcceptAttack`)
 3. World writes (`SeedFighter`, `AdvanceCombo`)
-4. Hitbox
-5. Damage / replication
+4. Hitbox / damage helpers
 
-Keep constants next to the fields they configure.
+Server `.server.clp` files: top-level `link`, then binders (`Ward.Start()`, `Net.Hit ~> …`, `Players.PlayerAdded ~>`).
 
-## Script layout
+## Links in a compiling script
 
-Define methods in the same order as the header. `void init()` only calls binders:
-
-```clpp
-void init() {
-	CombatServer::BindPlayerSessions();
-	CombatServer::BindCombatRemotes();
-}
+```clp
+link @clpp.roblox;
+link @clpp.libs.ward as Ward;
+link @clpp.libs.sweep as Sweep;
+link @ReplicatedStorage.Shared.CombatRules as CombatRules;
+link @ReplicatedStorage.Shared.Net as Net;
 ```
 
-## Includes in a compiling script
-
-```clpp
-#pragma strict
-#include <clpp/roblox.clh>
-#include <clpp/libs/ward.clh>
-#include "CombatServer.clh"
-```
-
-Angled library includes that must emit a `require` belong in the `.clpp`, not only the `.clh`.
+Library `link @clpp.libs.*` must appear in the script that needs the runtime `require`.
 
 ## Comments
 
-No narration. A name should replace a comment. If a workaround exists, one line pointing at the compiler limitation is enough.
+No narration. Prefer `<<` for non-obvious notes. One line for compiler limitations is enough.
 
 ## Never leave errors
 
-Diagnostics are work, not a report. Do not stop, explain, or ask while the file still shows errors. Fix, rebuild, fix again until `cluaupp build` exits 0 and the compiling `.clpp` has no unused-parameter / type diagnostics.
-
-CL++ does **not** count uses inside a nested `func () { }` as uses of the outer parameters. Mention every parameter in the method body (`guard`) before the lambda.
+Fix until `cluaupp build` exits 0. CL++ does **not** count uses inside nested `func () { }` as uses of outer parameters — mention them in the outer `guard` before the lambda.
 
-Flare handlers must match the packet arity. If a field is unused, put it in the `guard` — do not drop it from the signature.
+Flare handlers must match packet arity. Unused fields go in `guard`, not dropped from the signature.
 
-Truth is `cluaupp build`, not clangd / C++ IntelliSense on `.clpp`. If the editor squiggles but the compiler is clean, ignore the squiggle. If the compiler errors, change the code.
+Truth is `cluaupp build`, not C++ IntelliSense on `.clp`. If the compiler is clean, ship it.

package/src/api/build-profile.ts

@@ -132,7 +132,7 @@ export function writeProfileCache(profile: RobloxTargetProfile, outPath?: string
 export function profileContentHash(profile: RobloxTargetProfile): string {
 	const clone = { ...profile, sources: { ...profile.sources } };
 	for (const key of Object.keys(clone.sources)) {
-		clone.sources[key] = { ...clone.sources[key], loadedAt: "" };
+		clone.sources[key] = { ...clone.sources[key], loadedAt: "", path: "" };
 	}
 	return hashBuffer(JSON.stringify(clone));
 }

package/src/api/loader.ts

@@ -21,7 +21,7 @@ export function loadJsonFile<T>(id: string, filePath: string): LoadedSource<T> {
 		meta: {
 			id,
 			path: absolute,
-			hash: hashBuffer(raw),
+			hash: hashBuffer(text.replace(/\r\n/g, "\n")),
 			loadedAt: new Date().toISOString(),
 			version: typeof (data as { Version?: unknown }).Version !== "undefined"
 				? (data as { Version: string | number }).Version
@@ -54,7 +54,7 @@ export function overridesHash(): string {
 		if (!name.endsWith(".json")) {
 			continue;
 		}
-		parts.push(name, fs.readFileSync(path.join(dir, name), "utf8"));
+		parts.push(name, fs.readFileSync(path.join(dir, name), "utf8").replace(/\r\n/g, "\n"));
 	}
 	return hashBuffer(parts.join("\n"));
 }