cluaupp 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,9 +1,30 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.0
+
+- CLI rewritten as a TypeScript collector-emitter pipeline: Tree-sitter collection, Rojo-mapped `require`s, ordered Luau blocks (Services → Requires → Types → Constants → Code), then optional StyLua / `luau-analyze`. Commands `init`, `build`, `watch`, `lsp`, and `intellisense` stay. `cluaupp build -i file.cpp -o out.luau --rojo default.project.json` is the single-file path.
+- C++ IntelliSense is **clangd** only. The old tokenizer/`completeAt` engine is gone. Tree-sitter is the compiler frontend. `cluaupp lsp` publishes subset parse errors only.
+- `SystemUnderstander` scans identifiers, scores Roblox intents, and stamps Controller / Manager / utility plus `GetService` injections. Filename tags still decide Script vs LocalScript vs ModuleScript.
+- Sample game C++ lives in `examples/game/` (`src/server`, `src/client`, `src/shared`). Compiler `src/` is TypeScript only.
+- CLI security: StyLua / luau-analyze via `spawn` without a shell; emitted paths cannot leave the project; `.env*` stays out of git and the npm pack.
+- Docs / GitHub Pages: clangd, SystemUnderstander, one-file-out emit, `examples/game`. Rojo **7.7.0**.
+- Tests cover `out/` tree, types, modules, path safety, and understander roles.
+
+## 0.1.5
+
+- Default emit is one tagged `.cpp` → one `.server.luau` / `.client.luau`. `"architecture": true` keeps the old ForeverHD service folders.
+- `--!strict` is opt-in: `#pragma strict`, `#pragma nstrict`, or `"strict": true` in config (default `false`).
+- `.h` / `.hpp` emit type ModuleScripts (`export type` + typed table). A sibling `.cpp` becomes `*Impl.luau`; the header binds those functions.
+- Shared `#include` modules `require` game-rooted paths (`ReplicatedStorage.Cluaupp...` / `ServerScriptService.Cluaupp...`).
+
 ## 0.1.4
 
 - Quoted `#include "Header.h"` of project files becomes `const Header = require(...)`. Header-only structs emit a constructor (`TemplateData()`); const headers bind `PLAYER_DATA_VERSION` from the module. Boot scripts require services (`LeaderstatsServer:init()`).
 - Keep `const` for injected `require` / `GetService` and `const function` for C++ functions (not `local`).
+- `init.meta.json` stays pure JSON. Library `require` injection no longer prepends Luau onto Rojo meta files (which made `rojo serve` fail with a JSONC parse error).
+- Server services emit `init.server.luau` + `init.meta.json` with **only** `RunContext.Server`. Rojo forbids `className` when an `init.*` script exists (the folder is already a Script, not a Folder). `init.luau` is pruned so the instance is not a ModuleScript.
 
 ## 0.1.3
 

package/README.md

@@ -12,7 +12,7 @@
 [![Node.js](https://img.shields.io/node/v/cluaupp.svg)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Source-to-source transpiler: you write a C++ subset, Cluaupp emits modern [Luau](https://luau.org/getting-started) (`--!strict`, `local`, `const`). C++ structure, Luau quality, one language.
+Source-to-source transpiler: you write a C++ subset, Cluaupp emits modern [Luau](https://luau.org/getting-started) (`local`, `const`, optional `--!strict`). C++ structure, Luau quality, one language.
 
 No WASM. No Emscripten. No `lua_call`. Roblox APIs come out as they do in Studio: `game:GetService("Players")`, `player:FindFirstChild("leaderstats")`, `players:GetPlayers()`.
 
@@ -42,7 +42,7 @@ players.PlayerAdded:Connect(CreateLeaderstats)
 
 ## Install
 
-Node.js 18+ and [Rojo](https://rojo.space/) for Studio sync.
+Node.js 18+ and [Rojo](https://rojo.space/) **7.7.0** for Studio sync (`rokit.toml` in the game template).
 
 ```bash
 npm install -g cluaupp
@@ -59,19 +59,24 @@ npx cluaupp init my-game
 ```bash
 cluaupp init my-game
 cd my-game
+rokit install
 cluaupp build
 rojo serve
 ```
 
 Connect the Rojo plugin in Roblox Studio. Edit `src/**/*.{cpp,h,hpp}`, run `cluaupp watch` to rebuild on save.
 
+C++ autocomplete is **clangd**, not a Cluaupp tokenizer and not Microsoft cpptools. Put `#include <cluaupp/roblox.hpp>` at the top of each script; `cluaupp init` writes `.clangd` / `compile_flags.txt` / `compile_commands.json` with `-Iinclude` so clangd finds that header. Tree-sitter is only used to compile. See [IntelliSense](docs/intellisense.md).
+
 ```
-src/server/*.server.cpp  →  out/server/LeaderStats/   Script + ModuleScripts
-src/client/*.client.cpp  →  out/client/*.client.luau  LocalScript (or a service folder)
-src/shared/config.*      →  out/shared/Config.luau    typed config module
+src/server/*.server.cpp  →  out/server/*.server.luau  Script
+src/client/*.client.cpp  →  out/client/*.client.luau  LocalScript
+src/shared/*.cpp         →  out/shared/*.luau         ModuleScript
 ```
 
-A tiny `leaderstats.server.cpp` becomes `Main` / `PlayersManager` / `CacheController`. A combat `.server.cpp` becomes `CombatController` with your `TakeDamage` logic. Filename tags: `.server.cpp`, `.client.cpp`, `.legacy.server.cpp`, `.legacy.client.cpp`, or no tag (ModuleScript). See [Architecture](docs/architecture.md) and [OOP structure](docs/oop/index.md).
+Filename tags: `.server.cpp`, `.client.cpp`, `.legacy.server.cpp`, `.legacy.client.cpp`, or no tag (ModuleScript). One source file becomes one instance. Set `"architecture": true` only for the old PascalCase folder split. See [Architecture](docs/architecture.md) and [OOP structure](docs/oop/index.md).
+
+Compiler TypeScript lives in `src/`. Sample game C++ is [`examples/game`](examples/game) (`src/server`, `src/client`, `src/shared`). `cluaupp init` still copies [`templates/game`](templates/game).
 
 ## Documentation
 
@@ -84,7 +89,7 @@ A tiny `leaderstats.server.cpp` becomes `Main` / `PlayersManager` / `CacheContro
 | [Syntax](docs/syntax.md) | C++ subset → Luau (`local`, `const`, types) |
 | [print and cout](docs/print-cout.md) | `cout <<`, `cout::warn`, `endl` |
 | [Roblox API](docs/roblox-api.md) | Vector3, CFrame, UDim2, GetService, Instance.new |
-| [Architecture](docs/architecture.md) | PascalCase services, Types modules, not a 200-line dump |
+| [Architecture](docs/architecture.md) | One file in, one file out; opt-in ForeverHD folders |
 | [OOP structure](docs/oop/index.md) | File tags, services, modules, structs |
 | [Libraries](docs/libraries/index.md) | DataService Init, Janitor, Promise, Net |
 | [Examples](docs/examples/index.md) | Leaderstats, combat validation, shop, HUD, sword |

package/bin/cluau.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 "use strict";
 
-require("../src/cli.js");
+require("../generated/cli.js");

package/bin/cluaupp.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 "use strict";
 
-require("../src/cli.js");
+require("../generated/cli.js");

package/docs/README.md

@@ -10,7 +10,7 @@
 8. [Safety](cpp-safety.md) — client trust, Janitor, Net, DataService
 9. [Organization](cpp-organization.md) — server / client / shared
 10. [Advanced](cpp-advanced.md) — `::` vs `:`, Wally, performance
-11. [Architecture](architecture.md) — PascalCase services, Types modules, vs roblox-ts dumps
+11. [Architecture](architecture.md) — one file in, one file out; opt-in ForeverHD folders
 12. [OOP structure](oop/index.md) — file tags, services, modules, structs
 13. [Libraries](libraries/index.md) — DataService Init, Janitor, Promise, Net, more
 14. [Examples](examples/index.md) — leaderstats, combat validation, shop, HUD, sword

package/docs/architecture.md

@@ -3,54 +3,77 @@ title: Architecture
 sidebar_position: 15
 ---
 
-# Output treated as a Roblox system
+# One file in, one file out
 
-roblox-ts decides **what instance you get** from a filename **key** (the same idea as Rojo):
+roblox-ts decides **what instance you get** from a filename **key** (the same idea as Rojo). Cluaupp does the same — and **stops there** by default. It does not invent Main / Controller / Types folders.
 
-| Key | Rojo instance |
+| Key | Rojo instance | Default output |
+| --- | --- | --- |
+| `*.server.cpp` | Script | `*.server.luau` |
+| `*.client.cpp` | LocalScript | `*.client.luau` |
+| no suffix | ModuleScript | `Name.luau` |
+| `*.legacy.server.cpp` | Legacy Script | `*.server.luau` |
+
+`DataBoot.client.cpp` becomes `out/client/boot/DataBoot.client.luau` with your `init()` at the end. Shared `#include` modules use `require(ReplicatedStorage.Cluaupp...)`.
+
+`--!strict` is opt-in: put `#pragma strict` in the `.cpp`, or set `"strict": true` in `cluaupp.config.json`.
+
+The ForeverHD-style folder split (`LeaderStats/Main.luau`, …) is **opt-in**: `"architecture": true`.
+
+## SystemUnderstander
+
+Like [roblox-ts](https://github.com/roblox-ts/roblox-ts) (filename **key** first) and [roblox-cs](https://github.com/roblox-csharp/roblox-cs) (scan the AST, then decide), Cluaupp does **not** call a generative model. `src/system-understander.ts` walks the Tree-sitter tree, scores token density against Roblox engine services, and returns a report the emitter may stamp as comments / extra `GetService` lines.
+
+| Step | What happens |
 | --- | --- |
-| `*.server.ts` | Script |
-| `*.client.ts` | LocalScript |
-| no suffix | ModuleScript |
+| `parseFileTag` | `.server.cpp` → Script / Server, `.client.cpp` → LocalScript / Client, no tag → ModuleScript |
+| `namesIn` | identifiers, `GetService<T>`, `new Class`, string literals |
+| `scoreIntents` | evidence count × side weight (server tokens count more on `.server.cpp`) |
+| `determineArchitecture` | score &lt; 2 → utility Module; otherwise Knit-style Controller / Manager / Service. `players` / `cache` stay supporting if combat, UI, or net already has ≥ 2 tokens |
+
+The **Rojo class never changes** because of a role. A HUD LocalScript can be classified as `ViewController` and still emit `hud.client.luau`. Sample sources: [examples/game](../examples/game).
 
-Flamework then stamps a second key (`@Service` / `@Controller`) so the runtime knows the **role**. Cluaupp does both steps without decorators.
+## Compiler pipeline
 
-1. **Tag** (filename) — where the code runs and whether it is a Script, LocalScript, ModuleScript, or a 1:1 “legacy” dump.
-2. **Intent** (AST) — what the code *is for*: players, cache, combat, input, UI, net, data, … scored from APIs and identifiers, the same idea as intent classification in program analysis (features from the tree, not a 200-line dump).
+Cluaupp does not rewrite C++ as text. The CLI parses a Tree-sitter CST, collects symbols (`GetService<T>()`, `#include`, types, constants), then emits Luau in a fixed order:
 
-Leaderstats was the example. A combat `.server.cpp` is a different system and gets Combat folders, not a fake CacheController.
+1. `game:GetService(...)`
+2. `require(...)` (Rojo `default.project.json` when present)
+3. types
+4. constants
+5. functions / script body
+
+Formatting is delegated to StyLua; type sanity to `luau-analyze`. See [CLI](cli.md).
 
 ## File tags
 
 | Source | Meaning | Output |
 | --- | --- | --- |
-| `combat.server.cpp` | **Script** RunContext Server | `Combat/init.luau` + `init.meta.json` |
-| `hud.client.cpp` | **LocalScript** | `Hud/init.client.luau` |
-| `tools.plugin.cpp` | **Script** RunContext Plugin | `Tools/init.luau` + `init.meta.json` |
-| `boot.legacy.cpp` | Legacy Script | `boot.server.luau` |
+| `combat.server.cpp` | **Script** | `combat.server.luau` |
+| `hud.client.cpp` | **LocalScript** | `hud.client.luau` |
+| `tools.plugin.cpp` | **Script** RunContext Plugin | `tools.luau` (legacy plugin tag) |
 | `boot.legacy.server.cpp` | Legacy Script | `boot.server.luau` |
-| `boot.legacy.client.cpp` | Legacy LocalScript | `boot.client.luau` |
-| `boot.legacy.plugin.cpp` | Plugin | `boot.luau` + Plugin meta |
 | `damage.cpp` (no tag) | **ModuleScript** | `Damage.luau` |
 
-Trivial entry files (`init.client.cpp` that only `print`) stay a single LocalScript (`init.client.luau`). The planner does not invent Managers for a hello-world.
+## What a tagged file becomes
 
-## How the planner reasons
+```
+src/server/leaderstats.server.cpp  →  out/server/leaderstats.server.luau
+src/client/boot/DataBoot.client.cpp  →  out/client/boot/DataBoot.client.luau
+src/shared/damage.cpp  →  out/shared/Damage.luau
+```
+
+Scripts and LocalScripts keep your functions and call `init()` at the end. ModuleScripts return a table. There is no invented Main, Controller, or Types file.
+
+## Opt-in: ForeverHD folders (`"architecture": true`)
+
+Set `"architecture": true` in `cluaupp.config.json` to restore the old planner: PascalCase service folders, `Main` / Managers / Controllers / Types, and `require(script.Main):Start()`. Server folders emit `init.server.luau` plus a **pure JSON** `init.meta.json` with only `RunContext.Server` — never `className`, and never library `require` lines (Rojo 7.7 rejects both).
 
 ```
 filename key  →  server | client | module | legacy
 AST features  →  GetService, Instance.new, methods, identifiers
 intent scores →  combat:2, character:1, …
 roles         →  Main + Managers + Controllers + Types
-user functions→  kept in the matching Controller (not discarded)
-```
-
-Generated files start with that trace:
-
-```luau
--- tag server → Script (service)
--- intents combat:2, character:1
--- roles Main, CombatController, CombatTypes
 ```
 
 | Evidence in the C++ | Role |
@@ -64,54 +87,6 @@ Generated files start with that trace:
 | Domain shapes / stats | `{Service}Types` (`export type`, `return {}`) |
 | Wiring | `Main.Start` / `Main.Stop` |
 
-If the C++ creates Coins/Level, CacheController is generated (higher quality than copying `CreateLeaderstats`). Combat logic is **not** rewritten into leaderstats — `ApplyDamage` stays in `CombatController.luau`.
-
-The domain controller keeps **every** user function. CacheController is generated beside it; it must not delete `SetupPlayerManager` while `init` still calls that name. `GetChangedSignal(Paths.Currencies)` stays in `DataController`.
-
-## What leaderstats becomes
-
-```
-src/server/leaderstats.server.cpp
-```
-
-```
-out/server/LeaderStats/
-  init.luau
-  init.meta.json
-  Main.luau
-  PlayersManager.luau
-  CacheController.luau
-  LeaderStatsTypes.luau
-```
-
-## What combat becomes
-
-```
-src/server/combat.server.cpp   -- TakeDamage, Humanoid
-```
-
-```
-out/server/Combat/
-  init.luau
-  init.meta.json
-  Main.luau
-  CombatController.luau    -- your ApplyDamage / OnHit
-  CombatTypes.luau
-```
-
-No PlayersManager unless you actually listen to players. No CacheController unless you actually create value Instances.
-
-## ForeverHD-style rules
-
-- PascalCase folders and modules; camelCase locals
-- `--!strict` everywhere
-- Public API `Start` / `Stop`. `Start` is idempotent (`Stop` first). Domain `Stop` is `janitor:Cleanup()` (unbind, janitor stays reusable). `OnClose` / `Destroy` stay for `BindToClose`. `PlayersManager.Stop` disconnects and runs `onLeave`. `CacheController.ClearAll` drops the cache.
-- Janitor owns connections in the Manager
-- Module layout in generated Luau (no section banners): requires, types, constants, variables, functions, cleanup, return.
-- Transparent `require(script.Parent.X)`
-
-## Config
-
-`cluaupp.config.json`: `"architecture": true` (default). `"architecture": false` forces 1:1 dumps (or use `.legacy.server.cpp` / `.legacy.client.cpp` per file).
+Switching back to 1:1 deletes the stale `LeaderStats/` / `DataBoot/` folders on the next `cluaupp build`.
 
-How to **write** a service, tags, and module-style OOP: [OOP structure](oop/index.md). Copy-paste systems: [Examples](examples/index.md). Also [organization](cpp-organization.md) and [comparison](comparison.md).
+How to **write** a system, tags, and module-style OOP: [OOP structure](oop/index.md). Copy-paste systems: [Examples](examples/index.md). Also [organization](cpp-organization.md) and [comparison](comparison.md).

package/docs/cli.md

@@ -6,6 +6,8 @@ cluaupp <command> [folder]
 
 If `[folder]` is omitted, the current directory is used.
 
+The compiler is a **collector-emitter** pipeline: Tree-sitter walks the C++ CST, Rojo maps `#include` to `require`, Luau is emitted in a fixed block order (Services → Requires → Types → Constants → Code), then StyLua / `luau-analyze` can run as post-process.
+
 ## `cluaupp init [folder]`
 
 Creates a game from the template:
@@ -13,8 +15,9 @@ Creates a game from the template:
 - `src/server`, `src/client`, `src/shared`
 - `cluaupp.config.json`
 - `default.project.json` (Rojo)
+- `rokit.toml` (Rojo 7.7.0)
 - `include/cluaupp/roblox.hpp` (IntelliSense)
-- `.vscode/c_cpp_properties.json`
+- `.vscode/` (clangd)
 
 ```bash
 cluaupp init .
@@ -23,13 +26,12 @@ cluaupp init my-game
 
 ## `cluaupp build [folder]`
 
-Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. Script files become PascalCase **service folders** (`LeaderStats/Main.luau`, `PlayersManager.luau`, `CacheController.luau`, `LeaderStatsTypes.luau`) plus `init.luau` and `init.meta.json` (`RunContext.Server`) for Rojo. Shared `const` headers become `Config.luau`.
+Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. One tagged `.cpp` becomes one Luau instance (`leaderstats.server.luau`, `hud.client.luau`). Shared untagged files become ModuleScripts. Set `"architecture": true` for the old PascalCase service folders.
 
-- `--!strict` on every module
-- `#include "file.h"` inlines that header into the current file
+- `--!strict` only with `#pragma strict`, `"strict": true`, or `--strict` on the single-file path
+- `#include "file.h"` becomes `require(...)` resolved from `default.project.json` when present
 - `#include <cluaupp/roblox.hpp>` is ignored
-- `.h` / `.hpp` with a sibling `.cpp` are not emitted twice
-- `new Folder(parent)` in a stats system becomes `CacheController.Ensure`
+- `.h` / `.hpp` emit a type ModuleScript (`export type` + typed table). A sibling `.cpp` becomes `*Impl.luau` (the construction); the header binds those functions.
 - A parse error exits with code 1 and `file:line:column`
 - After emit, **orphans in `out/` are removed** (source deleted → matching Luau deleted). `out/` itself is never wiped, so a running Rojo serve keeps the live tree.
 - `libs/` and `include/cluaupp` are synced by writing missing/changed files only. They are **never** deleted as a folder — Rojo 7 unwrap-crashes if `libs/ArrayIndexer` vanishes while serving.
@@ -37,12 +39,29 @@ Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. Script files become PascalCase **
 ```bash
 cluaupp build
 cluaupp build ./my-game
+cluaupp build --format --analyze
+```
+
+### Single file
+
+```bash
+cluaupp build --input ./src/server/boot.server.cpp --output ./out/boot.server.luau --rojo ./default.project.json
 ```
 
+`--format` runs StyLua; `--analyze` runs `luau-analyze`. On the single-file path both run by default (warnings if the binaries are missing). On a project build they are opt-in.
+
 ## `cluaupp watch [folder]`
 
 Runs a compile (without copying `libs/`) and rebuilds when anything under `src/` changes, including deletes. Parse errors are printed; the watcher stays alive and **does not write `out/`** until the project compiles cleanly (Studio keeps the last good scripts). A second watcher in the same game exits. Deleted `.cpp` files prune their `out/` artifacts on the next successful compile.
 
+## `cluaupp lsp [folder]`
+
+Stdio JSON-RPC for **Cluaupp subset diagnostics** only. Completion, hover, and definitions are clangd.
+
+## `cluaupp intellisense [folder]`
+
+Writes `compile_commands.json`, `.clangd`, and `.vscode` for clangd, and installs LLVM clangd when needed.
+
 ## `cluaupp --version` / `cluaupp -v`
 
 Prints the npm package version.
@@ -65,7 +84,8 @@ Shows usage.
 In the Cluaupp development repo:
 
 ```bash
-npm run build    # cluaupp build game
-npm run dev      # watch + Rojo
-npm run stop     # stop Rojo
+npm run build:cli   # compile the TypeScript CLI
+npm test
+npm run dev         # local gitignored playground in game/ + Rojo
+npm run stop        # stop Rojo
 ```

package/docs/comparison.md

@@ -6,9 +6,9 @@
 
 Both are source-to-source. Neither goes through WASM. Generated Luau calls the Roblox API directly.
 
-The difference is **what Studio receives**. roblox-ts stops at the filename key (`*.server.ts` → Script). Cluaupp uses that key **and** reads the AST so a combat system is not emitted as a fake leaderstats. See [Architecture](architecture.md).
+By default Cluaupp matches that filename key: `*.server.cpp` → one Script, `*.client.cpp` → one LocalScript, untagged → ModuleScript. The ForeverHD folder split is opt-in (`"architecture": true`). See [Architecture](architecture.md).
 
-Current Luau has [`local`, `const`, and `--!strict`](https://luau.org/getting-started). Cluaupp emits that on purpose: `const int` in C++ becomes `const x = ...` in Luau.
+Current Luau has [`local`, `const`, and `--!strict`](https://luau.org/getting-started). Cluaupp emits `const` from C++ `const`. `--!strict` is opt-in (`#pragma strict` or `"strict": true`).
 
 ## vs C++ → WASM → Luau (RBX-CPP / Emscripten)
 
@@ -33,5 +33,5 @@ is exactly what Studio expects, not a parallel runtime.
 | Goal | Tool |
 | --- | --- |
 | Game in TypeScript | roblox-ts |
-| Game in C++, clear Roblox API, Luau `--!strict` | **Cluaupp** |
+| Game in C++, clear Roblox API | **Cluaupp** |
 | Full native C++ (templates, STL, engines) | not Cluaupp today |

package/docs/config.md

@@ -6,17 +6,17 @@ File: `cluaupp.config.json` at the game root (next to `src/`).
 {
 	"rootDir": "src",
 	"outDir": "out",
-	"strict": true,
-	"architecture": true
+	"strict": false,
+	"architecture": false
 }
 ```
 
 | Field | Default | Effect |
 | --- | --- | --- |
 | `rootDir` | `"src"` | Where the `.cpp` / `.h` / `.hpp` files live |
-| `outDir` | `"out"` | Where services and modules are written |
-| `strict` | `true` | Prefix `--!strict` on every generated file |
-| `architecture` | `true` | Emit PascalCase service folders (`LeaderStats/Main.luau`, …) instead of one dump per `.cpp` |
+| `outDir` | `"out"` | Where Luau is written |
+| `strict` | `false` | Prefix `--!strict` on generated files (overridden by `#pragma strict` / `#pragma nstrict`) |
+| `architecture` | `false` | If `true`, emit PascalCase service folders (`LeaderStats/Main.luau`, …) instead of one Luau per `.cpp` |
 
 If the file is missing, those defaults apply.
 
@@ -28,4 +28,4 @@ The template ships `default.project.json` mapping:
 - `out/client` → `StarterPlayer.StarterPlayerScripts.Cluaupp`
 - `out/shared` → `ReplicatedStorage.Cluaupp`
 
-`*.server.cpp` becomes a folder with `init.luau` + `init.meta.json` (`className` Script, `RunContext` Server). `.client` stays LocalScript via `init.client.luau`. A `.legacy.server.cpp` dump is still `*.server.luau` (Legacy).
+`*.server.cpp` becomes `*.server.luau` (Script). `*.client.cpp` becomes `*.client.luau` (LocalScript). Untagged files become ModuleScripts.

package/docs/cpp-organization.md

@@ -5,7 +5,7 @@ sidebar_position: 13
 
 # Organization
 
-A Cluaupp game is laid out like a roblox-ts project on disk. The **output** is not a dump: `cluaupp build` turns each system into a PascalCase service folder (Main, Manager, Controller, Types). See [Architecture](architecture.md).
+A Cluaupp game is laid out like a roblox-ts project on disk. One tagged `.cpp` becomes one Luau instance (`leaderstats.server.luau`, `hud.client.luau`). See [Architecture](architecture.md).
 
 ```
 src/
@@ -47,7 +47,7 @@ const string REMOTE_COINS = "Coins";
 
 `leaderstats.server.cpp` creates leaderstats. It does not also open the shop UI. Name files after the system: `inventory.server.cpp`, `shop.client.cpp`.
 
-`*.server.cpp` / `*.client.cpp` are **tags** (the same keys roblox-ts uses). Untagged `.cpp` is a ModuleScript. `.legacy.server.cpp` / `.legacy.client.cpp` skip the service split. See [Architecture](architecture.md) and [OOP structure](oop/index.md).
+`*.server.cpp` / `*.client.cpp` are **tags** (the same keys roblox-ts uses). Untagged `.cpp` is a ModuleScript. Set `"architecture": true` only if you want the old PascalCase folder split. See [Architecture](architecture.md) and [OOP structure](oop/index.md).
 
 ## CluauppLibs vs extra Wally
 

package/docs/examples/index.md

@@ -7,6 +7,8 @@ sidebar_position: 1
 
 High-quality Cluaupp systems you can copy. Each page is a full service: C++ that the subset actually compiles, server authority, Janitor cleanup, and the file names Studio expects.
 
+In this repo the live sample is [`examples/game`](../../examples/game) (`src/server`, `src/client`, `src/shared`). Compiler TypeScript is never mixed with game C++. `cluaupp init` still copies [`templates/game`](../../templates/game).
+
 These are **not** dumps of `int main()`. Entry is `void init()`. There are no lambdas and no custom C++ classes — named functions + structs.
 
 ## Suggested layout

package/docs/getting-started.md

@@ -5,8 +5,8 @@ Cluaupp installs from **npm**, the same channel as roblox-ts and most Roblox too
 ## Requirements
 
 - [Node.js](https://nodejs.org/) 18 or newer
-- [Rojo](https://rojo.space/) to sync `out/` into Studio
-- An editor with C++ IntelliSense (Cursor / VS Code + the C/C++ extension)
+- [Rojo](https://rojo.space/) **7.7.0** to sync `out/` into Studio (`cluaupp init` writes `rokit.toml`; run `rokit install`)
+- LLVM clangd for C++ IntelliSense (Cursor / VS Code — installed by `cluaupp init`)
 
 ## Install the compiler
 
@@ -43,6 +43,7 @@ npm install --save-dev cluaupp
 ```bash
 cluaupp init my-game
 cd my-game
+rokit install
 cluaupp build
 rojo serve
 ```
@@ -66,7 +67,8 @@ my-game/
     shared/config.h
     shared/config.cpp
   out/                    ← generated Luau (do not edit)
-    server/LeaderStats/     Main, PlayersManager, CacheController, Types
+    server/leaderstats.server.luau
+    client/init.client.luau
     shared/Config.luau
 ```
 
@@ -122,13 +124,13 @@ If a file defines `void init()`, Cluaupp calls `init()` at the end of the `.luau
 
 ## IntelliSense
 
-`cluaupp init` writes the C++ IntelliSense config and installs Microsoft `ms-vscode.cpptools` (via VSIX on Cursor). Then reload the window.
+`cluaupp init` writes clangd config and installs LLVM `clang++` plus the clangd editor extension when missing. Then reload the window. Completion is clangd; Cluaupp does not index C++ itself.
 
 ```bash
 cluaupp intellisense
 ```
 
-`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau.
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau. clangd learns that path from `-Iinclude` in `.clangd`, `compile_flags.txt`, and `compile_commands.json` — it does not read `c_cpp_properties.json`.
 
 See [IntelliSense](intellisense.md).
 

package/docs/intellisense.md

@@ -1,31 +1,49 @@
-# IntelliSense
-
-`cluaupp init` and `cluaupp intellisense` install the same setup that works in Cursor:
-
-1. Microsoft [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) (`ms-vscode.cpptools`)
-2. `.vscode/c_cpp_properties.json` — LLVM `clang++`, C++20, `include/` + `src/`, `compile_commands.json`
-3. Forced include of `include/cluaupp/roblox.hpp` so `GetService`, `Player`, `Janitor` complete
-4. The Cluaupp completion engine (Roblox APIs + your `struct`s)
-
-Cursor’s marketplace does not list `ms-vscode.cpptools`. Cluaupp downloads the official VSIX from [vscode-cpptools releases](https://github.com/microsoft/vscode-cpptools/releases) and runs `cursor --install-extension`.
-
-## Install
-
-```bash
-cluaupp intellisense
-```
-
-Reload: Command Palette → **Developer: Reload Window**. Status bar `{} C++` should read **IntelliSense: Ready**.
-
-`cluaupp build` / `watch` only refresh `compile_commands.json` (no download). They never keep deleted files in the compilation database.
-
-## Config that ships
-
-| File | Role |
-| --- | --- |
-| `.vscode/c_cpp_properties.json` | compiler path, include path, `compileCommands` |
-| `.vscode/settings.json` | `C_Cpp.intelliSenseEngine: default`, `clangd.enable: false` |
-| `.vscode/extensions.json` | recommends `ms-vscode.cpptools` |
-| `compile_commands.json` | one entry per `src/` file |
-
-`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is not compiled to Luau.
+# IntelliSense
+
+C++ completion, hover, and go-to-definition are **clangd**. Cluaupp does not ship a second completion engine.
+
+`cluaupp init` / `cluaupp intellisense` install:
+
+1. [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) (`llvm-vs-code-extensions.vscode-clangd`)
+2. LLVM `clang++` when missing (Windows: `winget install --id LLVM.LLVM -e`)
+3. `.clangd`, `compile_flags.txt`, and `compile_commands.json` so clangd finds `include/` (clangd does **not** read `.vscode/c_cpp_properties.json`)
+4. Forced include of `include/cluaupp/roblox.hpp` so `GetService`, `Player`, `Janitor` complete from the real C++ stubs
+
+Tree-sitter is the **compiler** frontend (collect → emit Luau). It is not an editor language server. A homemade tokenizer in the CLI would fight clangd — that path is gone.
+
+Microsoft `ms-vscode.cpptools` is **not** used. Two C++ engines in the same window fight; Cluaupp disables the Microsoft engine (`C_Cpp.intelliSenseEngine: Disabled`).
+
+`cluaupp lsp` only publishes **subset parse errors** (code that clangd may accept as C++ but Cluaupp will not transpile).
+
+## Headers clangd must see
+
+`#include <cluaupp/roblox.hpp>` resolves only if `-Iinclude` is on the clangd compile flags. That maps to `include/cluaupp/roblox.hpp`. Angle-bracket includes are ignored by the transpiler.
+
+`cluaupp init` / `build` / `watch` / `intellisense` rewrite:
+
+- `-Iinclude` and `-Isrc`
+- `-include include/cluaupp/roblox.hpp`
+- one `compile_commands.json` entry per file under `src/`
+
+## Install
+
+```bash
+cluaupp intellisense
+```
+
+Reload: Command Palette → **Developer: Reload Window**. clangd should attach to `.cpp` files.
+
+`cluaupp build` / `watch` only refresh `compile_commands.json` (no download). They never keep deleted files in the compilation database.
+
+## Config that ships
+
+| File | Role |
+| --- | --- |
+| `.vscode/c_cpp_properties.json` | compiler path (unused by clangd; kept if someone re-enables cpptools) |
+| `.vscode/settings.json` | `C_Cpp.intelliSenseEngine: Disabled`, `clangd.enable: true`, `--compile-commands-dir` |
+| `.vscode/extensions.json` | recommends `llvm-vs-code-extensions.vscode-clangd` |
+| `.clangd` | C++20, `-Iinclude`, skip `out/` and `libs/` |
+| `compile_flags.txt` | fallback flags if a file is not yet in `compile_commands.json` |
+| `compile_commands.json` | one entry per `src/` file |
+
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is not compiled to Luau.

package/docs/intro.md

@@ -5,14 +5,14 @@ sidebar_position: 1
 
 # Cluaupp
 
-**The definitive merge of C++ and modern Luau.** You write a C++ subset. Cluaupp emits [Luau](https://luau.org/getting-started) with `--!strict`, `local`, and `const`, and calls the Roblox API the way Studio does.
+**The definitive merge of C++ and modern Luau.** You write a C++ subset. Cluaupp emits [Luau](https://luau.org/getting-started) with `local` and `const` (and `--!strict` when you opt in), and calls the Roblox API the way Studio does.
 
 This site is built with [Moonwave](https://eryn.io/moonwave/) for local markdown (`npm run docs`). The **public** site is generated into `site/` and deployed to [GitHub Pages](https://kartzrbx.github.io/Cluaupp/) (Learn tabs, OOP, Examples, API). The language is in the same spirit as [roblox-ts](https://roblox-ts.com): a familiar syntax, a restricted subset, readable output.
 
 ## What you get
 
 1. A compiler (`cluaupp init` / `build` / `watch`)
-2. Headers for IntelliSense (`#include <cluaupp/roblox.hpp>`)
+2. Headers for **clangd** (`#include <cluaupp/roblox.hpp>`)
 3. First-party libraries in `ReplicatedStorage.CluauppLibs`
 4. Wally wrappers for DataServiceV2, Fusion, Cmdr, EzVisualz, TopbarPlus, and the rest of your stack