Docvks

docs/04 - Commands & Permissions.md

@@ -1,6 +1,24 @@
 # 04 - Commands & Permissions
 
-Iris exposes one root command: `/iris` (aliases `/ir`, `/irs`). Bukkit uses VolmLib Director (named parameters, optional `key=value`). Fabric, Forge, and NeoForge register a Brigadier tree with the same root aliases. This is the complete command reference; platform gaps are marked **Bukkit-only** or **modded-only**. See `30 - Platform Differences.md` for a matrix and `03 - Configuration.md` for `/iris reload` targets.
+Iris exposes one root command, `/iris` (aliases `/ir`, `/irs`), with Bukkit using VolmLib Director for named parameters and optional `key=value` arguments. Fabric, Forge, and NeoForge register a Brigadier tree with the same root aliases. This is the complete command reference; platform gaps are marked **Bukkit-only** or **modded-only**. See `30 - Platform Differences.md` for a matrix and `03 - Configuration.md` for `/iris reload` targets.
+
+## Common command recipes
+
+Use these as entry points; follow the linked guide before running destructive or long-running forms.
+
+| Goal | Bukkit-family | Fabric / Forge / NeoForge | Success check | Detailed guide |
+|---|---|---|---|---|
+| Create and enter a disposable world | `/iris create tutorial type=overworld seed=1337`, then `/iris tp tutorial` | `/iris create tutorial overworld 1337`, then `/iris tp irisworldgen:tutorial` | World/dimension appears in `/iris worlds` or `/iris world status`; ordinary chunks generate | `02 - Getting Started.md` |
+| Validate a pack before world creation | `/iris pack validate pack=overworld` | `/iris pack validate overworld` | No blocking validation errors | `25 - Pack Management.md` |
+| Open the live authoring pack | `/iris studio open overworld seed=1337` | `/iris studio open overworld 1337` | Transient Studio world opens and a valid save hotloads | `10 - Studio & VSCode Schemas.md` |
+| Create an in-game jigsaw project | `/iris jigsaw create overworld village/demo` | Not available; author on Bukkit and copy the saved pack | Owned planar, Iris-native graph is created atomically with six 16×16×16 workcells, one variant per archetype, and seed `1337`; edits then autosave | `21 - Jigsaw Structures.md` |
+| Inspect an Iris jigsaw graph | `/iris structure info overworld <structure>` | `/iris structure info <structure>` while in its Iris dimension | Resolved graph reports pieces and bounds | `21 - Jigsaw Structures.md` |
+| Pregenerate a small test area | `/iris pregen start 352 world=<world> center=0,0 gui=false` | `/iris pregen start 352 <dimension> at 0 0` | `/iris pregen status` advances with no accumulating failures | `07 - Pregeneration.md` |
+| Remove a disposable Iris world | Evacuate players, unload, then `/iris remove <world>` | `/iris world delete <dimension>` | Target is absent from world status and its managed data is removed | `06 - Worlds & Lifecycle.md` |
+
+Do not translate Bukkit `key=value` examples token-for-token to a mod loader. Use the Brigadier forms in the matching command sections.
+
+If a command fails before doing work, check in this order: platform syntax, permission level, sender requirements (player versus console), exact pack/world key, then lifecycle busy state. A parse error is not evidence that the underlying feature failed.
 
 ## Syntax
 
@@ -74,6 +92,7 @@ Tree feller on mod loaders uses platform permission APIs (`irisworldgen:treefell
 | `pregen` | `pregenerate` | Both | see Pregen | Pregeneration control |
 | `object` | `o` | Both | see Object | Object tools |
 | `studio` | `std`, `s` | Both | see Studio | Studio / pack authoring |
+| `jigsaw` | `jig`, `jgs` | **Bukkit** | see Jigsaw | Transaction-owned planar/spatial Jigsaw Studio |
 | `pack` | `pk` | Both | see Pack | Validate/cleanup/restore/status |
 | `structure` | `struct`, `str` | Both | see Structure | Structure index/import/place |
 | `datapack` | `datapacks`, `dp` | Both | see Datapack | Datapack helpers |
@@ -170,8 +189,8 @@ See `07 - Pregeneration.md`.
 
 | Command | Aliases | Platforms | Params | Description |
 |---------|---------|-----------|--------|-------------|
-| `open` | `o` | Both | **Bukkit:** `<dimension> [seed=1337]`. **Modded:** `<pack> [seed]` | Open temporary studio dimension |
-| `close` | `x` | Both | — | Close studio and discard world |
+| `open` | `o` | Both | **Bukkit:** `<dimension> [seed=1337]`. **Modded:** `<pack> [seed]` | Open temporary studio dimension; Bukkit refuses to replace an active Jigsaw Studio outside its owner-authorized Jigsaw lifecycle |
+| `close` | `x` | Both | — | Close studio and discard world; Bukkit requires `/iris jigsaw close` for an active Jigsaw Studio |
 | `tpstudio` | `stp` | Both | — | Teleport into open studio |
 | `status` | | **Modded** (Bukkit uses other paths) | — | Show open studio and pack |
 | `create` | `+` | Both | **Bukkit:** `[name=studio] [template=<dimension>]`. **Modded:** `[name] [template=example]` | Create pack project |
@@ -193,6 +212,54 @@ See `10 - Studio & VSCode Schemas.md`.
 
 ---
 
+## Jigsaw: `/iris jigsaw` (`jig`, `jgs`)
+
+**Bukkit-only; player origin.** This opens a transient Jigsaw Studio through the same single active Studio lifecycle. Saved Iris jigsaw resources run through the shared core on every platform, but Fabric/Forge/NeoForge do not register this authoring command tree.
+
+| Command | Params | Description |
+|---|---|---|
+| `create` | `<dimension> <key> [mode=planar] [compatibility=iris] [width=16] [height=16] [depth=16] [seed=1337]` | Add-only atomic graph creation followed by open; named `structure=` and `name=` alias `key=`; `mode` completes `planar`/`spatial`, compatibility completes `iris`/`vanilla`; planar X/Z `3..128`, spatial X/Z `1..128`, Y `1..192`, volume `<=2,097,152` |
+| `convert` | `<dimension> <source> [target=auto] [seed=1337]` | Add-only conversion of one live registered vanilla/datapack jigsaw into an owned Iris graph, then open it; aliases `import`, `import-vanilla` |
+| `adopt inspect` | `<dimension> <source> [target=auto] [strategy=auto]` | Asynchronously inspect an existing Iris closure and issue a hash-pinned `IN_PLACE`, `CLONE_REQUIRED`, or `BLOCKED` plan; strategy completes `auto`, `in-place`, `clone` |
+| `adopt apply` | `<planId>` | Revalidate and atomically apply that player's unexpired plan, then open the target at seed `1337`; active/opening Jigsaw Studio is rejected |
+| `open` | `<dimension> <key> [seed=1337]` | Open an existing graph in compact workcells; aliases `edit`, `reopen`; owner, autosave, and operation barriers protect replacement |
+| `close` | `[discard=false]` | Close Studio; refuse active autosave/load/graph work or a pending dirty capture unless deliberately discarded |
+| `status` | — | Show project/workcell state and the current automatic seed-`1337` evaluation, theme, piece count, and diagnostic |
+| `menu` | — | Open the six-row controls also opened by the generated chest or three sneaks within 1.5 seconds |
+| `select` | — | Select the workcell containing the player |
+| `goto` | `<workcell>` | Select and teleport above a stable workcell ID; alias `teleport` |
+| `particles` | `<visible>` | Toggle player-local bounds and connector particles |
+| `save` | `[bay=selected]` | Flush the selected dirty workcell's automatic capture now; normal block and container updates already autosave |
+| `connector channel` | `<channel\|none>` | Look at a saved marker in the active owned workcell within 8 blocks and set/clear its Iris-only channel at the inverse-mapped source position |
+| `bounds` | `<width> <height> <depth>` | Set the selected workcell capacity without resizing any variant object; every existing variant must fit, and the compact Studio layout requires close/reopen; aliases `cell`, `resize` |
+| `workcell capacity` | `<width> <height> <depth>` | Explicit nested form of `bounds`; planar capacities are per canonical archetype and spatial capacity is the single project envelope |
+| `workcell label` | `<displayName>` | Set the selected planar or spatial workcell's author label; quote spaces; solver identity remains canonical |
+| `workcell label-reset` | — | Reset the selected workcell to its canonical solver label; alias `reset-label` |
+| `pool create` | `<poolKey> [fallbackPoolKey=none]` | Atomically create an empty owned pool, optionally using an existing owned direct fallback |
+| `piece create` | `<poolKey> <pieceKey> [weight=1]` | Create and load an owned variant; planar derives connectors from the contextual canonical workcell |
+| `piece add` | `<poolKey> <pieceKey> [weight=1]` | Re-add and load an existing piece/object already owned by this project |
+| `piece remove` | `<poolKey>` | Remove the active variant from a pool without deleting its owned resources |
+| `piece rotatable` | `<true\|false>` | Persist cardinal rotation for the active variant; portable sessions reject `false` |
+| `piece expand` | — | Resize the active planar or spatial owned variant exactly to workcell capacity; planar canonical sockets move to the new faces |
+| `variant weight` | `<poolKey> <weight>` | Set the active variant's positive weight in an owned pool |
+| `variant resize` | `<width> <height> <depth>` | Resize only the active owned variant within its workcell capacity; safe shrink rejects cropped content and the active cell reloads in place |
+| `variant label` | `<displayName>` | Set the active variant's author label; quote spaces |
+| `variant label-reset` | — | Reset the active variant to its resource-key fallback; alias `reset-label` |
+| `variant duplicate` | — | Copy the active variant's object, metadata, and exact pool memberships into one new variant in this workcell |
+| `variant duplicate-family` | `[themeKey=next]` | Atomically clone every enabled workcell's active owned variant into one coherent Iris family and load the whole family; alias `family` |
+| `rules limits` | `<maxDepth> <maxSizeChunks>` | Set depth `1..30` and radius `1..32`; `VANILLA_PORTABLE` is restricted to `<=20` and `<=8` |
+| `rules fallback` | `<poolKey> <fallbackPoolKey\|none>` | Set or clear one owned pool's direct fallback after compiling the complete graph |
+| `preview goto` | — | Teleport above the permanent seed-`1337` block preview; alias `teleport` |
+| `preview assemble` | `[seed=1337]` | Compute a deterministic read-only assembly at the player, report its complete piece count, and show in-range bounds as purple particle boxes for 10 seconds within the shared particle budget; places no blocks |
+| `export` | `[namespace=iris] [output=jigsaw-export] [format=zip] [replace=false]` | Start a background strict Minecraft 26.2 vanilla datapack export as one direct artifact under the Studio packs `exports/` folder |
+| `delete` | `[confirm=false]` | With `confirm=true`, scan reverse references, close Studio, and hash-pinned-delete the complete owned project; alias `remove` |
+
+There are no Jigsaw Studio undo, adoption rollback, or mod-loader authoring commands. Planar Studio always has six independently capacitated/enabled canonical workcells, spatial Studio one, and every variant retains its own exact dimensions and optional display label. Workcell and variant rename tools are renamed in an anvil, right-clicked to apply, and sneak-right-clicked to reset. A catalog may contain at most 512 variants. The seed-`1337` assembly is evaluated automatically and rendered as a permanent protected block preview; `preview assemble` is the separate temporary arbitrary-seed particle diagnostic. See `21 - Jigsaw Structures.md` for GUI/toolbox controls, themes/chance/rules/caps, markers, ownership, placement, export, and recovery.
+
+Bukkit has one global Studio project/world and the Jigsaw session belongs to one owning player. Only that owner can control, load, or mutate it; entering a workcell makes that physical cell the owner's next menu selection. Non-owner edits are cancelled and non-owner commands use a strict informational/communication allowlist. Block and inventory changes in loaded owned workcells autosave after a 40-tick quiet period. Duplicate-one and duplicate-family actions queue once behind pending autosave, expedite it, and continue automatically against the same request and source variants. The chest and live preview are protected; schema-1 or otherwise stale toolbox sticks are rejected. A later mutation after capture starts remains dirty for another capture. Plugins that bypass covered events must call `JigsawStudioService.markDirty(...)` or `markAllDirty(...)`.
+
+---
+
 ## Pack: `/iris pack` (`pk`)
 
 | Command | Aliases | Params | Description |
@@ -282,6 +349,7 @@ Modded developer group currently implements only `sentry` and `network`/`ip`.
 | Object expand | — | `/iris object expand` |
 | Object WE / studio / convert | yes | help stubs only |
 | Studio loot/profile/spawn/objects/scoreboard/importvanilla | yes | stubs or messages |
+| Jigsaw Studio create/edit/autosave/export commands and GUI | yes | no; copy a Bukkit-authored Iris pack |
 | Structure import/capture | yes | messages (run on Bukkit, copy pack) |
 | Datapack Modrinth ingest/remove | yes | messages |
 | Datapack status/install (dimension types) | — | yes |
@@ -298,6 +366,7 @@ Modded developer group currently implements only `sentry` and `network`/`ip`.
 - `06 - Worlds & Lifecycle.md`
 - `07 - Pregeneration.md`
 - `10 - Studio & VSCode Schemas.md`
+- `21 - Jigsaw Structures.md`
 - `25 - Pack Management.md`
 - `28 - Integrations.md`
 - `30 - Platform Differences.md`