Leaf Getter: launch scope

v2, with your answers folded in. Paste this into Codex working on the repo. 4 waves: (1) hatch tornado by rarity up to Secret, giant pets + kg, global banner, number pops; (2) Golden Pile Run: meteor drop, light pillar, sack, timer, BONK, Golden Roulette, golden egg/seed models; (3) Hub Free Spin wheel, playtime gift boxes, bin tiers, rebirth aura; (4) the owner-only admin panel. New files only, on a branch, nothing wired in. Claude reviews + wires it.

You are working in the Roblox game repo `D:\joc roblox\PACHET-ROBLOX-PRIETEN\1-leafgetter-roblox-leafraker` (Luau, Rojo-style layout, disk is the source of truth). The game is **Leaf Getter**: kids rake falling leaves into a backpack, pour them into a bin on their plot for coins, upgrade a tree, hatch pets from eggs, rebirth. 8 plots sit on a ring around a central Hub.

## Goal
Build a **crazy-juicy FX + model pack** that speaks the visual language of today's viral Roblox games (Steal An Egg, Ride A Pet, Drill for Eggs, Build the Pyramid, +1 Loot To Forge), so new players "get it" in one second, **while staying OUR identity: every effect is made of LEAVES**. Their light beam = our leaf tornado. Their confetti = our falling leaves. Their meteor = our burning golden leaf pile. Palette: leaf green, gold, autumn orange/red, rainbow for Mythic, a dark galaxy purple for Secret.
Go big: screen shake, camera punches, shockwave rings, slow ease-outs, escalating drama by rarity. The rarer the thing, the more the whole screen reacts. But it must run on a phone.

You build **standalone presentation modules + an owner-only admin panel**. You do NOT wire them into the game loop: no edits to existing files. Claude integrates after review.

## Read first (only these)
- `CLAUDE.md` (repo rules), `docs/DESIGN.md` (palette, fonts, motion timings, 3D rules: part-built, `Material = Plastic` (Neon allowed for glow accents only), stud surfaces, NO MeshPart / Union / uploaded assets, part caps)
- `docs/LUAU-STANDARDS.md` (LF, no BOM, `task.*`, no `wait()`, no `Debris`, server trusts nothing from the client)
- `src/client/ReplicatedStorage/UIKit.luau`: reuse `UIKit.rarityColor`, `UIKit.short`, `UIKit.topbarY`, `UIKit.Colors`, `UIKit.punch`, `UIKit.shake`, `UIKit.panel`, `UIKit.button`, `UIKit.label`
- `src/server/Server/LeafGameServer.luau`, ONLY `setupTrashBin` (~line 225) for the bin footprint / `RimAbove` / mouth cap. Do not read the rest of this 200 KB file.
- `docs/research/viral-frames/*.jpg` for the look we're echoing: steal-an-egg-01-27 (hatch beam), ride-a-pet-11-59 ("1 in 1T" hatch), drill-for-eggs-09-42 (giant pet + kg), loot-to-forge-07-54 (big number pops), drill-for-eggs-04-36 (aura), steal-an-egg-00-46 ("RUN!!" carry), build-the-pyramid-00-01 (server bar).

## Decisions already made (design around these)
- **Size is flex, never power.** Pet stats stay by rarity as they are now. Big pets must never block play: every pet part `CanCollide = false`, `CanQuery = false`, `CanTouch = false`; the camera must not zoom in when a big pet passes between it and the player.
- Rarities: `Common, Rare, Epic, Legendary, Mythic` + an optional **`Secret`** (0.01%-style). Colours via `UIKit.rarityColor`; Secret isn't in UIKit, so define it locally (deep purple → black galaxy with white sparkles).
- Golden Pile Run + **Bonk at launch** (the bonk only knocks the golden sack off; never coins, pets or backpack).
- Golden Pile reward = a **Golden Roulette** spin (special Golden Egg / Golden Seed Pack / coin jackpot / rainbow / rare Secret Egg).
- Retention: playtime gifts, daily rewards, a **Free Spin wheel in the middle of the Hub**.
- Server-wide + cross-server (global) announcements for the rarest hatches.
- Admin panel for testing (owner-only, removed before launch).

## Hard rules
- New files ONLY: `src/client/ReplicatedStorage/LeafFx/*.luau`, `src/client/ReplicatedStorage/LeafModels/*.luau`, `src/server/Server/Admin/*.luau`, `src/client/StarterGui/LeafHUD/AdminUI.client.luau`, `tests/studio/fx-showcase.luau`. Edit NO existing file.
- No new asset ids (you can't upload). Allowed: parts, `ParticleEmitter` with built-in textures (`rbxasset://textures/particles/sparkles_main.dds`, `smoke_main.dds`, `fire_main.dds`), `Beam`, `Trail`, `PointLight`, `Highlight`, `BillboardGui`, `ScreenGui`, `TweenService`, client-side `Lighting`/`ColorCorrectionEffect` tweens that ALWAYS restore the exact previous values.
- Animations are procedural (TweenService / RunService), never `Animation` assets.
- Every effect: a max duration, cleans up after itself (`task.delay(t, inst.Destroy, inst)`), returns a `stop()` handle, and caps transient parts (≤ 60 per effect, ≤ 120 for Mythic/Secret). State the cap in the module header.
- Camera effects (shake, FOV punch, slow push) are client-only, ≤ 1.5 s, and respect a module-level `Settings.reducedMotion` flag.
- Each module starts with a 5-10 line header: what it is, which viral pattern it echoes, the public API, caps.
- Never open or drive Roblox Studio, never send mouse/keyboard input, never commit to `main`, never publish. LF, no BOM, no PowerShell `Set-Content`.

## What to build: one git commit per item, branch `codex/leaf-fx`, in this order

### Wave 1: the hatch and the flex
1. **`LeafFx/HatchBeam.luau`**: `HatchBeam.play(origin: CFrame, rarity: string, pet: Model?) -> {stop: () -> ()}`
   Escalates by rarity. Common/Rare: a short leaf swirl + pop. Epic: a 25-stud leaf tornado in the rarity colour + a leaf burst. Legendary: a 35-stud tornado, a shockwave ring along the ground, a camera shake. Mythic: the sky dims (Lighting tween, restored), a rainbow tornado, a double shockwave, a FOV punch, the pet rises out with a slow spin and a light flare. Secret: everything Mythic does, plus a black-purple galaxy column, 1 s of slow-mo on the pet's rise, and white sparkles raining over the plot. ≤ 3.5 s total.
2. **`LeafFx/PetFlex.luau`**: big pets by rarity.
   `scaleFor(rarity)` (one table at the top: Common 1, Rare 1.3, Epic 1.7, Legendary 2.4, Mythic 3.2, Secret 5.0), `weightKg(rarity, seed)` (deterministic; Common 1-20 kg … Secret 50,000-250,000 kg), `attachAura(model, rarity)` (Epic: 3 orbiting leaves; Legendary: 5 + a light; Mythic: 8 rainbow leaves + a Trail; Secret: a galaxy particle cloud + an orbiting ring), `weightLabel(model, kg, rarity)`, `apply(model, rarity, seed)` = ScaleTo + make the parts non-blocking (rule above) + aura + label, `setLocalSizeEnabled(enabled: boolean)` = client-side "Pet Size OFF": rescales every pet model under `workspace` locally back to 1x and hides auras (leave a comment if server CFrame replication could fight it).
3. **`LeafFx/Banner.luau`**: `Banner.show(text, rarity?, opts?: {global: boolean?, seconds: number?})`
   A top-centre strip under the top bar (`UIKit.topbarY()`). Slides down, rarity-gradient fill (rainbow scroll for Mythic, galaxy for Secret), shake, holds 3.5 s. `global = true` adds a gold frame + "🌍 GLOBAL" tag + a bigger entrance. Queue: max 3 waiting. Fits an 812x375 phone. Own ScreenGui, `DisplayOrder` 30, `IgnoreGuiInset = true`.
4. **`LeafFx/NumberPop.luau`**: `world(position, amount, color?)` (BillboardGui "+1.2M 💰", text size 24 → 72 by log10(amount), rises + fades 0.9 s; ≥ 1B also bursts gold leaves), `flyCoins(from: Vector2, to: GuiObject, count)` (≤ 12 coins arc into the pill, then `UIKit.punch(to)`).

### Wave 2: the Golden Pile Run
5. **`LeafModels/GoldenPile.luau`**: `build() -> Model`: a glowing heap of gold + a few rainbow stud leaves, ≤ 20 parts, PrimaryPart at ground centre.
6. **`LeafFx/GoldenPile.luau`**:
   - `incoming(groundPos: Vector3, seconds: number) -> {stop}`: a warning circle on the ground with a countdown + a burning leaf "meteor" falling from the sky that lands exactly at the end (impact shockwave, dust of leaves, camera shake for anyone within 80 studs).
   - `pillar(model) -> Instance`: a gold light pillar ~120 studs tall, visible from every plot.
   - `rakeRing(model, player) -> {set(frac), destroy}`: a circular progress ring over the pile while someone holds to rake it.
   - `sackOnBack(character) -> Model`: a glowing leaf sack welded to the back with a Trail.
   - `timerBar(character, seconds) -> {set(frac), destroy}`: a bar over the head, green → amber → red, with leaves blowing off as it empties and a red screen vignette + "RUN!!" text on the carrier's own screen for the last 5 s.
   - `bonk(attackerChar, victimChar)`: a procedural rake-swing arc (a swoosh part + Trail), stars over the victim's head, a "BONK!" pop, the sack flies off in an arc and bounces twice.
   - `landed(binModel, player)`: the sack dives into the bin, the lid slams, gold leaves erupt.
7. **`LeafFx/Roulette.luau`** (client UI): `Roulette.spin(slices: {{name, color, icon?, weight}}, resultIndex: number, onDone: () -> ())`
   The Golden Roulette. A big wheel panel with chasing lights, ticks that slow down (fire a `ticked` BindableEvent for sounds), a near-miss tease on the slice next to the rare one, then leaf confetti + the result card. The SERVER decides `resultIndex`; this only animates it. ≤ 6 s, skippable after 1.5 s.
8. **`LeafModels/GoldenRewards.luau`**: `goldenEgg() -> Model` (≤ 10 parts, gold with rainbow studs), `goldenSeedPack() -> Model` (≤ 10 parts), `secretEgg() -> Model` (≤ 10 parts, black-purple with white specks). Pivot at the bottom centre.

### Wave 3: retention props
9. **`LeafModels/HubWheel.luau`** + **`LeafFx/HubWheel.luau`**: a big part-built Free Spin wheel for the Hub centre (≤ 40 parts, ~18 studs tall, 8 slices with coloured studs, a pointer, light bulbs around the rim). `HubWheelFx.spinTo(model, sliceIndex, seconds)`: rim bulbs chase, the wheel decelerates, the pointer clicks per slice, and the win slice flashes with a leaf burst.
10. **`LeafModels/GiftBox.luau`** + **`LeafFx/GiftBox.luau`**: playtime gift boxes, tiers 1-5 (green → blue → purple → gold → rainbow), ≤ 12 parts each. `open(model, onDone)`: shakes, the lid pops off, a beam + leaves, the reward card slides up (`UIKit.slideUpCard`).
11. **`LeafModels/BinTiers.luau`**: tiers 1-4 **wood → metal → gold → crystal**, the same footprint + `RimAbove` + mouth cap as `setupTrashBin`, ≤ 12 parts each. `swapFx(old, new)`: the old one shrinks out, the new one slams in with a shockwave.
12. **`LeafFx/RebirthAura.luau`**: `titleFor(rebirths) -> (string, Color3)` (0 Raker, 1-2 Sweeper, 3-4 Groundskeeper, 5-7 Gardener, 8-11 Leaf Lord, 12+ Autumn King) and `attach(character, rebirths) -> Instance` (a title over the head + an aura growing by tier, up to a slow leaf tornado around the feet at 8+). Plus `rebirthMoment(character)`: the whole-screen rebirth explosion (white flash, a leaf supernova, camera push).

### Wave 4: owner-only admin panel (testing only, removed before launch)
13. **`src/server/Server/Admin/AdminPanel.luau`** (ModuleScript) + **`src/client/StarterGui/LeafHUD/AdminUI.client.luau`**.
   - Server: `AdminPanel.init(actions: {[string]: (player: Player, arg: any) -> (boolean, string?)})` creates ONE RemoteEvent `ReplicatedStorage.AdminRemote` and ONE RemoteFunction-free reply path (fire back `(ok, message)`). An allow-list `ADMIN_USER_IDS = {}` at the top (Claude fills it in) + `game.CreatorId`. EVERY request: check `player.UserId` against the allow-list on the SERVER, check the action name exists in `actions`, type-check `arg` (number within a sane range, or string from a fixed list), rate-limit to 5 per second per player, and log every call with `print("[ADMIN]", player.Name, action, arg)`. Non-admins get silently ignored. A top-level `ENABLED = true` flag: when false, `init` does nothing and the remote is never created.
   - The actions are injected by Claude later; you only define the action NAMES the UI offers: `giveCoins(n)`, `giveRainbow(n)`, `setRebirths(n)`, `spawnGoldenPile()`, `forceHatch(rarity)`, `merchantArrive()`, `startEvent(name)`, `spinWheelFree()`, `resetMe()`.
   - Client: a small draggable panel, opened with a button that only exists if `player.UserId` is in the same list (read from an attribute the server sets on the player, `IsLeafAdmin = true`), built with `UIKit.panel/button`. Number input + action buttons, and the last server reply shown at the bottom. Plus an FX preview tab that calls the LeafFx modules locally (hatch per rarity, banner, roulette, number pops).

### Always last
14. **`tests/studio/fx-showcase.luau`**: one Studio chunk (header `-- datamodel: Client`, see other `tests/studio/*.luau` for the header style) that requires every module and plays each one in a row in front of the local character, 12 studs apart, with a 3 s gap. It prints `PASS <item>` / `FAIL <item>: <error>` per module.

## Done means
- `D:\temp\leafgetter-lune-0.10.5\lune.exe run .scratch/compilecheck.luau` → all files OK (it collects every `.luau` under `src` automatically).
- `D:\temp\leafgetter-lune-0.10.5\lune.exe run tests/gamecore.test.luau` → still all green (you touched no logic).
- `git diff main --stat` shows ONLY the new files listed under Hard rules.
- A short report per wave: each file, its API, its part cap, what you weren't sure about. Don't claim it looks good; nobody has seen it in Studio yet. Claude runs the showcase in Studio, takes screenshots, and Mihai + Cristi pick.