@hraness/slopcamera 3.2.8 → 3.3.1

package/skills/slopcamera/references/image-galleries.md

@@ -0,0 +1,166 @@
+# Generate and review candidate galleries
+
+Use an image gallery when a request leaves visual alternatives open: texture
+maps, skyboxes and environment plates, backdrops, sprites, or competing design
+directions. One command produces several bounded candidates in parallel,
+composes a labelled contact sheet, and keeps every candidate independently
+addressable with its exact prompt, digest, and provenance. Review the sheet
+once, then promote the chosen candidate through an explicit authored step.
+Generation never edits authored source or an existing project implicitly.
+
+## Pick the gallery lane
+
+Two commands share one planner and compositor:
+
+```sh
+# Portable: bounded file output, default utility model, still paid per candidate.
+slopcamera image gallery 'weathered copper panel' \
+  --kind texture --output-dir review/copper --json
+
+# Durable: one tracked Gateway job per candidate, catalog model required.
+slopcamera ai image gallery 'weathered copper panel' \
+  --model <image-model-id> --kind texture --output-dir review/copper --json
+```
+
+The portable lane writes candidate files, `gallery.png`, and `receipt.json`
+into `--output-dir`. The durable lane additionally publishes each candidate
+through the generated-artifact store beneath `artifacts/slopcamera/generated/`
+with a retained job record per attempt, so interrupted or ambiguous paid work
+stays reconcilable. Prefer the durable lane when provenance must survive the
+invocation; both lanes are paid calls per candidate with zero client retries.
+
+## Choose the kind
+
+`--kind` selects the prompt contract and default aspect:
+
+| Kind | Contract | Aspect |
+| --- | --- | --- |
+| `image` | Plain subject, clean composition | 1:1 |
+| `texture` | Seamless tileable flat-lit surface | 1:1 |
+| `skybox` | Equirectangular 360 panorama, centered horizon | 2:1 |
+| `backdrop` | Scenic plate for compositing | 16:9 |
+| `sprite` | One isolated subject on neutral background | 1:1 |
+
+## Control the candidate set
+
+- `--count <n>` renders the same kind contract `n` times (up to 16).
+- `--vary 'axis[=v1,v2][;axis2...]'` takes the cartesian product of
+  `style`, `palette`, `material`, `lighting`, `mood`, and `detail` values.
+  Omit `=values` to use the kind-aware defaults, for example
+  `--vary 'style;lighting=golden hour,night'`.
+- `--candidates <file.json>` supplies an explicit bounded list of
+  `{id, prompt|variant}` entries. `prompt` replaces the kind template
+  verbatim; `variant` appends one direction inside it.
+- `--cell <n>` sets the square cell edge in pixels (64–1024, default 512).
+
+`--candidates` is mutually exclusive with `--vary` and `--count`.
+
+## See seams and applied renders, not flat pixels
+
+`--kind texture` composites each cell as a 2×2 tiled repeat so tiling seams
+are visible in the sheet itself; `--no-tile` keeps a flat cell, and `--tile`
+opts other kinds in. `--tile` and `--no-tile` are mutually exclusive, and
+receipt rows carry `tiled: true`.
+
+On the durable lane, `--preview probe` renders each settled candidate inside a
+fixed checked-in probe scene — a texture becomes the material map on lit
+geometry plus four adjacent wall tiles that expose seams, a skybox becomes the
+scene environment lighting a reflective sphere, a backdrop becomes a surface
+behind a lit subject — and the cell shows the rendered still:
+
+```sh
+slopcamera ai image gallery 'weathered copper panel' \
+  --model <image-model-id> --kind texture --preview probe \
+  --output-dir review/copper --json
+```
+
+`--preview probe` is valid only for `texture`, `skybox`, and `backdrop`. The
+receipt row keeps the generated candidate `path`/`sha256` and the rendered
+`cellImage` `path`/`sha256` as separate fields — promotion always targets the
+candidate, never the still. A failed render leaves the flat candidate in the
+sheet with a warning.
+
+## Review whole-scene variants
+
+`slopcamera ai scene gallery` renders a base scene's bounded typed variants —
+environment swaps, material changes, palette or transform axes expressed as
+`slopcamera.spatial-scene-patch` operations — into the same kind of labelled
+contact sheet, with no paid calls:
+
+```sh
+slopcamera ai scene gallery scene.json \
+  --variants gallery.variants.json --output-dir review/world --json
+```
+
+```json
+{ "kind": "slopcamera.scene-variants", "schemaVersion": 1,
+  "variants": [
+    { "id": "dusk", "label": "Dusk",
+      "patch": { "kind": "slopcamera.spatial-scene-patch", "schemaVersion": 1,
+        "operations": [{ "kind": "set-color", "entityId": "entity_sky_dome", "color": "#2a1e4f" }] } }
+  ] }
+```
+
+Each variant's `expectedSceneSha256` is optional and defaults to the base
+digest; a mismatched value fails before any render. Every derived scene is
+published at `variants/<id>/scene.json` under the output directory with its
+asset payloads staged alongside — inherited payload paths resolve beside the
+authored scene, variant-authored `add-asset`/`replace-asset` payload paths
+resolve beside the variants file — so the derived scene re-renders
+standalone. The receipt keeps the base digest, per-variant patch and derived
+scene digests, the rendered still digest, and the render receipt path per row;
+a failed render stays in the sheet as a failed row. `--camera` selects a scene
+camera, `--time-us` picks the frame, `--cell` sizes cells.
+
+## Review the sheet
+
+Inspect `gallery.png` directly. Each cell carries a `#<index> <id>` label; a
+failed candidate stays in the sheet as a dark cell marked `failed` so the
+review covers the whole requested set. `receipt.json` rows map every index to
+its path, SHA-256, media type, request ID, cell geometry, and — on the durable
+lane — its job record path.
+
+## Promote a selected candidate explicitly
+
+A gallery never applies itself. After selecting a cell, use that candidate's
+own path and digest. For a scene material or environment, declare the image
+as an asset and apply it through one `scene patch` carrying the current
+`expectedSceneSha256`:
+
+```json
+{ "kind": "add-asset", "asset": {
+    "assetId": "asset_copper",
+    "payload": { "path": "<candidate path relative to the scene file>", "sha256": "<receipt sha256>", "bytes": <n> },
+    "interpretation": { "kind": "image", "width": <w>, "height": <h>, "colorSpace": "srgb", "alpha": "opaque", "mimeType": "image/png" },
+    "dependencies": [],
+    "provenance": { "source": "generated", "description": "Gallery candidate copper-weathered", "receiptSha256": "<receipt.json sha256>" } } },
+{ "kind": "set-material", "entityId": "entity_pedestal",
+  "material": { "kind": "standard", "color": "#ffffff", "opacity": 1, "roughness": 0.7, "metalness": 0.8, "map": "asset_copper" } }
+```
+
+`material.map` applies to authored procedural geometry only, and scene image
+assets admit PNG/JPEG/SVG payloads. For a selected skybox, `add-entity` a
+`kind: "environment"` entity referencing the image asset with
+`role: "background" | "environment" | "both"` and a bounded `intensity`; at
+most one visible environment entity may appear in a frame, so gate alternates
+through authored `visible` flags. Keep the scene file where its asset paths
+resolve, the same rule as world imports.
+
+Outside scenes, promote by pointing the consuming step at the exact retained
+path — a video `project add`, a design slot, or an `image vectorize` input —
+never by copying bytes into an authored path implicitly.
+
+For a scene-variant gallery, promotion is adopting the variant: apply the
+selected patch from the variants file through `scene patch` (the receipt row
+keeps its digest), or move the derived `variants/<id>/scene.json` — with its
+staged payloads — to its permanent home. The authored base scene is never
+edited by the gallery.
+
+## Preserve failures and outputs
+
+Gallery publication is no-replace: an existing `gallery.png` or
+`receipt.json` in the output directory fails the command before any paid
+dispatch. A failed candidate never retries inside the run; reconcile its
+retained job record or receipt row before deciding a new paid command is
+authorized. If every candidate fails, the labelled sheet and receipt are
+still retained and the command reports `GENERATION_FAILED`.

package/skills/slopcamera/references/install.md

@@ -14,7 +14,7 @@ command -v slopcamera
 
 A restricted shell can omit package-manager paths. Check known host installation paths before declaring a tool unavailable. If Bun is genuinely absent, follow its official [installation guide](https://bun.sh/docs/installation) within the user’s authorized setup scope. Do not switch package managers or pipe an unreviewed installer into a shell.
 
-Slopcamera installs from its verified release archive: `bun add --global https://github.com/hraness/slopcamera/releases/download/v3.2.6/hraness-slopcamera-3.2.6.tgz`, then `slopcamera doctor --json`. Building from source is the contributor path. Historical Atet archives do not install the renamed CLI; never substitute `slopcamera` into an old archive URL.
+Slopcamera installs from its verified release archive: `bun add --global https://github.com/hraness/slopcamera/releases/download/v3.2.8/hraness-slopcamera-3.2.8.tgz`, then `slopcamera doctor --json`. Building from source is the contributor path. Historical Atet archives do not install the renamed CLI; never substitute `slopcamera` into an old archive URL.
 
 Use an existing compatible source build when available. Otherwise follow the [complete source-install guide](https://github.com/hraness/slopcamera/blob/main/docs/how-to/use-current-source.md): clone into a new directory, record its exact commit, install locked dependencies without lifecycle scripts, build the SDK and source CLI, then define the shell command against that checkout. A clone or skill installation alone does not install the executable. Do not alter an existing active checkout to satisfy this path.
 

package/skills/slopcamera/references/parametric-design.md

@@ -0,0 +1,14 @@
+# Build a revisable parametric design
+
+Use current source and `slopcamera scene design` for dimensions, repeated architectural parts, furniture, pavilions and façades that must regenerate from retained rules. This is a local mesh-design workflow; Rhino, Grasshopper and native engine execution are separate tools.
+
+1. Discover original studies with `slopcamera scene design catalog --json`. Start with `scene design init <new-directory> --template crescent-pavilion|spiral-stair|ribbed-tower|modular-bookshelf`.
+2. Read the emitted `design.json` and inspect it with `scene design inspect`. Describe the user's intended shape in named parameters, derived scalar values, constraints and semantic geometry stages. Keep references to engineering knowledge separate from visual references. Do not infer structural validation from appearance.
+3. Save an explicit numeric values object and use `scene design set <design.json> --parameters <values.json> --output <new-design.json>` to preserve revisions. A dimensional change should update dependent members and details together.
+4. Compile with `scene design compile <design.json> --scene <base.scene.json> --output-dir <new-bundle> --json`. Pass the starter's staging scene for cameras and lights, or a previous compiled scene to preserve supported generated-part overrides. Retain design, scene, exact asset bytes and receipt together.
+5. Render `scene render <bundle/scene.json> --request <bundle/render.json> --json`. Review hero pixels, then use `camera_detail` and `camera_plan` to inspect repeated members, joints, silhouette and framing. Geometry compilation does not prove visual quality.
+6. For alternatives, use `scene design gallery` with a bounded `slopcamera.spatial-design-variants` document. It emits up to six complete models; render the candidates through the same camera before selecting one. It makes no paid calls and does not upload source.
+
+Place generated bundles below `artifacts/slopcamera/generated/`. Existing files conflict. An interrupted bundle without its final receipt is incomplete; inspect it and choose a fresh destination. The design compiler never executes source text. For native CAD operations or Blender/Cycles production shading, retain a native-studio source and use the explicit trusted-code workflow in [native studio](native-studio.md).
+
+Detailed contracts and checked commands: [design reference](https://github.com/hraness/slopcamera/blob/main/docs/parametric-design.md) and [design guide](https://github.com/hraness/slopcamera/blob/main/docs/how-to/parametric-design.md). The portable SDK exports the design compiler and starter catalog from `@hraness/slopcamera/code`; file publication and rendering belong to the CLI.

package/skills/slopcamera/references/scene-building.md

@@ -0,0 +1,32 @@
+# Build scenes from code
+
+Prefer helpers over hand-written scene JSON. The `@hraness/slopcamera/code` export ships pure builders in `spatial-scene/build` that return validated v1 scene data; feed their output into entities, transforms, and animation channels, then parse the whole scene before writing it. Helpers never read files, execute source, or touch a renderer, and every result already satisfies the contract schemas. Use [directed scenes](directed-scenes.md) for rendering, patching, and project commands.
+
+## Camera and animation helpers
+
+- `perspectiveFromFov({fovDeg, width, height, near, far})` → calibrated projection. `fovDeg` is the horizontal field of view.
+- `lookAtPose(position, target)` → camera pose facing local −Z at the target.
+- `frameFitPose(bounds, projection, margin)` → pose framing authored or admitted bounds.
+- `easeKeys({from, to, durationUs, easing})` → dense keys for `linear`, `ease-in`, `ease-out`, or `ease-in-out`; `easeChannel({channelId, targetId, property, ...})` wraps them into a ready animation channel. Baked keys stay small: about 25 per 4-second span.
+- `orbitKeys({center, radius, durationUs, ...})` → paired position and look-at rotation keys for a turntable.
+
+## Layout and placement helpers
+
+- `align(items, axis, edge)`, `distribute(items, axis, {gap}|{span})`, `row`, `column`, `stack` order existing entities by their transforms and optional bounds.
+- `grid({rows, columns, cellSize, origin?})` → ground-plane cell positions; `scatter({seed, count, region, minSpacing?})` → deterministic seeded XZ positions.
+- `groundSnap(transform, halfHeight, floorY)`, `onTopOf(moverBounds, moverTransform, targetBounds, targetTransform)`, `nextTo(...)`, `facing(transform, target)` resolve relations to concrete transforms immediately. They need bounds — primitives have them; GLB and splat bounds come from `scene asset admit` output or an explicit `--asset-bounds` map.
+
+## The create → audit → patch loop
+
+1. Build or generate the scene JSON.
+2. `slopcamera scene audit scene.json --camera camera_hero --json` samples evaluated geometry across the duration and reports per-entity frustum state, projected pixel footprint, and findings such as off-camera or never-visible entities. `--times-us` picks explicit samples; `--asset-bounds bounds.json` supplies decoded asset enclosures as a bounds map, an admission document, a `{manifest, facts}` pair, or an array of those.
+3. Fix with a typed `scene patch` carrying `expectedSceneSha256`, or regenerate. `slopcamera scene diff before.json after.json --json` shows the exact structural difference a patch produced.
+4. Re-audit, then verify pixels with `slopcamera scene render-audit scene.json --camera camera_hero --json` — it renders the real object-ID pass in the bound browser runtime at each sampled time and counts attributed pixels per entity, catching occlusion and never-rendered cases geometric audit cannot see. Splats and camera-bound view surfaces report honestly as unsupported or non-attributable rather than estimated. Neither audit tier inspects beauty output — materials, textures, text layout, and splat internals still need rendered-frame inspection.
+
+## Generate procedural scenes
+
+`slopcamera scene generate --module <file.ts> --generator-id <id> --output scene.json --json` runs a trusted TypeScript module at authoring time — the same trust class as an explicitly imported workflow module, with no sandbox. See `examples/scene-generators/grid-city.ts` for the shape: the module exports `generate(ctx)` returning `{entities, editableKeys?}`; entities carry a caller `key` and never `entityId` or `origin`, which the host stamps from the generator identity. Draw randomness only from `ctx.seed`; an identical run must reproduce identical output, and the retained record pins source, parameters, seed, and output digests. Use `ctx.lib.entityId(key)` to parent entities inside one output. `--parameters` accepts a bounded JSON object; `--into scene.json` regenerates one generator's output while preserving authored entities, other generators, and declared overrides. Transitive relative `.ts`/`.js`/`.json` imports inside the module's own directory are allowed and hashed into the retained closure digest; absolute or escaping specifiers, symlinks, `require()`, and dynamic `import()` are rejected. Asset references are rejected in this version.
+
+## Admit a local glTF asset
+
+`slopcamera scene asset admit model.glb --source-root <dir> --output manifest.json --json` validates a local GLB 2.0 against the closed profile, stores it content-addressed, derives model-space and scene-space bounds into a sibling facts manifest, and emits the mesh entity plus ready `add-asset`/`add-entity` patch operations. The source path must stay inside `--source-root`; unsupported GLB features reject rather than degrade. Apply the returned operations through `scene patch`, then feed the admission document itself to `scene audit --asset-bounds`.

package/skills/slopcamera/references/social-collage-banners.md

@@ -0,0 +1,204 @@
+# Compose a social collage banner
+
+Use this workflow for an editorial or social banner built from several generated visual roles, local labels, annotations, and optional diagram material. Generate the parts independently, inspect them, then assemble the selected files with the packaged local compositor. Do not ask one model call to render the final banner or important text.
+
+## Fix the delivery frame first
+
+Record the exact output geometry before prompting. For an X profile header, use `1500×500` unless the user or current platform tooling supplies another target. Keep important faces and title copy away from the lower-left profile-photo overlap and the outer crop margins.
+
+Split the brief into visual roles rather than requesting several complete banners:
+
+- one opaque background plate that establishes place, lighting, and atmosphere;
+- one or more isolated subjects on transparent backgrounds;
+- one motif cluster for secondary concepts;
+- optional editable diagrams for literal values and relationships;
+- local title, labels, circles, arrows, tape, grain, and vignette.
+
+A role prompt should describe only that asset. Tell an isolated-asset model that the output needs a fully transparent background and no words, letters, or logos. Tell a background model to omit people when a separate character layer will cover it. This reduces accidental text, duplicate subjects, and baked-in composition decisions.
+
+## Discover the model and controls
+
+Inspect the current image catalog and selected model instead of naming a remembered “latest” model:
+
+```sh
+slopcamera ai models list --type image --json
+slopcamera ai models show <image-model-id> --json
+```
+
+Check that the model reports image output, the intended size or aspect control, and provider options for transparent PNG output before relying on them. Keep provider options in a private physical file because the same surface may contain sensitive values:
+
+```sh
+cat > transparent-provider-options.json <<'JSON'
+{
+  "openai": {
+    "background": "transparent",
+    "outputFormat": "png",
+    "quality": "high"
+  }
+}
+JSON
+chmod 600 transparent-provider-options.json
+```
+
+That object is an example for a compatible OpenAI image model, not a portable option set. Use only namespaces and fields reported for the selected model. An opaque background plate normally needs a separate options file without `background: "transparent"`.
+
+## Generate independent roles in parallel
+
+Write one prompt file per role and retain it beside the collage manifest. Start independent text-only generations concurrently when the agent host supports parallel tool calls. Each command remains one durable paid job with its own output and receipt:
+
+```sh
+vercel env run -- bun "$SLOPCAMERA_SOURCE_ROOT/apps/desktop/dist/cli/main.js" ai image generate \
+  --model <image-model-id> \
+  --prompt-file prompts/background.txt \
+  --size 1536x1024 \
+  --provider-options opaque-provider-options.json \
+  --json
+
+vercel env run -- bun "$SLOPCAMERA_SOURCE_ROOT/apps/desktop/dist/cli/main.js" ai image generate \
+  --model <image-model-id> \
+  --prompt-file prompts/character-sticker.txt \
+  --size 1024x1024 \
+  --provider-options transparent-provider-options.json \
+  --json
+```
+
+Do not hide several semantic roles in `--count`; they need separate prompts and retained requests. Use an [image gallery](image-galleries.md) when a role needs competing visual alternatives. Text-only generation does not authorize uploading local media. If a role needs a local reference, name that exact file and add `--allow-cloud-upload` only when the task already authorizes its upload.
+
+Inspect every candidate before composition. Check background alpha for isolated layers, accidental writing, duplicated limbs or objects, clipped silhouettes, and whether the visual metaphor still reads at banner size. A successful receipt does not establish those facts.
+
+## Render literal facts as an editable diagram
+
+Use a Slopcamera diagram when the banner needs a pipeline, architecture, values, or named relationships. Keep its `.diagram.json` source and render the PNG locally:
+
+```sh
+slopcamera diagram check work/token-flow.diagram.json --strict
+slopcamera diagram render work/token-flow.diagram.json
+```
+
+Place that PNG as a `paper` image layer. The diagram remains editable and factual while the surrounding composition can stay loose and expressive.
+
+## Author the collage manifest
+
+The packaged compositor accepts local PNG, JPEG, and WebP inputs. Paths are relative to the manifest unless absolute. Every `x` and `y` identifies the layer center. Array order is back-to-front.
+
+```json
+{
+  "schemaVersion": 1,
+  "canvas": {
+    "width": 1500,
+    "height": 500,
+    "color": "#100a1c",
+    "background": {
+      "path": "../generated/background.png",
+      "position": "centre"
+    }
+  },
+  "layers": [
+    {
+      "kind": "image",
+      "path": "../generated/character.png",
+      "x": 255,
+      "y": 258,
+      "width": 330,
+      "rotation": -4,
+      "treatment": {
+        "kind": "sticker",
+        "border": 12,
+        "borderColor": "#ffffff",
+        "shadow": { "dx": 10, "dy": 14, "blur": 14, "opacity": 0.5 }
+      }
+    },
+    {
+      "kind": "image",
+      "path": "token-flow.light.png",
+      "x": 760,
+      "y": 430,
+      "width": 850,
+      "rotation": -1.5,
+      "treatment": {
+        "kind": "paper",
+        "padding": 26,
+        "color": "#faf5e8"
+      }
+    },
+    {
+      "kind": "tape",
+      "x": 430,
+      "y": 325,
+      "width": 120,
+      "height": 38,
+      "rotation": -38,
+      "color": "#f8ebaa",
+      "opacity": 0.82
+    },
+    {
+      "kind": "text",
+      "text": "275B TOKENS",
+      "x": 760,
+      "y": 64,
+      "fontSize": 58,
+      "fontFamily": "sans",
+      "fontWeight": 900,
+      "fill": "#ffe05a",
+      "stroke": "#3c1450",
+      "strokeWidth": 4,
+      "rotation": 1
+    },
+    {
+      "kind": "ellipse",
+      "x": 1210,
+      "y": 250,
+      "width": 350,
+      "height": 330,
+      "rotation": -5,
+      "color": "#ff5048",
+      "strokeWidth": 8
+    },
+    {
+      "kind": "arrow",
+      "from": { "x": 1080, "y": 130 },
+      "to": { "x": 1150, "y": 180 },
+      "bend": 0.25,
+      "color": "#ff5048",
+      "width": 8
+    }
+  ],
+  "effects": {
+    "grain": 0.18,
+    "grainSeed": 7,
+    "vignette": 0.35,
+    "chromaticShift": 2
+  }
+}
+```
+
+Image treatments are `plain`, `sticker`, and `paper`. Text supports `sans`, `serif`, and `mono`, newline-separated rows, fill, stroke, weight, alignment, and rotation. Annotation layers are `arrow`, `ellipse`, and `tape`. The compositor bounds canvas size, input bytes, decoded pixels, layer count, text, geometry, and effects; it rejects remote URLs and never replaces an existing output.
+
+Render through the version-matched packaged skill:
+
+```sh
+skill_root="$(slopcamera skill path)"
+bun "$skill_root/scripts/compose-social-collage-banner.ts" \
+  --manifest /absolute/banner.manifest.json \
+  --output /absolute/banner-v1.png
+```
+
+The command writes the PNG and a same-stem `.receipt.json` containing the manifest digest, exact input paths and digests, output digest, canvas, and layer count. Save a new manifest or output name for each material revision.
+
+## Inspect the delivered pixels
+
+Open the final PNG and inspect it at full size. Also inspect crops around the title, faces, high-contrast annotations, paper edges, and each platform exclusion zone. Confirm:
+
+- the file has the exact requested dimensions;
+- text is local, legible, and free of missing-glyph boxes;
+- transparent assets have no opaque square or dark fringe;
+- paper clippings and tape stay behind labels that must remain readable;
+- chromatic shift and grain do not damage small text;
+- factual diagram labels remain accurate;
+- the composition still reads when scaled down.
+
+Keep the prompt files, provider-option digests, generated receipts, diagram source, collage manifest, compositor receipt, and rejected attempts that explain a selection or recovery.
+
+## Recover paid failures deliberately
+
+Run each paid command with zero client retries. If a generation fails or is interrupted, inspect its retained job path and reconciliation state before doing anything else. Do not automatically resubmit an ambiguous attempt. A deliberate replacement call is appropriate only after reconciliation and within the task's existing spending authority. The local compositor is deterministic and unpaid, so layout revisions should happen there rather than through more model calls.

package/skills/slopcamera/references/workflows-sdk.md

@@ -1,6 +1,6 @@
 # Use SDKs and durable workflows
 
-Use `slopcamera workflows list --json` and `slopcamera workflows show <id> --json` to discover checked recipes and their actual inputs. Built-ins include `talking-head-cleanup`, `polished-screen-demo`, `chaptered-demo`, `social-variants`, `creative-iteration`, `creative-selection` and `directed-scene`. Keep ordinary project edits complete before a V2 scene migration.
+Use `slopcamera workflows list --json` and `slopcamera workflows show <id> --json` to discover checked recipes and their actual inputs. Built-ins include `talking-head-cleanup`, `polished-screen-demo`, `chaptered-demo`, `social-variants`, `creative-iteration`, `creative-selection`, `directed-scene` and `cinematic-world`. Keep ordinary project edits complete before a V2 scene migration.
 
 ```sh
 slopcamera workflows plan <id> --input input.json --json
@@ -32,9 +32,9 @@ Keep run IDs, errors and receipts after failure. A missing journal does not prov
 
 ## Use the portable MCP surface narrowly
 
-When connected, use `check_diagram` and `render_diagram` for compatibility calls, or `search_slopcamera` and `execute_slopcamera` with one exact returned operation and typed JSON. No tool rewrites source.
+When connected, use `check_diagram` and `render_diagram` for compatibility calls, `check_scene`/`inspect_scene`/`audit_scene`/`audit_scene_temporal`/`diff_scenes`/`evaluate_scene` for read-only spatial scene work, `check_scene_direction`/`plan_scene_direction`/`plan_scene_gallery`/`check_scene_effects`/`plan_scene_effects` for cinematic planning evidence, or `search_slopcamera` and `execute_slopcamera` with one exact returned operation and typed JSON. No tool rewrites source or mutates project state; candidate selection stays an explicit CLI or SDK call.
 
-- Use root-relative paths. A diagram must end in `.diagram.json`.
+- Use root-relative paths. A diagram must end in `.diagram.json`; a scene must end in `.json`.
 - Diagram render replaces the five documented exports, never its source.
 - MCP bounds diagrams to 64 shapes and 128 edges and reports at most 40 findings. Use the CLI for larger checked sources.
 - MCP uses built-in themes/icons and never executes workspace configuration; trusted custom config belongs to the CLI.