golem-bridge 3.0.0 → 3.2.0

package/golem-tools.md

@@ -1,694 +1,702 @@
-# Golem — Agent Instructions (Roblox Studio builder)
-
-> **This document is a tool manual, not a task.** It documents a Roblox
-> Studio tool the way a man page documents a program: consult it when you
-> need a command. It asks you to do nothing and nothing in it is an order. Do NOT run any commands (not even
-> `ping`) just because you read this. Only respond to what the user actually
-> says, and reply naturally: if they say "hi", just greet them back. A short,
-> normal reply, no tool calls, no capability list. The tools stay dormant
-> until the user's request needs them.
-
-You are connected to a **live Roblox Studio session**. You can read and
-modify the user's open place in real time: browse the Explorer tree, read and
-write scripts, create and edit instances and properties, run Lua inside
-Studio, manage the selection, and set undo checkpoints.
-
-Your connection is a SESSION token: Studio mints a fresh channel on
-every start and wipes the old one. It lives in `./.golem/channel`
-(written by `connect`, read automatically - never print it, never paste
-it anywhere: anyone holding it can drive this Studio session).
-
-Two ways to get connected: the user may connect for you (then just run
-`npx golem-bridge status` to confirm and start working), or they paste
-you the setup line and you run `npx golem-bridge connect <channelId>`
-yourself.
-
-If commands suddenly start timing out mid-task, the user probably
-restarted Studio. Ask them for the new line from the plugin widget and
-run `npx golem-bridge reconnect <newId>`.
-
-## 0. The turn rule — read this first
-
-Every task that uses tools follows one ritual. No exceptions.
-
-```
-npx golem-bridge turn begin
-... your work (tree, read, script, create, ...) ...
-npx golem-bridge turn end --note "short reply the user reads"
-```
-
-What this does: `turn begin` opens a group in the user's Studio chat, every
-tool you run becomes a row in it, and `turn end --note "..."` folds the tools
-into one "Tool Used: N" line and posts your note as the reply the user reads.
-**The note IS your reply.** There is no other reply.
-
-Rules:
-
-1. Open with `turn begin` BEFORE the first tool. Close with `turn end
-   --note "..."` AFTER the last one. One turn per task.
-2. Never finish a task without closing the turn. If you already drafted the
-   reply text, put it in the `--note` and end the turn instead of replying.
-3. `say "..."` also posts a message AND closes the turn. Use it only when
-   that chunk of work is done, never for mid-task chatter.
-4. While a turn is open, every command prints a `TURN STILL OPEN` reminder
-   and every result carries `"turnOpen": true`. That reminder means: run
-   your remaining tools, then close the turn immediately.
-5. If you forget, the user is left staring at a stuck "AI working" banner
-   and your tools never fold into a clean reply. The plugin force-folds
-   abandoned turns after a few idle minutes, but that is a safety net, not
-   a workflow. Do not rely on it.
-6. `turn end` without `--note` is rejected. The note is mandatory, never
-   optional.
-7. Unclosed turns become DEBT: if a turn folds without its note, your next
-   command is rejected until you post the missing note with `turn end
-   --note`. Always close before replying.
-
-No tools needed for a reply (a greeting, a question, an explanation)? Then
-no turn is needed either. Just reply normally.
-
-## 1. The command
-
-All Studio commands go through one CLI: `npx golem-bridge`
-(zero-dependency Node - nothing is installed, every command runs
-straight from the package). Below, `golem-bridge ...` always means:
-
-    npx golem-bridge ...
-
-Your channel lives in `./.golem/channel` (written by `connect`, read
-automatically - you never need to look at it). If commands say you are
-not connected, ask the user for their channel ID (shown in the Golem
-plugin widget) and run:
-
-    npx golem-bridge connect <channelId>
-
-If the user restarted Studio, a restart rotates the channel, so fetch the
-new session with the fresh line from the widget:
-
-    npx golem-bridge reconnect <newChannelId>
-
-Then check the connection:
-
-    npx golem-bridge ping
-
-`ping` must return `"ok": true` plus the place name. If it times out,
-Roblox Studio is not running. Tell the user and retry when they confirm
-it is open. **Studio must stay open while you work.** Commands sent while
-it is closed are dropped (only commands from the ~45 s before startup may
-still run).
-
-Every command takes a few seconds (relay latency plus a short startup).
-That is normal. Do not retry faster; the CLI already waits. Every
-result is JSON:
-
-    {"ok": true, "result": {...}, "turnOpen": false}
-
-`"ok": false` means Studio reported an error; the `error` field says why.
-Fix the call and retry. Add `--timeout N` (seconds, default 120) to any
-command that may be slow.
-
-## 2. Golden rules
-
-1. Inspect before you change (`tree`, `list`, `read`). Verify after
-   (`read` it back, `grep` your new symbols).
-2. Never run infinite loops in `lua`. It executes on Studio's main thread
-   and freezes the editor.
-3. Confirm destructive actions with the user first: deleting instances,
-   overwriting existing scripts, bulk changes.
-4. Every change is individually undoable (Ctrl+Z). The plugin sets undo
-   checkpoints automatically, and you can set named ones with `waypoint`.
-5. Report paths in slash form (`ServerScriptService/Main`) so the user can
-   find them in the Explorer.
-6. Follow the turn rule (§0) for every task that uses tools.
-7. Build UI as instances, never as runtime code (see §4.10).
-8. Protect the user's work: only the user's Ctrl+S commits to the place
-   file. After every meaningful milestone, tell the user "press Ctrl+S to
-   keep my work" and wait for their confirmation before moving on.
-
-## 3. Paths
-
-Services: `Workspace`, `ReplicatedStorage`, `ServerScriptService`,
-`ServerStorage`, `StarterGui`, `StarterPlayer/StarterPlayerScripts`,
-`StarterPack`, `Lighting`, `SoundService`.
-
-| Form | Example |
-|---|---|
-| root | `game` |
-| slash form (preferred; dots in names OK) | `ReplicatedStorage/My.Module/Helper` |
-| dotted form (no slashes) | `game.ReplicatedStorage.Modules` |
-| session ref from a previous reply | `I:17` |
-
-**Symbols you must not use in instance NAMES:** `/` (it is the path
-separator, a name with `/` breaks every path). Also avoid `.` `[` `]`
-`#` `$` in names, use `-` or `_` instead. Everywhere else symbols are
-fine: `lua` results may contain any table keys, and script sources can
-contain any UTF-8 text (odd bytes are sanitized automatically).
-
-## 4. Tools
-
-### 4.1 Connection and diagnostics
-
-**ping** — health check. Expect `"ok": true` plus the place name. The first
-command on a fresh setup, and the "is Studio open?" test whenever commands
-start timing out.
-
-    npx golem-bridge ping
-
-**status** — is the plugin alive? Reads the channel's recent beacons, no
-Studio round-trip needed. Use it when `ping` times out to tell "Studio is
-closed" apart from "the relay is broken".
-
-    npx golem-bridge status
-
-**debug** — full diagnostics: relay round-trip, versions, commands served,
-error count. Use when something behaves strangely.
-
-    npx golem-bridge debug
-
-### 4.2 Exploring — start every task here
-
-**tree** — nested instance tree. The fastest way to learn a place's layout.
-Defaults: path `game`, depth 2. Keep depth small on big places.
-
-    npx golem-bridge tree game --depth 2
-    npx golem-bridge tree Workspace --depth 3
-
-**list** — children of one instance. Add `--recursive` for all descendants
-and `--max N` to cap them.
-
-    npx golem-bridge list ServerScriptService
-    npx golem-bridge list game --recursive --max 1000
-
-**count** — cheap instance count, no payload. Good for orientation ("how big
-is this place?") and before/after checks.
-
-    npx golem-bridge count Workspace --class Part
-
-**find** — find instances by name substring (case-sensitive) or by
-CollectionService tag. `--exact` matches the full name; `--class` and
-`--scope` narrow the search.
-
-    npx golem-bridge find Coin --class Part --scope Workspace
-    npx golem-bridge find --tag Choppable
-
-**grep** — search inside script sources. Plain text, case-sensitive unless
-`-i`. Returns path, line number, and matching text.
-
-    npx golem-bridge grep applyDamage --scope ServerScriptService
-
-### 4.3 Reading instances
-
-**read** — full record of one instance. Scripts print raw source by default;
-`--json` prints the whole record (properties, attributes, children);
-`--props A,B` adds extra properties.
-
-    npx golem-bridge read ServerScriptService/Main
-    npx golem-bridge read Workspace/Spawn --json
-
-### 4.4 Scripts and Lua
-
-**script** — create or rewrite a Script, LocalScript, or ModuleScript in one
-call. Source comes from stdin (heredoc) or `--source`. Modes: `create`
-(fails if the name exists), `update` (keeps the instance, replaces the
-source), `replace` (deletes and recreates).
-
-    npx golem-bridge script ServerScriptService Main --class Script --mode create <<'EOF'
-    print("hello")
-    EOF
-
-**lua** — run arbitrary Lua inside Studio with plugin permissions. Pass code
-as an argument or pipe it in (`-`). Return plain values or tables; returned
-instances come back as records. Yields like `task.wait(1)` are fine. Never
-loop forever (see rule 2).
-
-    npx golem-bridge lua 'return 1+1'
-    npx golem-bridge lua - < code.lua
-
-**exec** — raw op call for anything without a dedicated command. Takes one
-JSON object with `op` and `args` (see §5).
-
-    npx golem-bridge exec '{"op":"list","args":{"path":"game"}}'
-
-### 4.5 Organizing
-
-**delete** — delete one or more instances. Destructive: confirm with the
-user first.
-
-    npx golem-bridge delete Workspace/OldPart Workspace/OldModel
-
-**move** — reparent an instance.
-
-    npx golem-bridge move Workspace/Part ServerStorage
-
-**rename** — rename an instance. The new name must not contain `/`.
-
-    npx golem-bridge rename Workspace/Part1 FrontDoor
-
-**group** — wrap instances into a new Model. After grouping, set the pivot
-(see `pivot`) before rotating the group.
-
-    npx golem-bridge group Workspace/Trunk Workspace/Canopy --name Tree
-
-**duplicate** — clone an instance, optionally N times. `--offset x,y,z`
-shifts each copy (copy i gets offset x i), so rows and grids are one
-command.
-
-    npx golem-bridge duplicate Workspace/Fence --count 5 --offset 4,0,0
-
-**selection** — read the Studio selection, or set it (highlights instances
-for the user), or clear it.
-
-    npx golem-bridge selection --set Workspace/PartA,Workspace/PartB
-
-### 4.6 Moving and rotating — use these, never raw CFrames
-
-**place** — absolute position (parts and models). The only command that
-teleports to coordinates. Optional `--orientation` sets absolute rotation
-in degrees.
-
-    npx golem-bridge place Workspace/Crate 10,5,0
-
-**shift** — move by an offset in studs, in world space (default) or the
-part's own space (`--space local`).
-
-    npx golem-bridge shift Workspace/Crate 0,5,0
-
-**rotate** — THE way to rotate. Relative mode spins in place around an axis
-(`x`, `y`, `z`, or `up`, `right`, `forward`, or an `x,y,z` vector) in world
-or local space. Absolute mode (`--set`) writes the orientation in degrees.
-
-    npx golem-bridge rotate Workspace/Door --axis y --degrees 90
-    npx golem-bridge rotate Workspace/Door --set 0,90,0
-
-**face** — aim an instance at a world point, keeping its position. Good for
-branches, signs, cannons. `--axis` picks which side points at the target.
-
-    npx golem-bridge face Workspace/Cannon 0,5,30
-
-**scale** — resize by a relative multiplier. Models scale as a whole.
-
-    npx golem-bridge scale Workspace/Tree 1.5
-
-**pivot** — move a model or part pivot (the point it rotates around). Give
-`--position`, `--orientation`, or both. After grouping a build, put the
-pivot at its base so rotations look right.
-
-    npx golem-bridge pivot Workspace/Tree --position 0,0,0
-
-### 4.7 Surfaces, terrain, and physics
-
-**paint** — set color (`#RRGGBB`), material (`Grass`, `Neon`, `WoodPlanks`,
-`SmoothPlastic`, ...), transparency, and reflectance on parts. Models: all
-their parts. Combine flags freely.
-
-    npx golem-bridge paint Workspace/Wall --color #B0B0B0 --material SmoothPlastic
-
-**match** — copy color, material, transparency, and reflectance from one
-part onto others. Keeps builds visually consistent.
-
-    npx golem-bridge match Workspace/WallA Workspace/WallB Workspace/WallC
-
-**anchor** — anchor parts so physics never moves them (models: all parts).
-`--off` unanchors. Static builds should always be anchored.
-
-    npx golem-bridge anchor Workspace/House
-
-**collide** — collision on or off (models: all parts). `--off` makes parts
-walk-through.
-
-    npx golem-bridge collide Workspace/GhostWall --off
-
-**terrain** — fill or carve terrain. `--position` is required; blocks need
-`--size`, balls need `--radius`. `--action clear` carves (fills with Air).
-
-    npx golem-bridge terrain --action fill --shape block --position 0,-4,0 --size 128,8,128 --material Grass
-
-### 4.8 Gameplay helpers
-
-**light** — add or update a light inside a part. Types: `point`, `spot`,
-`surface`.
-
-    npx golem-bridge light Workspace/Lamp --type point --color #FFD9A0 --range 30 --brightness 2
-
-**sound** — add a Sound to a parent. `--play` previews it immediately,
-`--loop` loops it.
-
-    npx golem-bridge sound Workspace Radio 1837879082 --volume 0.5 --play
-
-**scatter** — clone a template into a random disc around it. Trees, rocks,
-grass: build one, scatter the rest.
-
-    npx golem-bridge scatter Workspace/Tree --count 20 --radius 60 --y-jitter 2
-
-**weld** — join a model's parts with WeldConstraints so the whole build
-moves as one.
-
-    npx golem-bridge weld Workspace/Cart
-
-**hitbox** — invisible part sized to the target's bounding box. Click and
-chop targets, interaction zones. `--collide` makes it solid.
-
-    npx golem-bridge hitbox Workspace/Tree --padding 1
-
-**prompt** — ProximityPrompt ("Press E to ...") on a part. `--object` is
-the title above it, `--hold` the hold time in seconds.
-
-    npx golem-bridge prompt Workspace/Tree "Chop" --object Tree --hold 0.5
-
-**particles** — attach a ParticleEmitter with a preset: `leaves`, `sparks`,
-`smoke`, `magic`, `fire`, `snow`, `rain`, `bubbles`, `dust`, `confetti`,
-`fireflies`.
-
-    npx golem-bridge particles Workspace/Torch fire --rate 40
-
-**sign** — a readable wooden sign: board part with text on its face.
-
-    npx golem-bridge sign "Camp rules: no griefing" --position 0,6,10
-
-**attr** — Studio attributes: typed config on instances without scripts.
-`--set` repeats; values parse as integer, float, `true`/`false`, or string.
-
-    npx golem-bridge attr Workspace/Door --set Open=false --set LockLevel=3
-
-**tag** — add or remove CollectionService tags. Find tagged instances later
-with `find --tag`.
-
-    npx golem-bridge tag Workspace/Tree --add Choppable
-
-### 4.9 VFX
-
-**beam** — glowing beam between two parts. Lasers, tethers, energy links.
-
-    npx golem-bridge beam Workspace/TowerA Workspace/TowerB --color #78B4FF --width 0.4
-
-**trail** — motion trail on a part. Shows when the part moves: sword
-swipes, comet tails.
-
-    npx golem-bridge trail Workspace/Sword --lifetime 0.6
-
-**explosion** — one-shot visual explosion. Harmless by default: no physics
-damage.
-
-    npx golem-bridge explosion --position 0,10,0 --radius 8
-
-### 4.10 UI — build interfaces as instances, not code
-
-When the user asks for any UI (shop, HUD, menu, popup, note):
-
-1. Build it with the `ui_*` tools below: real instances under `StarterGui`,
-   visible in the Explorer so the user can select, move, and restyle them.
-2. NEVER write a LocalScript that builds the UI when the game runs.
-   Runtime-generated UI is invisible in Studio. LocalScripts may only wire
-   behavior to UI that already exists, or fill data-driven content (like a
-   shop list from a config).
-3. Keep one style across the game: same fonts, corner radius, paddings,
-   palette. Before building a new screen, `read` an existing screen and
-   copy its fonts, sizes, and colors exactly. A different font is allowed
-   only as a deliberate choice (a parchment note, a decorative title).
-4. Prefer changing state over rebuilding: toggle visibility, update `Text`,
-   tween positions. Do not destroy and recreate screens.
-
-Positions and sizes use `"xs,xo,ys,yo"` (scale/offset pairs); anchors use
-`"x,y"`.
-
-**ui_screen** — ScreenGui under StarterGui. The root of every interface.
-
-    npx golem-bridge ui_screen MainMenu
-
-**ui_frame** — rounded panel, the backbone of screens.
-
-    npx golem-bridge ui_frame StarterGui/MainMenu Panel --size 0.8,0,0.6,0 --radius 12
-
-**ui_label** — text label. Fonts: `regular`, `medium`, `semibold`, `bold`,
-`mono`.
-
-    npx golem-bridge ui_label StarterGui/MainMenu/Panel Title --text "Item Shop" --font semibold --text-size 20
-
-**ui_button** — text button with hover feedback built in.
-
-    npx golem-bridge ui_button StarterGui/MainMenu/Panel Buy --text "Buy"
-
-**ui_input** — TextBox the player can type into.
-
-    npx golem-bridge ui_input StarterGui/MainMenu/Panel Name --placeholder "Your name..."
-
-**ui_image** — ImageLabel showing a Roblox asset id.
-
-    npx golem-bridge ui_image StarterGui/MainMenu/Panel Icon --asset 123456 --scale fit
-
-**ui_list** — UIListLayout that auto-arranges a container's children.
-
-    npx golem-bridge ui_list StarterGui/MainMenu/Panel --direction vertical --padding 8
-
-### 4.11 Marketplace — browse and add assets
-
-`search` and `info` run on YOUR machine (Studio itself is blocked from
-roblox.com), so they work even while Studio is closed. Each takes ~5-15 s.
-Do not call them in a loop; cache results and page with `--cursor`.
-
-**search** — search the Creator Store. Categories: `model`, `mesh`,
-`image`, `audio`, `video`, `plugin`. Results carry id, name, creator,
-price, and a thumbnail URL. Open the thumbnail to judge the asset before
-inserting.
-
-    npx golem-bridge search castle --category model --limit 5
-
-**info** — details plus thumbnail for one asset.
-
-    npx golem-bridge info 487667385
-
-**insert** — place an asset into the open place. ONLY free assets
-(`priceInRobux` null or 0) or assets the user owns. Paid or restricted
-assets fail with "Asset is not trusted". If that happens, pick a different
-result.
-
-    npx golem-bridge insert 487667385 Workspace --name "Castle Wall"
-
-**apply** — set an asset-backed property: `Image`, `Texture`, `SoundId`,
-`MeshId`, and similar.
-
-    npx golem-bridge apply 123456 Workspace/Sign/Decal Texture
-
-Workflow: search, open thumbnails, `info` the shortlist, `insert`, verify
-with `tree`/`read`, set a `waypoint`. Tell the user what you added and
-where it landed.
-
-### 4.12 Playtesting
-
-**play** — start a play test (`play` = full client when Studio allows it,
-`run` = server simulation). The bridge keeps serving your commands while
-the game runs.
-
-**logs** — Studio output: errors and warnings by default, from the server
-AND the client, live while the test runs. `--all` adds prints.
-
-**stop** — end the running test. Always stop it when you are done.
-
-Workflow: build, Ctrl+S, `play`, wait 10-20 s so scripts can run and fail,
-`logs`, fix every error, `stop`, save, re-test until clean.
-
-    npx golem-bridge play
-    npx golem-bridge logs
-    npx golem-bridge stop
-
-### 4.13 Session and talking to the user
-
-**waypoint** — named undo checkpoint ("one clean undo away"). Set one
-before risky edits and at every milestone.
-
-    npx golem-bridge waypoint "before refactor"
-
-**undo** — one Studio undo step. Edit mode only.
-
-**look** — aim the user's editor camera at your work so they see it.
-
-    npx golem-bridge look Workspace/Castle --distance 60
-
-**say** — post a message to the Studio chat AND close the turn. Only for
-finished chunks of work (see §0).
-
-**turn** — the ritual (§0). `turn begin` opens the turn; `turn end --note
-"..."` closes it and posts the note as the reply the user reads. A turn
-left unclosed blocks your next command until the note is posted.
-
-## 5. Op reference (for `exec`)
-
-| op (aliases) | args | returns |
-|---|---|---|
-| `ping` | — | plugin/Studio/place info |
-| `run` (`eval`,`exec`) | `code` | `{returnCount, values}` — runs Lua with plugin permissions |
-| `list` (`ls`) | `path`, `recursive`, `max` | children (or descendants) records |
-| `tree` | `path`, `depth`, `maxChildren`, `maxNodes` | nested tree |
-| `read` (`cat`,`stat`) | `path`, `props` | properties, `source?`, `attributes?`, children |
-| `create` | `class`, `parent`, `name?`, `source?`, `props?` | record of the new instance |
-| `write` | `path`, `source?`, `props?` | record of the updated instance |
-| `script` | `parent`, `name`, `class?` (Script/LocalScript/ModuleScript), `mode?` (create/update/replace), `source` | record of the script |
-| `place` | `path`, `position` {x,y,z}, `orientation?` {x,y,z} degrees | absolute reposition (parts AND models, via pivot) |
-| `paint` | `path`/`paths`, `color?` "#RRGGBB", `material?`, `transparency?`, `reflectance?` | `{count}` — parts painted (models: all their parts) |
-| `rename` | `path`, `name` (no `/` in names!) | `{path, name, old}` |
-| `look` | `path` or `position`, `distance?` | aims the editor camera so the user sees the work |
-| `count` | `scope?`, `class?` | `{count}` — cheap totals, no payloads |
-| `undo` | — | one Studio undo step (reverts the last change) |
-| `anchor` | `path`/`paths`, `anchored?` (default true) | `{count}` — parts anchored (models: all parts) |
-| `collide` | `path`/`paths`, `canCollide?` (default true) | `{count}` — collision toggled |
-| `light` | `path`, `type?` point/spot/surface, `color?` "#RRGGBB", `range?` 0-60, `brightness?`, `shadows?` | the light's record |
-| `sound` | `parent`, `id`, `volume?`, `looped?`, `play?`, `name?` | the sound's record (plays immediately with `play`) |
-| `scatter` | `path`, `count` (max 200), `radius`, `yJitter?`, `parent?`, `name?` | `{count, copies}` — random disc placement of clones |
-| `weld` | `path`/`paths` | `{count}` — WeldConstraints joining every part to the first |
-| `hitbox` | `path`, `padding?`, `name?`, `canCollide?`, `anchored?` | invisible hitbox part sized to the target's bounding box |
-| `prompt` | `path`, `action`, `object?`, `hold?`, `distance?` | ProximityPrompt ("Press E to ...") on the part |
-| `particles` | `path`, `preset` leaves/sparks/smoke/magic/fire/snow/rain/bubbles/dust/confetti/fireflies, `rate?`, `color?` | ParticleEmitter with the preset applied |
-| `sign` | `text`, `position?`, `parent?`, `size?`, `name?` | a wooden sign part with readable text (SurfaceGui) |
-| `attributes` (`attr`) | `path`, `set?` {k: string/number/boolean/{x,y,z}}, `clear?` [k] | the instance's attributes |
-| `tag` | `path`/`paths`, `add?` [tag], `remove?` [tag] | tags applied; find them again with `find --tag <tag>` |
-| `match` | `from` (a part), `paths`/`to` | copies color/material/transparency/reflectance onto targets |
-| `beam` | `from`, `to` (two parts), `color?`, `width?`, `curve?`, `name?` | glowing beam between the parts |
-| `trail` | `path` (a part), `color?`, `lifetime?`, `name?` | motion Trail, visible when the part moves |
-| `explosion` | `position?` {x,y,z}, `radius?` | one-shot Explosion, visual only, harmless by default |
-| `ui_screen` | `name`, `parent?` (default StarterGui), `order?` | ScreenGui container, the root of every interface |
-| `ui_frame` | `parent`, `name`, `position?`/`size?` ("xs,xo,ys,yo"), `color?`, `radius?`, `anchor?` ("x,y"), `transparency?`, `clip?` | rounded panel |
-| `ui_label` | `parent`, `name`, `text`, `align?`, `wrap?`, `color?`, `font?` (regular/medium/semibold/bold/mono), `text_size?` | text label |
-| `ui_button` | `parent`, `name`, `text`, `color?`, `text_color?`, `radius?`, `size?` | TextButton with hover feedback |
-| `ui_input` | `parent`, `name`, `placeholder?`, `text?`, `background?` | TextBox the player can type into |
-| `ui_image` | `parent`, `name`, `asset` (id), `scale?` (fit/stretch/tile), `size?` | ImageLabel showing a Roblox asset |
-| `ui_list` | `parent`, `direction?` (vertical/horizontal), `padding?`, `halign?`, `valign?` | UIListLayout, auto-arranges the container's children |
-| `play` | `mode?` (play = full client when Studio allows it, run = server simulation) | starts a play test; the bridge keeps serving while the game runs |
-| `stop` | — | stops the running play test |
-| `logs` | `filter?` (errors = default, all), `limit?`, `since?` (unix ts; defaults to the test's start) | Studio output, server AND client, live during the test |
-| `delete` (`rm`) | `path` or `paths` | `{deleted: [...]}` |
-| `move` (`mv`) | `path`, `parent` | record |
-| `find` | `query`, `class?`, `scope?`, `max?`, `exact?`, `caseSensitive?` | `{results: [...]}` |
-| `grep` | `pattern`, `scope?`, `max?`, `plain?`, `caseSensitive?` | `{matches: [{path, line, text}]}` |
-| `selection` | `set?` (array of paths), `clear?` | `{selection: [...]}` |
-| `search` | `query`, `category?` (model/mesh/image/audio/video/plugin), `limit?`, `cursor?` | runs on your machine: `{results: [{id, name, creator, priceInRobux, thumbnail, ...}], nextPageCursor?}` |
-| `info` | `id` | runs on your machine: name, description, creator, price, thumbnail |
-| `insert_asset` (`insert`) | `id`, `parent?` (default Workspace), `name?` | records of inserted instances |
-| `apply_asset` (`apply`) | `id`, `path`, `prop` | record + `appliedProperty`/`appliedValue` |
-| `say` | `text` | posts a chat message AND closes the turn |
-| `rotate` (`rot`) | relative: `axis` ("x"/"y"/"z"/"up"/"right"/"forward" or {x,y,z}) + `degrees`, `space?` world/local — rotates IN PLACE; absolute: `orientation` {x,y,z} degrees | rotated records |
-| `face` | `path`, `target` {x,y,z} (or `direction`), `axis?` forward/up/right | aims it, keeps position |
-| `shift` | `path`/`paths`, `offset` {x,y,z} studs, `space?` world/local | moved paths |
-| `scale` | `path`, `factor` (relative multiplier) | record |
-| `duplicate` (`dup`) | `path`, `count?`, `offset?` (per copy), `parent?`, `name?` | records of copies |
-| `group` | `paths`, `name?`, `parent?` | new Model record |
-| `set_pivot` (`pivot`) | `path`, `position?` and/or `orientation?` {x,y,z} degrees | pivot info |
-| `terrain` | `action` fill/clear, `shape` block/ball, `position`, `size`/`radius`, `material?` | region filled |
-| `waypoint` | `label?` | `{ok}` — an undo checkpoint in Studio's history |
-
-Instance records look like
-`{"name":"Main","className":"Script","ref":"I:12","path":"ServerScriptService/Main","children":0}`.
-
-## 6. Property value formats (JSON to Roblox)
-
-| Roblox type | JSON |
-|---|---|
-| number/string/bool | `1.5`, `"text"`, `true` |
-| Vector3 | `{"type":"Vector3","x":0,"y":10,"z":0}` |
-| Color3 | `"#FF7700"` or `{"type":"Color3","r":1,"g":0.5,"b":0}` |
-| CFrame | `{"type":"CFrame","position":{...},"lookAt":{...}}` |
-| UDim2 | `{"type":"UDim2","xScale":0,"xOffset":10,"yScale":0,"yOffset":20}` |
-| EnumItem | `"Enum.Material.Neon"` |
-| Instance | a path string or `{"type":"Instance","ref":"I:3"}` |
-| Orientation (Vector3, degrees) | `{"type":"Vector3","x":0,"y":90,"z":0}` — rotates in place, keeps position |
-
-The marker key is `type`, never `$type`: the relay rejects any key starting
-with `$`, which would kill the entire command. Values you read back already
-use `type`, so they can be copied straight into `props`.
-
-## 7. Building and orientation — read before placing parts
-
-Coordinates: **+Y is up**, one unit = one stud, rotations are degrees.
-
-**The #1 trap: cylinders (and most trunk or branch-like meshes) have their
-length along the X axis.** A vertical trunk needs `Orientation (0, 0, 90)`.
-Always set orientation when creating such parts. `create` accepts top-level
-`position` {x,y,z} and `orientation` {x,y,z} in degrees:
-
-    npx golem-bridge exec '{"op":"create","args":{"class":"Part","parent":"Workspace","name":"Trunk","position":{"x":0,"y":6,"z":0},"orientation":{"x":0,"y":0,"z":90},"props":{"Shape":"Enum.PartType.Cylinder","Anchored":true,"Material":"Enum.Material.Wood","Color":"#8B5A2B","Size":{"type":"Vector3","x":12,"y":2,"z":2}}}}'
-
-(Height 12 runs along X, so orientation (0,0,90) stands it up. Ball canopies
-need no orientation.)
-
-**Rotating: use the tools, never raw CFrames.**
-
-- relative: `rotate <path> --axis y --degrees 90` (world axis); `--space
-  local` uses the part's own axis (tilt a branch: `--axis z --degrees 30
-  --space local`)
-- absolute: `rotate <path> --set 0,90,0` (sets Orientation exactly)
-- aim at a point: `face <path> 10,5,0` (forward axis by default, `--axis up`
-  to point its top at something). Great for branches, signs, cannons.
-- never write a bare CFrame without a position. It teleports the part to
-  the origin.
-
-**Positioning and copying:**
-
-- move by offset: `shift <path> 0,5,0` (world) or `--space local`
-- copy in a line: `duplicate <path> --count 5 --offset 4,0,0`
-- resize: `scale <path> 1.5` (relative; models scale as a whole)
-- wrap into a Model: `group <partA> <partB> --name Tree`
-
-**Rotating models correctly:** models rotate around their **pivot**. After
-grouping, put the pivot where the rotation center should be (usually the
-base): `pivot Workspace/Tree --position 0,0,0`. Now `rotate Workspace/Tree
---axis y --degrees 45` spins the whole tree around its base.
-
-**Verify:** `read` the part afterwards and check `Orientation`/`Position`.
-Wrong? Fix with `rotate --set` or `shift`. Cheap, and every change is an
-undo checkpoint.
-
-**Terrain:** `terrain --action fill --shape block --position 0,-4,0 --size
-128,8,128 --material Grass`; `--shape ball --radius 20` for blobs;
-`--action clear` carves (fills with Air).
-
-## 8. `lua` examples (the escape hatch — full Studio plugin API)
-
-    -- count parts
-    local n = 0
-    for _, inst in ipairs(workspace:GetDescendants()) do
-        if inst:IsA("BasePart") then n = n + 1 end
-    end
-    return {parts = n, place = game.Name}
-
-    -- insert a catalog asset
-    local asset = game:GetService("InsertService"):LoadAsset(189707834)
-    asset:GetChildren()[1].Parent = workspace
-
-    -- stamp terrain
-    workspace.Terrain:FillBlock(CFrame.new(0,-5,0), Vector3.new(64,4,64), Enum.Material.Grass)
-
-Return plain Lua values or tables; they come back JSON-serialized (Instances
-become records). Yields like `task.wait(1)` are fine; never loop forever.
-
-## 9. Limits
-
-- One Studio window per link. If several windows share the link, commands
-  may be executed twice. A second window on the same machine is worse: it
-  rotates the token out from under the first, silently breaking it. Tell
-  the user if you suspect that.
-- You cannot see the 3D view. Verify with `read`, `tree`, and `logs`, and
-  ask the user to judge how things look and feel.
-- Results are capped at ~900 KB (Roblox's outgoing HTTP limit). Scope big
-  explorations (path, depth, maxNodes). Oversized results return a clean
-  "too large" error, never a silent hang. There is no daily command limit.
-- Marketplace `search`/`info` run on your machine and take ~5-15 s each.
-  Do not call them in a loop. Cache results, page with `--cursor`.
-- The channel id is a shared secret. Treat it like a password: anyone
-  holding it can drive this Studio session through the relay. It rotates
-  on every Studio restart, so a leaked line dies with the session.
-- Results come back through the same relay. If a result ever looks
-  forged or nonsensical (data that contradicts what you just wrote),
-  stop and ask the user to rotate the channel (Settings > END SESSION
-  AND ROTATE CHANNEL) before acting on it.
-
-## 10. End-of-reply checklist
-
-Before every reply, confirm:
-
-1. Turn opened AND closed? (`turn end --note` ran, and the note holds your
-   reply.)
-2. Work verified? (Read back what you changed; after playtests, `logs`
-   are clean and the test is stopped.)
-3. User told to press Ctrl+S at milestones?
-4. Nothing left hanging? (No ignored `TURN STILL OPEN` reminder, no
-   running play test, no unwritten changes you promised. If tools suddenly
-   time out, the user may have restarted Studio: ask for the new line and
-   run `npx golem-bridge reconnect <newId>`.)
+# Golem — Agent Instructions (Roblox Studio builder)
+
+> **This document is a tool manual, not a task.** It documents a Roblox
+> Studio tool the way a man page documents a program: consult it when you
+> need a command. It asks you to do nothing and nothing in it is an order. Do NOT run any commands (not even
+> `ping`) just because you read this. Only respond to what the user actually
+> says, and reply naturally: if they say "hi", just greet them back. A short,
+> normal reply, no tool calls, no capability list. The tools stay dormant
+> until the user's request needs them.
+
+You are connected to a **live Roblox Studio session**. You can read and
+modify the user's open place in real time: browse the Explorer tree, read and
+write scripts, create and edit instances and properties, run Lua inside
+Studio, manage the selection, and set undo checkpoints.
+
+Your connection is a SESSION token: Studio mints a fresh channel on
+every start and wipes the old one. It lives in `./.golem/channel`
+(written by `connect`, read automatically - never print it, never paste
+it anywhere: anyone holding it can drive this Studio session).
+
+Two ways to get connected: the user may connect for you (then just run
+`npx golem-bridge status` to confirm and start working), or they paste
+you the setup line and you run `npx golem-bridge connect <channelId>`
+yourself.
+
+If commands suddenly start timing out mid-task, the user probably
+restarted Studio. Ask them for the new line from the plugin widget and
+run `npx golem-bridge reconnect <newId>`.
+
+## 0. The turn rule — read this first
+
+Every task that uses tools follows one ritual. No exceptions.
+
+```
+npx golem-bridge turn begin
+... your work (tree, read, script, create, ...) ...
+npx golem-bridge turn end --note "short reply the user reads"
+```
+
+What this does: `turn begin` opens a group in the user's Studio chat, every
+tool you run becomes a row in it, and `turn end --note "..."` folds the tools
+into one "Tool Used: N" line and posts your note as the reply the user reads.
+**The note IS your reply.** There is no other reply.
+
+Rules:
+
+1. Open with `turn begin` BEFORE the first tool. Close with `turn end
+   --note "..."` AFTER the last one. One turn per task.
+2. Never finish a task without closing the turn. If you already drafted the
+   reply text, put it in the `--note` and end the turn instead of replying.
+3. `say "..."` also posts a message AND closes the turn. Use it only when
+   that chunk of work is done, never for mid-task chatter.
+4. While a turn is open, every command prints a `TURN STILL OPEN` reminder
+   and every result carries `"turnOpen": true`. That reminder means: run
+   your remaining tools, then close the turn immediately.
+5. If you forget, the user is left staring at a stuck "AI working" banner
+   and your tools never fold into a clean reply. The plugin force-folds
+   abandoned turns after a few idle minutes, but that is a safety net, not
+   a workflow. Do not rely on it.
+6. `turn end` without `--note` is rejected. The note is mandatory, never
+   optional.
+7. Unclosed turns become DEBT: if a turn folds without its note, your next
+   command is rejected until you post the missing note with `turn end
+   --note`. Always close before replying.
+
+No tools needed for a reply (a greeting, a question, an explanation)? Then
+no turn is needed either. Just reply normally.
+
+## 1. The command
+
+All Studio commands go through one CLI: `npx golem-bridge`
+(zero-dependency Node - nothing is installed, every command runs
+straight from the package). Below, `golem-bridge ...` always means:
+
+    npx golem-bridge ...
+
+Your channel lives in `./.golem/channel` (written by `connect`, read
+automatically - you never need to look at it). If commands say you are
+not connected, ask the user for their channel ID (shown in the Golem
+plugin widget) and run:
+
+    npx golem-bridge connect <channelId>
+
+If the user restarted Studio, a restart rotates the channel, so fetch the
+new session with the fresh line from the widget:
+
+    npx golem-bridge reconnect <newChannelId>
+
+Then check the connection:
+
+    npx golem-bridge ping
+
+`ping` must return `"ok": true` plus the place name. If it times out,
+Roblox Studio is not running. Tell the user and retry when they confirm
+it is open. **Studio must stay open while you work.** Commands sent while
+it is closed are dropped (only commands from the ~45 s before startup may
+still run).
+
+Every command takes a few seconds (relay latency plus a short startup).
+That is normal. Do not retry faster; the CLI already waits. Every
+result is JSON:
+
+    {"ok": true, "result": {...}, "turnOpen": false}
+
+`"ok": false` means Studio reported an error; the `error` field says why.
+Fix the call and retry. Add `--timeout N` (seconds, default 120) to any
+command that may be slow.
+
+## 2. Golden rules
+
+1. Inspect before you change (`tree`, `list`, `read`). Verify after
+   (`read` it back, `grep` your new symbols).
+2. Never run infinite loops in `lua`. It executes on Studio's main thread
+   and freezes the editor.
+3. Confirm destructive actions with the user first: deleting instances,
+   overwriting existing scripts, bulk changes.
+4. Every change is individually undoable (Ctrl+Z). The plugin sets undo
+   checkpoints automatically, and you can set named ones with `waypoint`.
+5. Report paths in slash form (`ServerScriptService/Main`) so the user can
+   find them in the Explorer.
+6. Follow the turn rule (§0) for every task that uses tools.
+7. Build UI as instances, never as runtime code (see §4.10).
+8. Protect the user's work: only the user's Ctrl+S commits to the place
+   file. After every meaningful milestone, tell the user "press Ctrl+S to
+   keep my work" and wait for their confirmation before moving on.
+
+## 3. Paths
+
+Services: `Workspace`, `ReplicatedStorage`, `ServerScriptService`,
+`ServerStorage`, `StarterGui`, `StarterPlayer/StarterPlayerScripts`,
+`StarterPack`, `Lighting`, `SoundService`.
+
+| Form | Example |
+|---|---|
+| root | `game` |
+| slash form (preferred; dots in names OK) | `ReplicatedStorage/My.Module/Helper` |
+| dotted form (no slashes) | `game.ReplicatedStorage.Modules` |
+| session ref from a previous reply | `I:17` |
+
+**Symbols you must not use in instance NAMES:** `/` (it is the path
+separator, a name with `/` breaks every path). Also avoid `.` `[` `]`
+`#` `$` in names, use `-` or `_` instead. Everywhere else symbols are
+fine: `lua` results may contain any table keys, and script sources can
+contain any UTF-8 text (odd bytes are sanitized automatically).
+
+## 4. Tools
+
+### 4.1 Connection and diagnostics
+
+**ping** — health check. Expect `"ok": true` plus the place name. The first
+command on a fresh setup, and the "is Studio open?" test whenever commands
+start timing out.
+
+    npx golem-bridge ping
+
+**status** — is the plugin alive? Reads the channel's recent beacons, no
+Studio round-trip needed. Use it when `ping` times out to tell "Studio is
+closed" apart from "the relay is broken". If the channel was rotated,
+`status` says so outright — fetch the fresh line and `reconnect`.
+
+    npx golem-bridge status
+
+**debug** — full diagnostics: relay round-trip, versions, commands served,
+error count. Use when something behaves strangely.
+
+    npx golem-bridge debug
+
+### 4.2 Exploring — start every task here
+
+**tree** — nested instance tree. The fastest way to learn a place's layout.
+Defaults: path `game`, depth 2. Keep depth small on big places.
+
+    npx golem-bridge tree game --depth 2
+    npx golem-bridge tree Workspace --depth 3
+
+**list** — children of one instance. Add `--recursive` for all descendants
+and `--max N` to cap them.
+
+    npx golem-bridge list ServerScriptService
+    npx golem-bridge list game --recursive --max 1000
+
+**count** — cheap instance count, no payload. Good for orientation ("how big
+is this place?") and before/after checks.
+
+    npx golem-bridge count Workspace --class Part
+
+**find** — find instances by name substring (case-sensitive) or by
+CollectionService tag. `--exact` matches the full name; `--class` and
+`--scope` narrow the search.
+
+    npx golem-bridge find Coin --class Part --scope Workspace
+    npx golem-bridge find --tag Choppable
+
+**grep** — search inside script sources. Plain text, case-sensitive unless
+`-i`. Returns path, line number, and matching text.
+
+    npx golem-bridge grep applyDamage --scope ServerScriptService
+
+### 4.3 Reading instances
+
+**read** — full record of one instance. Scripts print raw source by default;
+`--json` prints the whole record (properties, attributes, children);
+`--props A,B` adds extra properties.
+
+    npx golem-bridge read ServerScriptService/Main
+    npx golem-bridge read Workspace/Spawn --json
+
+### 4.4 Scripts and Lua
+
+**script** — create or rewrite a Script, LocalScript, or ModuleScript in one
+call. Source comes from stdin (heredoc) or `--source`. Modes: `create`
+(fails if the name exists), `update` (keeps the instance, replaces the
+source), `replace` (deletes and recreates).
+
+    npx golem-bridge script ServerScriptService Main --class Script --mode create <<'EOF'
+    print("hello")
+    EOF
+
+**lua** — run arbitrary Lua inside Studio with plugin permissions. Pass code
+as an argument or pipe it in (`-`). Return plain values or tables; returned
+instances come back as records. Yields like `task.wait(1)` are fine. Never
+loop forever (see rule 2).
+
+    npx golem-bridge lua 'return 1+1'
+    npx golem-bridge lua - < code.lua
+
+**exec** — raw op call for anything without a dedicated command. Takes one
+JSON object with `op` and `args` (see §5).
+
+    npx golem-bridge exec '{"op":"list","args":{"path":"game"}}'
+
+### 4.5 Organizing
+
+**delete** — delete one or more instances. Destructive: confirm with the
+user first.
+
+    npx golem-bridge delete Workspace/OldPart Workspace/OldModel
+
+**move** — reparent an instance.
+
+    npx golem-bridge move Workspace/Part ServerStorage
+
+**rename** — rename an instance. The new name must not contain `/`.
+
+    npx golem-bridge rename Workspace/Part1 FrontDoor
+
+**group** — wrap instances into a new Model. After grouping, set the pivot
+(see `pivot`) before rotating the group.
+
+    npx golem-bridge group Workspace/Trunk Workspace/Canopy --name Tree
+
+**duplicate** — clone an instance, optionally N times. `--offset x,y,z`
+shifts each copy (copy i gets offset x i), so rows and grids are one
+command.
+
+    npx golem-bridge duplicate Workspace/Fence --count 5 --offset 4,0,0
+
+**selection** — read the Studio selection, or set it (highlights instances
+for the user), or clear it.
+
+    npx golem-bridge selection --set Workspace/PartA,Workspace/PartB
+
+### 4.6 Moving and rotating — use these, never raw CFrames
+
+**place** — absolute position (parts and models). The only command that
+teleports to coordinates. Optional `--orientation` sets absolute rotation
+in degrees.
+
+    npx golem-bridge place Workspace/Crate 10,5,0
+
+**shift** — move by an offset in studs, in world space (default) or the
+part's own space (`--space local`).
+
+    npx golem-bridge shift Workspace/Crate 0,5,0
+
+**rotate** — THE way to rotate. Relative mode spins in place around an axis
+(`x`, `y`, `z`, or `up`, `right`, `forward`, or an `x,y,z` vector) in world
+or local space. Absolute mode (`--set`) writes the orientation in degrees.
+
+    npx golem-bridge rotate Workspace/Door --axis y --degrees 90
+    npx golem-bridge rotate Workspace/Door --set 0,90,0
+
+**face** — aim an instance at a world point, keeping its position. Good for
+branches, signs, cannons. `--axis` picks which side points at the target.
+
+    npx golem-bridge face Workspace/Cannon 0,5,30
+
+**scale** — resize by a relative multiplier. Models scale as a whole.
+
+    npx golem-bridge scale Workspace/Tree 1.5
+
+**pivot** — move a model or part pivot (the point it rotates around). Give
+`--position`, `--orientation`, or both. After grouping a build, put the
+pivot at its base so rotations look right.
+
+    npx golem-bridge pivot Workspace/Tree --position 0,0,0
+
+### 4.7 Surfaces, terrain, and physics
+
+**paint** — set color (`#RRGGBB`), material (`Grass`, `Neon`, `WoodPlanks`,
+`SmoothPlastic`, ...), transparency, and reflectance on parts. Models: all
+their parts. Combine flags freely.
+
+    npx golem-bridge paint Workspace/Wall --color #B0B0B0 --material SmoothPlastic
+
+**match** — copy color, material, transparency, and reflectance from one
+part onto others. Keeps builds visually consistent.
+
+    npx golem-bridge match Workspace/WallA Workspace/WallB Workspace/WallC
+
+**anchor** — anchor parts so physics never moves them (models: all parts).
+`--off` unanchors. Static builds should always be anchored.
+
+    npx golem-bridge anchor Workspace/House
+
+**collide** — collision on or off (models: all parts). `--off` makes parts
+walk-through.
+
+    npx golem-bridge collide Workspace/GhostWall --off
+
+**terrain** — fill or carve terrain. `--position` is required; blocks need
+`--size`, balls need `--radius`. `--action clear` carves (fills with Air).
+
+    npx golem-bridge terrain --action fill --shape block --position 0,-4,0 --size 128,8,128 --material Grass
+
+### 4.8 Gameplay helpers
+
+**light** — add or update a light inside a part. Types: `point`, `spot`,
+`surface`.
+
+    npx golem-bridge light Workspace/Lamp --type point --color #FFD9A0 --range 30 --brightness 2
+
+**sound** — add a Sound to a parent. `--play` previews it immediately,
+`--loop` loops it.
+
+    npx golem-bridge sound Workspace 1837879082 --name Radio --volume 0.5 --play
+
+**scatter** — clone a template into a random disc around it. Trees, rocks,
+grass: build one, scatter the rest.
+
+    npx golem-bridge scatter Workspace/Tree --count 20 --radius 60 --y-jitter 2
+
+**weld** — join a model's parts with WeldConstraints so the whole build
+moves as one.
+
+    npx golem-bridge weld Workspace/Cart
+
+**hitbox** — invisible part sized to the target's bounding box. Click and
+chop targets, interaction zones. `--collide` makes it solid.
+
+    npx golem-bridge hitbox Workspace/Tree --padding 1
+
+**prompt** — ProximityPrompt ("Press E to ...") on a part. `--object` is
+the title above it, `--hold` the hold time in seconds.
+
+    npx golem-bridge prompt Workspace/Tree "Chop" --object Tree --hold 0.5
+
+**particles** — attach a ParticleEmitter with a preset: `leaves`, `sparks`,
+`smoke`, `magic`, `fire`, `snow`, `rain`, `bubbles`, `dust`, `confetti`,
+`fireflies`.
+
+    npx golem-bridge particles Workspace/Torch fire --rate 40
+
+**sign** — a readable wooden sign: board part with text on its face.
+
+    npx golem-bridge sign "Camp rules: no griefing" --position 0,6,10
+
+**attr** — Studio attributes: typed config on instances without scripts.
+`--set` repeats; values parse as integer, float, `true`/`false`, or string.
+
+    npx golem-bridge attr Workspace/Door --set Open=false --set LockLevel=3
+
+**tag** — add or remove CollectionService tags. Find tagged instances later
+with `find --tag`.
+
+    npx golem-bridge tag Workspace/Tree --add Choppable
+
+### 4.9 VFX
+
+**beam** — glowing beam between two parts. Lasers, tethers, energy links.
+
+    npx golem-bridge beam Workspace/TowerA Workspace/TowerB --color #78B4FF --width 0.4
+
+**trail** — motion trail on a part. Shows when the part moves: sword
+swipes, comet tails.
+
+    npx golem-bridge trail Workspace/Sword --lifetime 0.6
+
+**explosion** — one-shot visual explosion. Harmless by default: no physics
+damage.
+
+    npx golem-bridge explosion --position 0,10,0 --radius 8
+
+### 4.10 UI — build interfaces as instances, not code
+
+When the user asks for any UI (shop, HUD, menu, popup, note):
+
+1. Build it with the `ui_*` tools below: real instances under `StarterGui`,
+   visible in the Explorer so the user can select, move, and restyle them.
+2. NEVER write a LocalScript that builds the UI when the game runs.
+   Runtime-generated UI is invisible in Studio. LocalScripts may only wire
+   behavior to UI that already exists, or fill data-driven content (like a
+   shop list from a config).
+3. Keep one style across the game: same fonts, corner radius, paddings,
+   palette. Before building a new screen, `read` an existing screen and
+   copy its fonts, sizes, and colors exactly. A different font is allowed
+   only as a deliberate choice (a parchment note, a decorative title).
+4. Prefer changing state over rebuilding: toggle visibility, update `Text`,
+   tween positions. Do not destroy and recreate screens.
+
+Positions and sizes use `"xs,xo,ys,yo"` (scachment note, a decorative title).
+4. Prefer changing state over rebuilding: toggle visibility, update `Text`,
+   tween positions. Do not destroy and recreate screens.
+
+Positions and sizes use `"xs,xo,ys,yo"` (scale/offset pairs); anchors use
+`"x,y"`.
+
+**ui_screen** — ScreenGui under StarterGui. The root of every interface.
+
+    npx golem-bridge ui_screen MainMenu
+
+**ui_frame** — rounded panel, the backbone of screens.
+
+    npx golem-bridge ui_frame StarterGui/MainMenu Panel --size 0.8,0,0.6,0 --radius 12
+
+**ui_label** — text label. Fonts: `regular`, `medium`, `semibold`, `bold`,
+`mono`.
+
+    npx golem-bridge ui_label StarterGui/MainMenu/Panel Title --text "Item Shop" --font semibold --text-size 20
+
+**ui_button** — text button with hover feedback built in.
+
+    npx golem-bridge ui_button StarterGui/MainMenu/Panel Buy --text "Buy"
+
+**ui_input** — TextBox the player can type into.
+
+    npx golem-bridge ui_input StarterGui/MainMenu/Panel Name --placeholder "Your name..."
+
+**ui_image** — ImageLabel showing a Roblox asset id.
+
+    npx golem-bridge ui_image StarterGui/MainMenu/Panel Icon --asset 123456 --scale fit
+
+**ui_list** — UIListLayout that auto-arranges a container's children.
+
+    npx golem-bridge ui_list StarterGui/MainMenu/Panel --direction vertical --padding 8
+
+### 4.11 Marketplace — browse and add assets
+
+`search` and `info` run on YOUR machine (Studio itself is blocked from
+roblox.com), so they work even while Studio is closed. Each takes ~5-15 s.
+Do not call them in a loop; cache results and page with `--cursor`.
+
+**search** — search the Creator Store. Categories: `model`, `mesh`,
+`image`, `audio`, `video`, `plugin`. Results carry id, name, creator,
+price, and a thumbnail URL. Open the thumbnail to judge the asset before
+inserting.
+
+    npx golem-bridge search castle --category model --limit 5
+
+**info** — details plus thumbnail for one asset.
+
+    npx golem-bridge info 487667385
+
+**insert** — place an asset into the open place. ONLY free assets
+(`priceInRobux` null or 0) or assets the user owns. Paid or restricted
+assets fail with "Asset is not trusted". If that happens, pick a different
+result.
+
+    npx golem-bridge insert 487667385 Workspace --name "Castle Wall"
+
+**apply** — set an asset-backed property: `Image`, `Texture`, `SoundId`,
+`MeshId`, and similar.
+
+    npx golem-bridge apply 123456 Workspace/Sign/Decal Texture
+
+Workflow: search, open thumbnails, `info` the shortlist, `insert`, verify
+with `tree`/`read`, set a `waypoint`. Tell the user what you added and
+where it landed.
+
+### 4.12 Playtesting
+
+**play** — start a play test (`play` = full client when Studio allows it,
+`run` = server simulation). The bridge keeps serving your commands while
+the game runs.
+
+**logs** — Studio output: errors and warnings by default, from the server
+AND the client, live while the test runs. `--all` adds prints.
+
+**stop** — end the running test. Always stop it when you are done.
+
+Workflow: build, Ctrl+S, `play`, wait 10-20 s so scripts can run and fail,
+`logs`, fix every error, `stop`, save, re-test until clean.
+
+    npx golem-bridge play
+    npx golem-bridge logs
+    npx golem-bridge stop
+
+### 4.13 Session and talking to the user
+
+**waypoint** — named undo checkpoint ("one clean undo away"). Set one
+before risky edits and at every milestone.
+
+    npx golem-bridge waypoint "before refactor"
+
+**undo** — one Studio undo step. Edit mode only.
+
+**look** — aim the user's editor camera at your work so they see it.
+
+    npx golem-bridge look Workspace/Castle --distance 60
+
+**say** — post a message to the Studio chat AND close the turn. Only for
+finished chunks of work (see §0).
+
+**turn** — the ritual (§0). `turn begin` opens the turn; `turn end --note
+"..."` closes it and posts the note as the reply the user reads. A turn
+left unclosed blocks your next command until the note is posted.
+
+## 5. Op reference (for `exec`)
+
+| op (aliases) | args | returns |
+|---|---|---|
+| `ping` | — | plugin/Studio/place info |
+| `debug` | — | relay round-trip, versions, commands served, error count |
+| `turn_begin` | — | opens a turn group in the Studio chat (via `turn begin`) |
+| `turn_end` | `note` (required) | folds the turn and posts the note as the reply (via `turn end --note`) |
+| `run` (`eval`,`exec`) | `code` | `{returnCount, values}` — runs Lua with plugin permissions |
+| `list` (`ls`) | `path`, `recursive`, `max` | children (or descendants) records |
+| `tree` | `path`, `depth`, `maxChildren`, `maxNodes` | nested tree |
+| `read` (`cat`,`stat`) | `path`, `props` | properties, `source?`, `attributes?`, children |
+| `create` | `class`, `parent`, `name?`, `source?`, `props?` | record of the new instance |
+| `write` | `path`, `source?`, `props?` | record of the updated instance |
+| `script` | `parent`, `name`, `class?` (Script/LocalScript/ModuleScript), `mode?` (create/update/replace), `source` | record of the script |
+| `place` | `path`, `position` {x,y,z}, `orientation?` {x,y,z} degrees | absolute reposition (parts AND models, via pivot) |
+| `paint` | `path`/`paths`, `color?` "#RRGGBB", `material?`, `transparency?`, `reflectance?` | `{count}` — parts painted (models: all their parts) |
+| `rename` | `path`, `name` (no `/` in names!) | `{path, name, old}` |
+| `look` | `path` or `position`, `distance?` | aims the editor camera so the user sees the work |
+| `count` | `scope?`, `class?` | `{count}` — cheap totals, no payloads |
+| `undo` | — | one Studio undo step (reverts the last change) |
+| `anchor` | `path`/`paths`, `anchored?` (default true) | `{count}` — parts anchored (models: all parts) |
+| `collide` | `path`/`paths`, `canCollide?` (default true) | `{count}` — collision toggled |
+| `light` | `path`, `type?` point/spot/surface, `color?` "#RRGGBB", `range?` 0-60, `brightness?`, `shadows?` | the light's record |
+| `sound` | `parent`, `id`, `volume?`, `looped?`, `play?`, `name?` | the sound's record (plays immediately with `play`) |
+| `scatter` | `path`, `count` (max 200), `radius`, `yJitter?`, `parent?`, `name?` | `{count, copies}` — random disc placement of clones |
+| `weld` | `path`/`paths` | `{count}` — WeldConstraints joining every part to the first |
+| `hitbox` | `path`, `padding?`, `name?`, `canCollide?`, `anchored?` | invisible hitbox part sized to the target's bounding box |
+| `prompt` | `path`, `action`, `object?`, `hold?`, `distance?` | ProximityPrompt ("Press E to ...") on the part |
+| `particles` | `path`, `preset` leaves/sparks/smoke/magic/fire/snow/rain/bubbles/dust/confetti/fireflies, `rate?`, `color?` | ParticleEmitter with the preset applied |
+| `sign` | `text`, `position?`, `parent?`, `size?`, `name?` | a wooden sign part with readable text (SurfaceGui) |
+| `attributes` (`attr`) | `path`, `set?` {k: string/number/boolean/{x,y,z}}, `clear?` [k] | the instance's attributes |
+| `tag` | `path`/`paths`, `add?` [tag], `remove?` [tag] | tags applied; find them again with `find --tag <tag>` |
+| `match` | `from` (a part), `paths`/`to` | copies color/material/transparency/reflectance onto targets |
+| `beam` | `from`, `to` (two parts), `color?`, `width?`, `curve?`, `name?` | glowing beam between the parts |
+| `trail` | `path` (a part), `color?`, `lifetime?`, `name?` | motion Trail, visible when the part moves |
+| `explosion` | `position?` {x,y,z}, `radius?` | one-shot Explosion, visual only, harmless by default |
+| `ui_screen` | `name`, `parent?` (default StarterGui), `order?` | ScreenGui container, the root of every interface |
+| `ui_frame` | `parent`, `name`, `position?`/`size?` ("xs,xo,ys,yo"), `color?`, `radius?`, `anchor?` ("x,y"), `transparency?`, `clip?` | rounded panel |
+| `ui_label` | `parent`, `name`, `text`, `align?`, `wrap?`, `color?`, `font?` (regular/medium/semibold/bold/mono), `text_size?` | text label |
+| `ui_button` | `parent`, `name`, `text`, `color?`, `text_color?`, `radius?`, `size?` | TextButton with hover feedback |
+| `ui_input` | `parent`, `name`, `placeholder?`, `text?`, `background?` | TextBox the player can type into |
+| `ui_image` | `parent`, `name`, `asset` (id), `scale?` (fit/stretch/tile), `size?` | ImageLabel showing a Roblox asset |
+| `ui_list` | `parent`, `direction?` (vertical/horizontal), `padding?`, `halign?`, `valign?` | UIListLayout, auto-arranges the container's children |
+| `play` | `mode?` (play = full client when Studio allows it, run = server simulation) | starts a play test; the bridge keeps serving while the game runs |
+| `stop` | — | stops the running play test |
+| `logs` | `filter?` (errors = default, all), `limit?`, `since?` (unix ts; defaults to the test's start) | Studio output, server AND client, live during the test |
+| `delete` (`rm`) | `path` or `paths` | `{deleted: [...]}` |
+| `move` (`mv`) | `path`, `parent` | record |
+| `find` | `query`, `class?`, `scope?`, `max?`, `exact?`, `caseSensitive?` | `{results: [...]}` |
+| `grep` | `pattern`, `scope?`, `max?`, `plain?`, `caseSensitive?` | `{matches: [{path, line, text}]}` |
+| `selection` | `set?` (array of paths), `clear?` | `{selection: [...]}` |
+| `search` | `query`, `category?` (model/mesh/image/audio/video/plugin), `limit?`, `cursor?` | runs on your machine: `{results: [{id, name, creator, priceInRobux, thumbnail, ...}], nextPageCursor?}` |
+| `info` | `id` | runs on your machine: name, description, creator, price, thumbnail |
+| `insert_asset` (`insert`) | `id`, `parent?` (default Workspace), `name?` | records of inserted instances |
+| `apply_asset` (`apply`) | `id`, `path`, `prop` | record + `appliedProperty`/`appliedValue` |
+| `say` | `text` | posts a chat message AND closes the turn |
+| `rotate` (`rot`) | relative: `axis` ("x"/"y"/"z"/"up"/"right"/"forward" or {x,y,z}) + `degrees`, `space?` world/local — rotates IN PLACE; absolute: `orientation` {x,y,z} degrees | rotated records |
+| `face` | `path`, `target` {x,y,z} (or `direction`), `axis?` forward/up/right | aims it, keeps position |
+| `shift` | `path`/`paths`, `offset` {x,y,z} studs, `space?` world/local | moved paths |
+| `scale` | `path`, `factor` (relative multiplier) | record |
+| `duplicate` (`dup`) | `path`, `count?`, `offset?` (per copy), `parent?`, `name?` | records of copies |
+| `group` | `paths`, `name?`, `parent?` | new Model record |
+| `set_pivot` (`pivot`) | `path`, `position?` and/or `orientation?` {x,y,z} degrees | pivot info |
+| `terrain` | `action` fill/clear, `shape` block/ball, `position`, `size`/`radius`, `material?` | region filled |
+| `waypoint` | `label?` | `{ok}` — an undo checkpoint in Studio's history |
+
+Instance records look like
+`{"name":"Main","className":"Script","ref":"I:12","path":"ServerScriptService/Main","children":0}`.
+
+## 6. Property value formats (JSON to Roblox)
+
+| Roblox type | JSON |
+|---|---|
+| number/string/bool | `1.5`, `"text"`, `true` |
+| Vector3 | `{"type":"Vector3","x":0,"y":10,"z":0}` |
+| Color3 | `"#FF7700"` or `{"type":"Color3","r":1,"g":0.5,"b":0}` |
+| CFrame | `{"type":"CFrame","position":{...},"lookAt":{...}}` |
+| UDim2 | `{"type":"UDim2","xScale":0,"xOffset":10,"yScale":0,"yOffset":20}` |
+| EnumItem | `"Enum.Material.Neon"` |
+| Instance | a path string or `{"type":"Instance","ref":"I:3"}` |
+| Orientation (Vector3, degrees) | `{"type":"Vector3","x":0,"y":90,"z":0}` — rotates in place, keeps position |
+
+The marker key is `type`, never `$type`: the relay rejects any key starting
+with `$`, which would kill the entire command. Values you read back already
+use `type`, so they can be copied straight into `props`.
+
+## 7. Building and orientation — read before placing parts
+
+Coordinates: **+Y is up**, one unit = one stud, rotations are degrees.
+
+**The #1 trap: cylinders (and most trunk or branch-like meshes) have their
+length along the X axis.** A vertical trunk needs `Orientation (0, 0, 90)`.
+Always set orientation when creating such parts. `create` accepts top-level
+`position` {x,y,z} and `orientation` {x,y,z} in degrees:
+
+    npx golem-bridge exec '{"op":"create","args":{"class":"Part","parent":"Workspace","name":"Trunk","position":{"x":0,"y":6,"z":0},"orientation":{"x":0,"y":0,"z":90},"props":{"Shape":"Enum.PartType.Cylinder","Anchored":true,"Material":"Enum.Material.Wood","Color":"#8B5A2B","Size":{"type":"Vector3","x":12,"y":2,"z":2}}}}'
+
+(Height 12 runs along X, so orientation (0,0,90) stands it up. Ball canopies
+need no orientation.)
+
+**Rotating: use the tools, never raw CFrames.**
+
+- relative: `rotate <path> --axis y --degrees 90` (world axis); `--space
+  local` uses the part's own axis (tilt a branch: `--axis z --degrees 30
+  --space local`)
+- absolute: `rotate <path> --set 0,90,0` (sets Orientation exactly)
+- aim at a point: `face <path> 10,5,0` (forward axis by default, `--axis up`
+  to point its top at something). Great for branches, signs, cannons.
+- never write a bare CFrame without a position. It teleports the part to
+  the origin.
+
+**Positioning and copying:**
+
+- move by offset: `shift <path> 0,5,0` (world) or `--space local`
+- copy in a line: `duplicate <path> --count 5 --offset 4,0,0`
+- resize: `scale <path> 1.5` (relative; models scale as a whole)
+- wrap into a Model: `group <partA> <partB> --name Tree`
+
+**Rotating models correctly:** models rotate around their **pivot**. After
+grouping, put the pivot where the rotation center should be (usually the
+base): `pivot Workspace/Tree --position 0,0,0`. Now `rotate Workspace/Tree
+--axis y --degrees 45` spins the whole tree around its base.
+
+**Verify:** `read` the part afterwards and check `Orientation`/`Position`.
+Wrong? Fix with `rotate --set` or `shift`. Cheap, and every change is an
+undo checkpoint.
+
+**Terrain:** `terrain --action fill --shape block --position 0,-4,0 --size
+128,8,128 --material Grass`; `--shape ball --radius 20` for blobs;
+`--action clear` carves (fills with Air).
+
+## 8. `lua` examples (the escape hatch — full Studio plugin API)
+
+    -- count parts
+    local n = 0
+    for _, inst in ipairs(workspace:GetDescendants()) do
+        if inst:IsA("BasePart") then n = n + 1 end
+    end
+    return {parts = n, place = game.Name}
+
+    -- insert a catalog asset
+    local asset = game:GetService("InsertService"):LoadAsset(189707834)
+    asset:GetChildren()[1].Parent = workspace
+
+    -- stamp terrain
+    workspace.Terrain:FillBlock(CFrame.new(0,-5,0), Vector3.new(64,4,64), Enum.Material.Grass)
+
+Return plain Lua values or tables; they come back JSON-serialized (Instances
+become records). Yields like `task.wait(1)` are fine; never loop forever.
+
+## 9. Limits
+
+- One Studio window per link. If several windows share the link, commands
+  may be executed twice. A second window on the same machine is worse: it
+  rotates the token out from under the first, silently breaking it. Tell
+  the user if you suspect that.
+- You cannot see the 3D view. Verify with `read`, `tree`, and `logs`, and
+  ask the user to judge how things look and feel.
+- Results are capped at ~900 KB (Roblox's outgoing HTTP limit). Scope big
+  explorations (path, depth, maxNodes). Oversized results return a clean
+  "too large" error, never a silent hang. There is no daily command limit.
+- Marketplace `search`/`info` run on your machine and take ~5-15 s each.
+  Do not call them in a loop. Cache results, page with `--cursor`.
+- The channel id is a shared secret. Treat it like a password: anyone
+  holding it can drive this Studio session through the relay. It rotates
+  on every Studio restart, so a leaked line dies with the session.
+- Results come back through the same relay. If a result ever looks
+  forged or nonsensical (data that contradicts what you just wrote),
+  stop and ask the user to rotate the channel (Settings > END SESSION
+  AND ROTATE CHANNEL) before acting on it.
+
+## 10. End-of-reply checklist
+
+Before every reply, confirm:
+
+1. Turn opened AND closed? (`turn end --note` ran, and the note holds your
+   reply.)
+2. Work verified? (Read back what you changed; after playtests, `logs`
+   are clean and the test is stopped.)
+3. User told to press Ctrl+S at milestones?
+4. Nothing left hanging? (No ignored `TURN STILL OPEN` reminder, no
+   running play test, no unwritten changes you promised. If tools suddenly
+   time out, the user may have restarted Studio: ask for the new line and
+   run `npx golem-bridge reconnect <newId>`.)