golem-bridge 1.0.2 → 2.0.0

package/golem.md

@@ -0,0 +1,683 @@
+# 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 (already configured, nothing to change):
+
+- Relay database: `__DB_URL__`
+- Your private channel: `__CHANNEL_ID__`
+
+The channel is a SESSION token: Studio mints a fresh one on every start
+and wipes the old channel. 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.
+
+```
+python3 ./.golem/golem.py turn begin
+... your work (tree, read, script, create, ...) ...
+python3 ./.golem/golem.py 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 helper
+
+All Studio commands go through one script: `./.golem/golem.py`
+(zero-dependency Python 3, your channel already baked in). Below,
+`golem.py ...` always means:
+
+    python3 ./.golem/golem.py ...
+
+Keep it in `./.golem/`. If it is ever missing, ask the user for their
+channel ID (shown in the Golem plugin widget) and re-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:
+
+    golem.py 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 ~1-3 s (relay latency). That is normal. Do not retry
+faster; the helper 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.
+
+    golem.py 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".
+
+    golem.py status
+
+**debug** — full diagnostics: relay round-trip, versions, commands served,
+error count. Use when something behaves strangely.
+
+    golem.py 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.
+
+    golem.py tree game --depth 2
+    golem.py tree Workspace --depth 3
+
+**list** — children of one instance. Add `--recursive` for all descendants
+and `--max N` to cap them.
+
+    golem.py list ServerScriptService
+    golem.py list game --recursive --max 1000
+
+**count** — cheap instance count, no payload. Good for orientation ("how big
+is this place?") and before/after checks.
+
+    golem.py 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.
+
+    golem.py find Coin --class Part --scope Workspace
+    golem.py find --tag Choppable
+
+**grep** — search inside script sources. Plain text, case-sensitive unless
+`-i`. Returns path, line number, and matching text.
+
+    golem.py 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.
+
+    golem.py read ServerScriptService/Main
+    golem.py 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).
+
+    golem.py 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).
+
+    golem.py lua 'return 1+1'
+    golem.py lua - < code.lua
+
+**exec** — raw op call for anything without a dedicated command. Takes one
+JSON object with `op` and `args` (see §5).
+
+    golem.py exec '{"op":"list","args":{"path":"game"}}'
+
+### 4.5 Organizing
+
+**delete** — delete one or more instances. Destructive: confirm with the
+user first.
+
+    golem.py delete Workspace/OldPart Workspace/OldModel
+
+**move** — reparent an instance.
+
+    golem.py move Workspace/Part ServerStorage
+
+**rename** — rename an instance. The new name must not contain `/`.
+
+    golem.py rename Workspace/Part1 FrontDoor
+
+**group** — wrap instances into a new Model. After grouping, set the pivot
+(see `pivot`) before rotating the group.
+
+    golem.py 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.
+
+    golem.py 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.
+
+    golem.py 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.
+
+    golem.py 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`).
+
+    golem.py 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.
+
+    golem.py rotate Workspace/Door --axis y --degrees 90
+    golem.py 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.
+
+    golem.py face Workspace/Cannon 0,5,30
+
+**scale** — resize by a relative multiplier. Models scale as a whole.
+
+    golem.py 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.
+
+    golem.py 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.
+
+    golem.py paint Workspace/Wall --color #B0B0B0 --material SmoothPlastic
+
+**match** — copy color, material, transparency, and reflectance from one
+part onto others. Keeps builds visually consistent.
+
+    golem.py 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.
+
+    golem.py anchor Workspace/House
+
+**collide** — collision on or off (models: all parts). `--off` makes parts
+walk-through.
+
+    golem.py collide Workspace/GhostWall --off
+
+**terrain** — fill or carve terrain. `--position` is required; blocks need
+`--size`, balls need `--radius`. `--action clear` carves (fills with Air).
+
+    golem.py 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`.
+
+    golem.py 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.
+
+    golem.py 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.
+
+    golem.py 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.
+
+    golem.py weld Workspace/Cart
+
+**hitbox** — invisible part sized to the target's bounding box. Click and
+chop targets, interaction zones. `--collide` makes it solid.
+
+    golem.py 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.
+
+    golem.py 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`.
+
+    golem.py particles Workspace/Torch fire --rate 40
+
+**sign** — a readable wooden sign: board part with text on its face.
+
+    golem.py 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.
+
+    golem.py attr Workspace/Door --set Open=false --set LockLevel=3
+
+**tag** — add or remove CollectionService tags. Find tagged instances later
+with `find --tag`.
+
+    golem.py tag Workspace/Tree --add Choppable
+
+### 4.9 VFX
+
+**beam** — glowing beam between two parts. Lasers, tethers, energy links.
+
+    golem.py 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.
+
+    golem.py trail Workspace/Sword --lifetime 0.6
+
+**explosion** — one-shot visual explosion. Harmless by default: no physics
+damage.
+
+    golem.py 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.
+
+    golem.py ui_screen MainMenu
+
+**ui_frame** — rounded panel, the backbone of screens.
+
+    golem.py ui_frame StarterGui/MainMenu Panel --size 0.8,0,0.6,0 --radius 12
+
+**ui_label** — text label. Fonts: `regular`, `medium`, `semibold`, `bold`,
+`mono`.
+
+    golem.py ui_label StarterGui/MainMenu/Panel Title --text "Item Shop" --font semibold --text-size 20
+
+**ui_button** — text button with hover feedback built in.
+
+    golem.py ui_button StarterGui/MainMenu/Panel Buy --text "Buy"
+
+**ui_input** — TextBox the player can type into.
+
+    golem.py ui_input StarterGui/MainMenu/Panel Name --placeholder "Your name..."
+
+**ui_image** — ImageLabel showing a Roblox asset id.
+
+    golem.py ui_image StarterGui/MainMenu/Panel Icon --asset 123456 --scale fit
+
+**ui_list** — UIListLayout that auto-arranges a container's children.
+
+    golem.py 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.
+
+    golem.py search castle --category model --limit 5
+
+**info** — details plus thumbnail for one asset.
+
+    golem.py 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.
+
+    golem.py insert 487667385 Workspace --name "Castle Wall"
+
+**apply** — set an asset-backed property: `Image`, `Texture`, `SoundId`,
+`MeshId`, and similar.
+
+    golem.py 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.
+
+    golem.py play
+    golem.py logs
+    golem.py 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.
+
+    golem.py 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.
+
+    golem.py 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:
+
+    golem.py 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.
+
+## 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>`.)