cluaupp 0.1.2 → 0.1.5

package/CHANGELOG.md

@@ -1,10 +1,38 @@
 # Changelog
 
+## 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
+
+- Architecture: generated services keep a fixed declaration order (requires, types, constants, variables, functions, cleanup, return) without section banners. Domain `Stop` runs `janitor:Cleanup()`.
+- IntelliSense: `cluaupp init` / `cluaupp intellisense` install Microsoft `ms-vscode.cpptools` (VSIX on Cursor, where the marketplace omits it), write `.vscode/c_cpp_properties.json` (LLVM clang++, C++20, `include/` + `src/`, `compile_commands.json`), and disable clangd so the two engines do not fight. `build`/`watch` only refresh `compile_commands.json`.
+- `Class::method` on game types becomes `Class:method()` (`self`). Datatype/library statics stay dotted (`CFrame.lookAt`, `Color3.fromRGB`, `FormatNumber.Abbreviate`).
+- `switch` / `case` / `default` / `break` compile to a one-shot `repeat` with `if` / `elseif` / `else`. The discriminant is evaluated once; stacked `case` labels share a body; `break` leaves the switch even from inside an `if`.
+- Janitor typed border re-exports `_impl` (`export type Janitor = Impl.Janitor; return Impl`). It no longer invents `Has` or requires Promise for a parallel type that did not match howmanysmall.
+- Emit: injected `require` / `GetService` are `const`. C++ functions emit as `const function` instead of `local function`.
+- `.server.cpp` emits `init.luau` + `init.meta.json` with `RunContext.Server`. `init.server.luau` is Legacy and is pruned.
+- `cout << ... << endl` emits `print(...)`. `cerr <<` emits `warn`. `cout::print` / `cout::warn` / `cout::error` / `cout::ping` map to the Roblox globals.
+- Docs: [print and cout](docs/print-cout.md); [Libraries](docs/libraries/index.md) how-tos (DataService Init, Janitor, Promise, Net); [OOP structure](docs/oop/index.md) (file tags, services, modules); [Examples](docs/examples/index.md) (leaderstats, combat validation, shop, HUD, sword). GitHub Pages Learn tabs: OOP, Libraries, print/cout, Examples — generated into `site/` (`guide/oop.html`, `guide/examples.html`).
+
 ## 0.1.2
 
 - Watch does not write `out/` while any file fails to compile (Studio keeps the last good scripts).
 - Watch/build skip rewriting Luau whose contents did not change (a space in C++ no longer floods Rojo).
-- `libs/` is fill-only: missing files are restored, existing files are never overwritten or deleted. Fixes Rojo 7 crashing on `libs/ArrayIndexer` when watch/build raced a live serve.
+- Watch never copies `libs/` or headers. Changing a constant no longer makes Rojo 7 crash on `libs/ArrayIndexer`.
+- `libs/` on `cluaupp build` is fill-only: missing files are restored, existing files are never overwritten or deleted.
+- Filename tags: `.server.cpp` → Script (`init.server.luau`), `.client.cpp` → LocalScript (`init.client.luau`), `.plugin.cpp` → Plugin, `.legacy` / `.legacy.client` / `.legacy.server` → Legacy. Bare `init.luau` is not used for `.server` (Rojo would make a ModuleScript).
 - Dropped `$optional` from `default.project.json` (Rojo 7.7 failed to deserialize it).
 
 ## 0.1.1

package/README.md

@@ -8,18 +8,11 @@
 
 [Docs](https://kartzrbx.github.io/Cluaupp/) · [Learn](https://kartzrbx.github.io/Cluaupp/learn/) · [API](https://kartzrbx.github.io/Cluaupp/api/classes/)
 
-The cinematic docs site deploys to [Vercel](https://vercel.com) from `site/` (`vercel.json`). Code blocks use **Dark Modern**, **Tokyo Night**, and **Dracula**. Ask Cluaupp (AI Gateway) is the floating chat on the Vercel deploy.
-
-```bash
-cp .env.example .env.local   # set AI_GATEWAY_API_KEY
-npx vercel
-```
-
 [![npm version](https://img.shields.io/npm/v/cluaupp.svg)](https://www.npmjs.com/package/cluaupp)
 [![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()`.
 
@@ -73,12 +66,12 @@ rojo serve
 Connect the Rojo plugin in Roblox Studio. Edit `src/**/*.{cpp,h,hpp}`, run `cluaupp watch` to rebuild on save.
 
 ```
-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).
+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).
 
 ## Documentation
 
@@ -89,8 +82,12 @@ A tiny `leaderstats.server.cpp` becomes `Main` / `PlayersManager` / `CacheContro
 | [Learn](https://kartzrbx.github.io/Cluaupp/learn/) | C++ subset, Luau output, safety, architecture |
 | [CLI](docs/cli.md) | `init`, `build`, `watch`, flags |
 | [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 |
 | [C++ types](docs/cpp-types.md) | Typing, `const`, safety, organization |
 | [Comparison](docs/comparison.md) | vs roblox-ts and WASM toolchains |
 | [Contributing](CONTRIBUTING.md) | Tests, layout, how to ship |

package/docs/README.md

@@ -4,16 +4,19 @@
 2. [Getting started](getting-started.md) — npm, Rojo, Wally
 3. [CLI](cli.md) — `init`, `build`, `watch`
 4. [Syntax](syntax.md) — C++ subset, `local`, `const`
-5. [C++ types](cpp-types.md) — primitives, Instances, `nullptr`
-6. [const](cpp-const.md) — immutability
-7. [Safety](cpp-safety.md) — client trust, Janitor, Net, DataService
-8. [Organization](cpp-organization.md) — server / client / shared
-9. [Advanced](cpp-advanced.md) — `::` vs `:`, Wally, performance
-10. [Architecture](architecture.md) — PascalCase services, Types modules, vs roblox-ts dumps
-11. [Libraries](libraries.md) — Janitor, Promise, Net, Module3D, Twinkle, DataServiceV2
-12. [Roblox API](roblox-api.md) — Vector3, CFrame, UDim2, classes
-13. [Config](config.md) — `cluaupp.config.json`
-14. [Comparison](comparison.md) — roblox-ts and WASM
+5. [print and cout](print-cout.md) — `cout <<`, `cout::warn`, `endl`
+6. [C++ types](cpp-types.md) — primitives, Instances, `nullptr`
+7. [const](cpp-const.md) — immutability
+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) — 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
+15. [Roblox API](roblox-api.md) — Vector3, CFrame, UDim2, classes
+16. [Config](config.md) — `cluaupp.config.json`
+17. [Comparison](comparison.md) — roblox-ts and WASM
 
 Moonwave site (local): `npx moonwave dev`
 

package/docs/architecture.md

@@ -3,51 +3,52 @@ 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 |
-| --- | --- |
-| `*.server.ts` | Script |
-| `*.client.ts` | LocalScript |
-| no suffix | ModuleScript |
+| 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` |
 
-Flamework then stamps a second key (`@Service` / `@Controller`) so the runtime knows the **role**. Cluaupp does both steps without decorators.
+`DataBoot.client.cpp` becomes `out/client/boot/DataBoot.client.luau` with your `init()` at the end. Shared `#include` modules use `require(ReplicatedStorage.Cluaupp...)`.
 
-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).
+`--!strict` is opt-in: put `#pragma strict` in the `.cpp`, or set `"strict": true` in `cluaupp.config.json`.
 
-Leaderstats was the example. A combat `.server.cpp` is a different system and gets Combat folders, not a fake CacheController.
+The ForeverHD-style folder split (`LeaderStats/Main.luau`, …) is **opt-in**: `"architecture": true`.
 
 ## File tags
 
 | Source | Meaning | Output |
 | --- | --- | --- |
-| `combat.server.cpp` | Server **system** | `Combat/` Script: `init.server.luau` + Main / Controllers / Types |
-| `hud.client.cpp` | Client **system** | `Hud/` LocalScript folder |
-| `boot.legacy.server.cpp` | Server script, no split | `boot.server.luau` (Rojo Script, `init()` still runs) |
-| `boot.legacy.client.cpp` | Client script, no split | `boot.client.luau` |
-| `damage.cpp` (no tag) | **Module** | `Damage.luau` ModuleScript `return { ... }` — does not auto-run |
+| `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` |
+| `damage.cpp` (no tag) | **ModuleScript** | `Damage.luau` |
+
+## What a tagged file becomes
+
+```
+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
+```
 
-Trivial entry files (`init.client.cpp` that only `print`) stay a single LocalScript. The planner does not invent Managers for a hello-world.
+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.
 
-## How the planner reasons
+## 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()`.
 
 ```
 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 |
@@ -61,50 +62,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`.
-
-## What leaderstats becomes
-
-```
-src/server/leaderstats.server.cpp
-```
-
-```
-out/server/LeaderStats/
-  init.server.luau
-  Main.luau
-  PlayersManager.luau
-  CacheController.luau
-  LeaderStatsTypes.luau
-```
-
-## What combat becomes
-
-```
-src/server/combat.server.cpp   -- TakeDamage, Humanoid
-```
-
-```
-out/server/Combat/
-  init.server.luau
-  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`
-- Janitor owns connections in the Manager
-- Types modules `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`.
 
-See [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

@@ -23,13 +23,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.server.luau` 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` or `"strict": true`
+- `#include "file.h"` becomes `require(ReplicatedStorage.Cluaupp...)` / `require(ServerScriptService.Cluaupp...)` for shared/server modules
 - `#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.
@@ -41,7 +40,7 @@ cluaupp build ./my-game
 
 ## `cluaupp watch [folder]`
 
-Runs a `build` 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). Rebuilds are debounced and do **not** recopy `libs/`. Deleted `.cpp` files prune their `out/` artifacts on the next successful compile.
+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 --version` / `cluaupp -v`
 

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.luau` and `*.client.luau` files are classified by Rojo as Script and LocalScript. A folder with `init.server.luau` becomes a Script named after the folder (`LeaderStats`) with ModuleScript children (`Main`, `PlayersManager`, `CacheController`, `LeaderStatsTypes`).
+`*.server.cpp` becomes `*.server.luau` (Script). `*.client.cpp` becomes `*.client.luau` (LocalScript). Untagged files become ModuleScripts.

package/docs/cpp-advanced.md

@@ -9,7 +9,7 @@ The subset is intentional. What exists is enough for game scripts; what is missi
 
 ## Supported
 
-- Functions, prototypes (headers only), `if` / `else` / `while` / range-`for`
+- Functions, prototypes (headers only), `if` / `else` / `while` / range-`for` / `switch` (`case`, `default`, `break`)
 - `new Class(parent)`, `GetService<T>()`, `::` statics (`CFrame::lookAt`, `Enum::Material::Plastic`)
 - `->` methods and properties, `.` members, `Connect`
 - `const`, `auto`, `nullptr`, arithmetic, `&&` `||` `!=`
@@ -18,7 +18,7 @@ The subset is intentional. What exists is enough for game scripts; what is missi
 
 ## Not supported (yet)
 
-Full C++: templates besides `GetService<T>`, `class` bodies as emitted types, `std::`, overloading as two runtimes, `switch`, C-style `for`, macros, pointer arithmetic.
+Full C++: templates besides `GetService<T>`, `class` bodies as emitted types, `std::`, overloading as two runtimes, C-style `for`, macros, pointer arithmetic.
 
 If you need a custom type, it is usually a **ModuleScript in shared** (a `.cpp` of functions) or a Wally package, not a C++ class the compiler would lower to a metatable.
 
@@ -45,12 +45,16 @@ CluauppLibs already contains the full Janitor, Fusion, Cmdr, DataServiceV2, …
 #include <cluaupp/libs/dataservice.hpp>
 
 void Grant(Player* player, int amount) {
-	auto coins = DataService::Get(player, "Currencies.Coins");
-	DataService::Set(player, "Currencies.Coins", coins + amount);
+	Data* data = DataService::Server.WaitFor(player);
+	if (data == nullptr) {
+		return;
+	}
+	int coins = data->Get(DataService::Server.Paths.Currencies.Money);
+	data->Set(DataService::Server.Paths.Currencies.Money, coins + amount);
 }
 ```
 
-Keep path strings in `config.h`. Match the tokens your DataServiceV2 template already uses (`DataService.Paths.Currencies.Coins` in Luau).
+`Paths.Currencies.Money` exists because **your** Template passed to `Init` had that field. Full copies: [Examples](examples/index.md).
 
 ## Performance notes
 
@@ -68,4 +72,4 @@ Keep path strings in `config.h`. Match the tokens your DataServiceV2 template al
 5. **Headers declare, scripts define.** Prototypes in `.h`, bodies in `.cpp`.
 6. **Do not share mutable statics across server and client** — use Net or DataService.
 
-See also: [syntax](syntax.md), [libraries](libraries.md), [comparison](comparison.md).
+See also: [syntax](syntax.md), [print and cout](print-cout.md), [libraries](libraries/index.md), [OOP](oop/index.md), [examples](examples/index.md), [comparison](comparison.md).

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).
+`*.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
 
@@ -58,4 +58,6 @@ const string REMOTE_COINS = "Coins";
 
 Do not install a second Janitor from Wally unless you have a reason — CluauppLibs already has howmanysmall/Janitor. DataServiceV2 still bundles its own janitor/quicknet/signal inside the DataService folder.
 
+How-tos: [Libraries](libraries/index.md). Service layout: [OOP](oop/index.md). Copy-paste: [Examples](examples/index.md).
+
 Next: [advanced Cluaupp](cpp-advanced.md).

package/docs/cpp-safety.md

@@ -9,7 +9,7 @@ Safety in Cluaupp is not a sandbox flag. It is a set of habits the compiler and
 
 ## 1. Never trust the client
 
-[Net](libraries.md) lets a client `FireServer`. The server must validate:
+[Net](libraries/net.md) lets a client `FireServer`. The server must validate:
 
 ```cpp
 void OnBuy(Player* player, int productId) {
@@ -17,19 +17,23 @@ void OnBuy(Player* player, int productId) {
 		return;
 	}
 	int price = PriceOf(productId);
-	int coins = DataService::Get(player, "Currencies.Coins");
+	Data* data = DataService::Server.WaitFor(player);
+	if (data == nullptr) {
+		return;
+	}
+	int coins = data->Get(DataService::Server.Paths.Currencies.Money);
 	if (coins < price) {
 		return;
 	}
-	DataService::Set(player, "Currencies.Coins", coins - price);
+	data->Set(DataService::Server.Paths.Currencies.Money, coins - price);
 }
 ```
 
-Do not store coins only on the client. Do not let the client pass the new coin total — pass the *intent* (`productId`).
+Do not store coins only on the client. Do not let the client pass the new coin total — pass the *intent* (`productId`). Full systems: [Shop](examples/shop.md), [Combat](examples/combat.md).
 
 ## 2. Clean up with Janitor
 
-Every `Connect` that outlives a player, a GUI, or a tool needs a Janitor. Leaving a step, destroying a character, or closing a menu should `Cleanup()` or `LinkToInstance`.
+Every `Connect` that outlives a player, a GUI, or a tool needs a [Janitor](libraries/janitor.md). Leaving a step, destroying a character, or closing a menu should `Cleanup()` or `LinkToInstance`.
 
 ```cpp
 auto* janitor = new Janitor();
@@ -45,7 +49,7 @@ Leaked connections duplicate effects: double coins, stacked cameras, lingering h
 
 ## 4. One writer for persisted data
 
-[DataServiceV2](https://wally.run/package/kartzrbx/dataservicev2) distinguishes `Get()` (merged, includes transient admin overlays) from `GetPersisted()` (what ProfileStore will save). Use `SetTransient` for test panels so you never persist cheat values. Only the server writes persisted paths.
+[DataService](libraries/dataservice.md) distinguishes `Get()` (merged, includes transient admin overlays) from `GetPersisted()` (what ProfileStore will save). Use `SetTransient` for test panels so you never persist cheat values. Only the server writes persisted paths. The save **shape** is your Template — the library does not ship `Currencies`.
 
 ## 5. Buffers, not ad-hoc strings
 
@@ -55,4 +59,4 @@ Leaked connections duplicate effects: double coins, stacked cameras, lingering h
 
 Remote names (`Net::Event("Coins")`) are public protocol. Keep them `const`, short, and unique. Changing a name without a migration breaks old clients.
 
-Next: [organization](cpp-organization.md).
+Next: [organization](cpp-organization.md), [OOP](oop/index.md), [Examples](examples/index.md).

package/docs/cpp-types.md

@@ -46,7 +46,7 @@ player.Name = "Kartz"
 player:FindFirstChild("leaderstats")
 ```
 
-There is no pointer arithmetic, no `delete`, no `std::unique_ptr`. Lifetime is Roblox’s: parented Instances live until `Destroy` or until a [Janitor](libraries.md) cleans them.
+There is no pointer arithmetic, no `delete`, no `std::unique_ptr`. Lifetime is Roblox’s: parented Instances live until `Destroy` or until a [Janitor](libraries/janitor.md) cleans them.
 
 ## `nullptr`
 

package/docs/examples/_category_.json

@@ -0,0 +1,5 @@
+{
+	"label": "Examples",
+	"position": 21,
+	"collapsed": false
+}