Project layout

How the repository maps into Roblox Studio, what replicates and what stays on the server, and where game code, tools and agent docs live.

The repository holds the framework, one game’s Game layer, the tools that check both, and the docs that agents and people read before changing anything. ChloeKernel.project.json maps the three folders under src/ into Studio. The split between them is the security model made physical.

Source tree

src/
├── Shared/                        -> ReplicatedStorage (replicates to every client)
│   ├── Game/                      the game: Channels.luau (every network channel), Config/ (client-visible tunables)
│   └── ChloeKernel/               the kernel and client framework
│       ├── init.luau              Kernel: boot, start, createScope, phaseScheduler, spawnProcess, shutdown
│       ├── Scheduler, Process, ServiceManager, Scope, Logger, GcWatch, ErrorWatch
│       ├── Serde, Base64, Rng, Time, Rules, Text, Curve, Pool, TablePool, Preload
│       ├── Spatial, SpatialKit, TagWatch, Mounts
│       ├── IPC/                   Bus, Signal
│       ├── Hooks/                 HookRegistry
│       ├── Net/                   Client (NetClient), Registry, Prediction, TokenBucket, ReplicaClient,
│       │                          SettingsClient, InventoryClient, BusBridgeClient, GovernorClient,
│       │                          HazardClient, ProjectileClient, RagdollClient, Packet/ (wire transport)
│       ├── InputDriver, MoveKit, CameraKit, CutsceneKit, MaterialKit, Highlights, Prices
│       ├── AnimKit, AudioKit, BonePhysics, HairKit, Dissolve, MeshSource, DeviceBench, VfxSuite, Impact, Gait
│       ├── Debug/                 Panel, NetTap, NetPanel, ImGui, Chronicle, HookScope, SimPanel, SimLoad
│       ├── TestKit/               TestKit, Gate, Watch, Expect, Bench
│       ├── Tests/                 shared specs
│       └── Benches/               Kernel.bench.luau
├── Server/                        -> ServerScriptService (never replicates)
│   ├── Main.server.luau           spec gate, boot, Bootstrap, start, diagnostics, audit and fuzz
│   ├── Bootstrap.luau             loads Game between kernel boot and start
│   ├── Simulation.server.luau     load harness (ChloeKernelSimulation attribute), Studio or ChloeKernelDebug only
│   ├── Game/                      the game: init.luau, Registry.luau, Services/ (ComponentService), and
│   │                              Components/, Config/, Data/, Tests/ as the game adds them
│   └── ChloeKernelServer/         the privileged framework
│       ├── init.luau              ServerKernel: sessions, net(), close phase, securityAudit
│       ├── Session, Net (NetDriver), NetGovernor, Replica, BusBridge, MessageDriver, Milestones
│       ├── Data/                  DataDriver (init), Handoff, MemoryDriver, TransactionRecovery, Backends/
│       ├── Commerce/              Receipts, Passes, Pricing, Transactions
│       ├── AntiExploit/           Movement, Rewind, Consequences
│       ├── Policy, TextFilter, Fuzz, Forensics, Settings, LiveConfig, Analytics
│       ├── Projectiles, Effects, Zones, Senses, Hazards, Sweeps, Stages, Ragdoll, Pathfinding/
│       ├── Matchmaking, TeleportRetry, SoftShutdown, Leaderboards, Leaderstats, ActorPool/
│       ├── Kits/                  WeaponKit, MeleeKit, SpellKit, NPCKit, BehaviorTree, InventoryKit, LootKit,
│       │                          CraftingKit, ShopKit, CompanionKit, QuestKit, RoundKit, CheckpointKit,
│       │                          TeamKit, PartyKit, InteractionKit, ProceduralKit/, AchievementKit, DialogueKit
│       ├── Simulation/            simulation modes
│       └── Tests/                 server specs
└── Client/                        -> StarterPlayer.StarterPlayerScripts
    ├── Main.client.luau           game specs (Studio), boot, Bootstrap, start, F8 debug panel
    ├── Bootstrap.luau             loads Game between kernel boot and start
    └── Game/                      the game: init.luau, Registry.luau, Controllers/ (ComponentController,
                                   UIController), and Screens/, Components/, Tests/ as the game adds them

The Packet transport under Net/Packet is a kernel-maintained port of Packet v1.7 by Suphi Kaner; its CREDITS.md credits the original and marks the local changes.

The placement rule

src/Shared/ChloeKernel replicates to every client. Only genre-agnostic, non-privileged code lives there: schedulers, signals, codecs, the network client and client-side kits. An exploiter who reads all of it learns nothing that helps them.
src/Server/ChloeKernelServer never leaves the server. Sessions, validators, rate limits, data, commerce, anti-exploit heuristics and the gameplay kits live there.
src/Shared/Game replicates too. It holds Channels.luau, which both sides require so schemas cannot drift, and client-visible config. Loot odds, anti-cheat thresholds and anything else clients must not see go in src/Server/Game/Config.
src/Server/Game and src/Client/Game are the game. Game/init.luau on each side builds the channel handles and registers every module in Registry.luau; the Registry lists one require per service or controller, and the directive linter (CK010) fails when a module is missing from it or its Name does not match the file.
The Main scripts and Bootstrap.luau files own boot ordering. Leave them alone unless a framework driver must attach before services. Framework updates then never collide with game code.
Workspace, Lighting, terrain, models and UI are authored in Studio and saved in the place file, not on disk. Map requirements (folders, tags, attributes) are listed in docs/game/Plan.md.

Directive CK009 fails the check when shared or client code references ServerScriptService or ServerStorage, so a client module cannot quietly depend on server code.

Repository root

AGENTS.md                  the rulebook for every coding agent (and a good read for people); CLAUDE.md points here
CLAUDE.md                  Claude Code specifics: skills, hooks, finish with tools/check.py
README.md                  the cookbook ("I want to...") and the full API reference
CHANGELOG.md               release notes; the release job cuts GitHub releases from it
LICENSE.md                 private-access license
.claude/                   skills (new-game, add-system, review-game), hooks (format and lint on edit,
                           toolchain install in web sessions), settings.json
.github/workflows/         ci.yml (runs python tools/check.py), release.yml (two models per v* tag)
docs/
├── agents/                Catalog.md (generated capability map), Recipes.md (genre to module map),
│                          Engine.md and Engine/ (nine engine domain guides), templates/ (Design.md, Plan.md)
├── game/                  created per game: Design.md and Plan.md
└── *.md                   runtime guides: event-driven, event-driven-networking, scopes, receipts,
                           performance, teleport-retries, vendoring
templates/                 GunArena, WizardDuel, Obby: reference games, never synced
tools/                     check.py, setup.py, directives.py, scaffold.py (+ scaffold_templates/), catalog.py,
                           engine.py (+ engine-api.json), vendor.py, check_runtime.py, types-baseline.txt,
                           regressions/ (isolated Luau runners), plugin/ (Studio spec harness), test_*.py

docs/agents and the root AGENTS.md are what the Agent workflow reads first. Starter templates covers templates/, and check.py covers the tools.

Toolchain files

File	Purpose
`ChloeKernel.project.json`	The Rojo sync project: a DataModel with `src/Shared` in ReplicatedStorage, `src/Server` in ServerScriptService and `src/Client` in StarterPlayerScripts. `check.py` builds it as a smoke test.
`build.project.json`	Folder-rooted model of the same three trees, for the `ChloeKernel-<tag>.rbxm` release artifact
`runtime.project.json`	Framework-only model (`ReplicatedStorage.ChloeKernel` and `ServerScriptService.ChloeKernelServer`) without `Tests/`, `Benches/`, TestKit or Simulation, for `ChloeKernelRuntime-<tag>.rbxm`; `tools/check_runtime.py` inspects the built model. See Releases and vendoring.
`aftman.toml`	Tool pins: Rojo 7.4.4, StyLua 2.0.2, Selene 0.28.0, luau-lsp 1.68.0. `tools/setup.py` reads them.
`selene.toml`, `stylua.toml`, `.luaurc`	Lint, format and strict-typing configuration. `check.py` runs StyLua and Selene over `src` and `templates`.
`tools/types-baseline.txt`	Accepted luau-lsp warnings; a new warning or any type error fails the `types` step
`.tools/`	Created by `tools/setup.py`: pinned binaries in `.tools/bin`, the Luau runtime, `globalTypes.d.luau`. Ignored by git.