@hraness/slopcamera 3.2.8 → 3.3.2

package/skills/slopcamera/references/directed-scenes.md

@@ -2,7 +2,10 @@
 
 Use `slopcamera scene --help` to check that the installed CLI includes the directed-scene foundation. The initial renderer uses Three.js and supports explicit scene JSON, semantic edits, calibrated cameras, native media surfaces, contact sheets, and transparent video.
 
-Start with `slopcamera scene init scene.json --json`, then `slopcamera scene inspect scene.json --json`. Retain the original source. Use its stable entity IDs and exact `sceneSha256` in typed patches; save each edit with `--output` to a new file. Inspect `editableControls` before changing generated parts or imported materials. Do not replace named scene parts with opaque regenerated source merely to change one color or camera.
+Use [scene refinement](scene-building.md#refine-an-existing-scene) for a shot-by-shot craft pass, subtle
+behavior design, actual-rig contact checks, and final encoded-frame review.
+
+To author a scene from code — builder helpers, procedural generator modules, glTF admission, or geometric audit — read [scene building](scene-building.md) first. Start interactive work with `slopcamera scene init scene.json --json`, then `slopcamera scene inspect scene.json --json`. Retain the original source. Use its stable entity IDs and exact `sceneSha256` in typed patches; save each edit with `--output` to a new file. Inspect `editableControls` before changing generated parts or imported materials. Do not replace named scene parts with opaque regenerated source merely to change one color or camera.
 
 Use `slopcamera scene plan scene.json --request request.json --json` before rendering. A frame request is:
 
@@ -22,15 +25,58 @@ For a media project, finish ordinary timeline/audio edits before V2 migration. R
 
 Use `scene project restore` to select an earlier retained scene for explicit shots in a new project revision. Use `add-asset`/`replace-asset` and `set-mesh-geometry` for authored representation changes. Preserve the entity ID and explicitly readdress GLB node/clip indices after a payload replacement; inspect available controls again afterward.
 
+Generated raster assets enter the scene the same way: declare the image as an `add-asset` payload with `provenance.source: "generated"`, then apply it explicitly — `set-material` with `material.map` on an authored procedural mesh for a texture, or `add-entity` a `kind: "environment"` entity (`role` plus bounded `intensity`) for a skybox. When alternatives matter, review them through [an image gallery](image-galleries.md) first and promote only the selected candidate; a frame renders at most one visible environment entity.
+
 Prepare a camera program with `slopcamera scene project prepare-render <project-id> --input prepare.json --output prepared-render.json --json`. The input declares the exact basis, calibrated output profile, straight-alpha full-frame scene policy, and delivery output/sync policy/tier. Then run `slopcamera workflows plan directed-scene --input prepared-render.json --json` and `slopcamera workflows run directed-scene --input prepared-render.json --json`. Use `slopcamera workflows show directed-scene --json` for the complete prepared-input schema.
 
 Use `--profile three-webgl2-hardware-v1` on scene rendering or project preparation to require the qualified macOS Metal backend. Missing or software GPU evidence rejects; no silent fallback occurs. A profile already in the request must agree with the CLI. Omit both fields for the historical software renderer. GPU identity and retained artifact hashes serve different purposes: cross-driver regeneration need not be pixel-identical.
 
-Import saved SPZ and an optional approximate collider with `scene world import --input import.json --source-root <directory> --output-root artifacts/slopcamera/generated/<name> --json`. Declare exact payload hashes, stable IDs, scale, source up axis and uniform transform. Historical World Labs provenance remains supported for offline replay and requires the matching world ID, approximate collider and retained provider receipt. Import needs no provider credential; paid world-generation commands were removed from current source (they remain in the historical Atet v3.2.3 release). Keep all returned assets and the splat entity, and save the consuming scene JSON inside that import output directory so its asset paths resolve relative to the scene file. Metadata dependencies preserve provenance through source-gone replay. Do not invent scale or relabel a collider as verified physics. Use `three-spark-webgl2-hardware-v1` for non-AA SPZ v2/v3, perspective cameras and at most 500,000 splats across the rendered world. This profile renders beauty only; splat depth/ID products and interleaved transparent world surfaces are unsupported. Materials and internal objects inside a splat are not ordinary editable mesh parts.
+Import saved SPZ and an optional approximate collider with `scene world import --input import.json --source-root <directory> --output-root artifacts/slopcamera/generated/<name> --json`. Declare exact payload hashes, stable IDs, scale, source up axis and uniform transform. An optional `providerMetadata` payload reference (for example a Marble `semantics_metadata` JSON export) surfaces recognized scale/ground/up-axis fields as an advisory `suggestedNormalization` in the output manifest; normalization still comes only from the explicit input fields. Historical World Labs provenance remains supported for offline replay and requires the matching world ID, approximate collider and retained provider receipt. Import needs no provider credential; paid world-generation commands were removed from current source (they remain in the historical Atet v3.2.3 release). Keep all returned assets and the splat entity, and save the consuming scene JSON inside that import output directory so its asset paths resolve relative to the scene file. Metadata dependencies preserve provenance through source-gone replay. Do not invent scale or relabel a collider as verified physics. Use `three-spark-webgl2-hardware-v1` for non-AA SPZ v2/v3, perspective cameras and at most 500,000 splats across the rendered world. This profile renders beauty only; splat depth/ID products and interleaved transparent world surfaces are unsupported. Materials and internal objects inside a splat are not ordinary editable mesh parts.
 
 Keep receipts and the original run ID after interruption. Inspect `slopcamera runs` and reconcile the exact attempt instead of blindly repeating a possibly published operation. Candidate records preserve derivation and staleness; candidate selection does not yet replace authored footage in the V2 scene compositor. Interactive scene editing and portable simulation remain deferred; native Blender jobs retain their own simulation caches. Use the separate [directing workflow](directing-video.md) to generate and review short clips before assembling an ordinary media project.
 
 
+## Direct cinematic worlds
+
+A `slopcamera.spatial-direction` document describes beats, actions, camera coverage, and look intents semantically; its `projectDigest` must equal the scene's `sceneSha256` from `scene inspect`. Check it with `slopcamera scene direction check direction.json --scene scene.json --json`, compile proposals with `scene direction plan ... --camera <camera-id> --output plan.json`, and plan bounded variants with `scene direction gallery ... --axis performance|camera|lighting|materials|effects|sequence`. Compiled direction stays `verified: false` — it is review evidence, not applied state.
+
+Bind declared effects through `scene effects plan` and `scene effects check` against the same scene, and bake planned simulation through `scene effects bake` when the plan calls for it. `scene temporal-audit` and `scene render-audit` report sampled evidence over explicit `--times-us` without inventing quality claims.
+
+## Author character behaviors
+
+A `slopcamera.spatial-behavior` document describes deterministic character behavior programs as ALGAL organism graphs — inert manifests of typed cells (`input`/`const`/`fn`/`repeat`/`each`/`organism` only for bake-safe behaviors), declared channels, scene binding, and explicit initial state. The organism closure is a content-addressed map of manifest digests to manifests; the `entry` field selects the top-level organism.
+
+Check a behavior against a scene with `slopcamera scene behavior check behavior.json --scene scene.json --json`. The checker validates the organism closure (digest consistency, fn references against the admitted catalog, wiring, carry bindings, interface completeness, entity and range against the scene). Bake it with `slopcamera scene behavior bake behavior.json --scene scene.json --output bake.json --json`; the bake runs through the real ALGAL runtime and produces a deterministic emitted trace with a bound receipt. Plan seeded gallery variants with `slopcamera scene behavior gallery behavior.json --scene scene.json --json`. Audit a baked trace with `slopcamera scene behavior audit bake.json --json`; the audit reports state thrash, exact periodicity, dead channels, and unreachable states as advisory findings.
+
+Four standard-library organisms are available for composition: locomotion FSM (`behavior.fsm.v1` — state machines with after/chance/flag/clear/always guards), expression layer (`behavior.expression.v1` — blink, gaze, mood), interaction sequence (`behavior.interact.v1` — phase sequencer with emit-on-entry), and a combined organism that merges all three via pairwise `emitted.append`. Each follows the `repeat`+`carry`+`window.advance` accumulation pattern. Use the stdlib organisms as templates; compose them into a behavior document with explicit initial states and scene-bound args.
+
+The authoring loop: (1) assemble a behavior doc from stdlib organisms with scene-bound args, (2) check it with `scene behavior check`, (3) bake it with `scene behavior bake`, (4) audit the trace with `scene behavior audit`, (5) plan gallery variants and review. Identical behavior doc + seed + scene produce byte-identical bakes. The `seed` interface input auto-binds from `behavior.seed` for gallery diversity. A channel map (`--channel-map`) binds emitted channels to clip runs, attach/release pairs, or trajectory waypoints for performance directives. Behaviors never execute source, contact providers, or access the filesystem; organisms are data.
+
+For SDK authoring, normalize the scene with `parseSpatialScene` and bind the
+behavior using `spatialSceneSha256`. These public helpers validate references and
+normalize entity order so saved SDK scenes and the CLI share the same identity.
+Check, bake, and gallery use that canonical identity. A behavior bound to a raw,
+noncanonical scene hash remains stale: explicitly rebind it to the inspected
+scene and bake again, preserving the earlier documents and receipts.
+
+The CLI check and bake still wait for host CPU and local-I/O admission. A concurrent
+render can reserve the CPU pool. A timeout with no output does not establish that
+the behavior program failed; preserve the attempt's outcome and distinguish
+resource waiting from a returned validation error before retrying.
+
+When compiling mapped directives with `compileSpatialPerformance`, use the
+exported `SPATIAL_PERFORMANCE_COMPILER_ID` for the plan's `compilerVersion`.
+Compiler `slopcamera.spatial-performance-compiler@v3` resolves prop ownership in
+time order. A later attach can take ownership after a release. At the same
+timestamp, releases precede attaches, so an immediate handoff keeps the new
+attachment; among simultaneous attaches, the last authored attach wins. When the
+latest attachment's interval ends, an older overlapping attachment does not
+resume. Retained `@v2` plans require an explicit version update and a new compile
+and audit. Preserve old takes and receipts as evidence rather than relabeling
+them with the new compiler identity.
+
+The `cinematic-world` built-in workflow composes exactly these operations for one admitted scene. Its input is an inert `slopcamera.spatial-recipe-pack` — one scene digest, one direction document, bounded gallery axes, up to 4 named preview render requests, optional declared effects, and optional temporal-audit inputs — wrapped with the scene document and its repository path. Plan it with `slopcamera workflows plan cinematic-world --input input.json --json`; run it with `workflows run`. The workflow never selects or promotes a candidate: registration uses `scene project add-candidate <project-id> --input <request.json>`, and selection uses `scene project select-candidate <project-id> --input <request.json>`, both after review. A recipe pack is data — it cannot register executors, source paths beyond the declared render source, permissions, secrets, or URLs.
+
 ## Direct short generated clips
 
 Use [short-video directing](directing-video.md) for retained paid takes and accepted-shot assembly. Use the matching Slopcamera source build for those commands.

package/skills/slopcamera/references/gateway-media.md

@@ -109,6 +109,12 @@ Never automatically retry an interrupted or failed paid generation. Slopcamera u
 zero client retries because an ambiguous request may still have been charged.
 Report the failure receipt and reconcile the exact attempt. A deliberate new paid command needs authority within the user’s budget; do not infer that an ambiguous failure was free.
 
+When the request leaves alternatives open — texture maps, skyboxes,
+backdrops, sprites, or competing design directions — prefer `slopcamera ai
+image gallery`, which runs one tracked job per candidate and composes a
+labelled contact sheet for one review pass. [Image galleries](image-galleries.md)
+covers the candidate grammar, receipt, and explicit promotion steps.
+
 ## Finish the task
 
 Report:
@@ -123,7 +129,9 @@ Report:
 
 Use [directing video](directing-video.md) for budgeted takes, accepted predecessor frames and local recovery. URL-only models can use its explicit private Blob path; do not paste short-lived signed URLs into CLI arguments or project files. Blob charges and authority are separate from Gateway.
 
-The small portable `slopcamera image generate '<prompt>' --output image.webp` command defaults to `recraft/recraft-v4.1-utility` and admits PNG/JPEG/WebP output. It is distinct from the local `ai` catalog workflow. Preserve literal prompts when requested, keep its output inside the intended workspace and never automatically retry a failed paid call.
+The small portable `slopcamera image generate '<prompt>' --output image.webp` command defaults to `recraft/recraft-v4.1-utility` and admits PNG/JPEG/WebP output. It is distinct from the local `ai` catalog workflow. Preserve literal prompts when requested, keep its output inside the intended workspace and never automatically retry a failed paid call. Its sibling `slopcamera image gallery '<subject>' --output-dir <directory>` shares that bounded model contract and composes several candidates into one review sheet; see [image galleries](image-galleries.md).
+
+For product identity SVGs, `slopcamera image icon '<subject>' --purpose <mark|illustration> --output icon.svg` is the canned pipeline. `mark` produces a compact favicon/app/header mark: one to three bold masses in one ink, gated for 16–32 px recognition and low path count. `illustration` (the compatibility default) produces the related marketing illustration: simple isometric structure in one ink, gated against hairlines, dense fills, and detail lost at 64 px. Both run one style-locked Gateway raster through ink normalization, local tracing, and deterministic geometry gates. `--rounds 2` (the default) adds a purpose-specific vision critique that revises the prompt between attempts; `--rounds 1` is a single paid generation with no critique call. `--ink` overrides the ink color and `--keep-raster` retains the normalized line-art PNG beside the SVG.
 
 ## Style recipes
 
@@ -132,3 +140,9 @@ vignette and typewriter notes on paper right), do not ask Gateway to redraw the
 whole poster. Follow [rubber-stamp-field-notes.md](rubber-stamp-field-notes.md):
 generate only the stamp with a reference-capable model, then assemble with the
 local compositor.
+
+For an editorial or social banner made from an opaque plate, transparent
+characters, motif clusters, local type, annotations, and diagram clippings,
+follow [social-collage-banners.md](social-collage-banners.md). Generate each
+semantic role independently, inspect its pixels, and compose the selected files
+with the packaged manifest-driven compositor.

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.3.1/hraness-slopcamera-3.3.1.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/music-video.md

@@ -5,6 +5,10 @@ including dancing characters, changing landscapes, and musical light accents.
 The export retains the source and creates an ordinary editable project with
 separate scene video and original music.
 
+For an existing composition, use [scene refinement](scene-building.md#refine-an-existing-scene) to review
+each shot, author subtle interactions, check contact, and inspect the encoded
+delivery. Keep the scene's deliberate style and original media intact.
+
 ## Confirm the input and local capability
 
 Use the user's selected track and supplied tempo. Establish an explicit duration,

package/skills/slopcamera/references/native-studio.md

@@ -20,6 +20,25 @@ A failed or interrupted job is never automatically rerun. `studio inspect` reche
 
 See the shipped `docs/studio.md` and checked `examples/studio/` for source conventions, color/alpha rules, native caveats and the local `.studio.run()` workflow operation. Source/runtime identities are observed provenance, not a complete hash of every plugin, font, library or ambient read.
 
+### Diagnose a Blender render crash
+
+`studio probe` discovers devices and checks runtime capabilities; it does not
+render a frame or prove that Cycles shader compilation succeeds. Qualify the
+selected engine and device with a bounded render before a long job.
+
+When Blender quits unexpectedly, inspect the exact studio attempt and its retained
+logs, then correlate the process and time with the operating system's crash
+report. On macOS, a `MetalKernelPipeline::compile` stack and a main thread waiting
+in `BlenderSession::render` identify failure during rendering. They do not establish
+an out-of-memory condition, a harmless shutdown, or a particular cache defect.
+A successful Chrome/Three.js render supplies no evidence about Blender's recovery.
+
+After custody is settled, test a revised engine or device in a new, explicitly
+configured job if needed. CPU or EEVEE success can narrow the failing path but
+does not fix or qualify Cycles/Metal. Keep the original failure and inspect the
+new frames before adopting that configuration. Do not clear shared caches, alter
+another task's render, or repeatedly launch the failing job as a generic recovery.
+
 ## Share a native output without re-executing it
 
 `studio asset <studio-id> --output-id <id> --asset-id <id> --representation native|encoded-video [--frame <index>] --json` rechecks one successful output and returns its spatial asset, binding and receipt. It never rerenders or silently transcodes. Preserve all three together. A frame selection uses the native job’s explicit frame index; an encoded-video selection requires a previously retained unambiguous encode. Unsupported GLB materials, skins or morphs fail before rendering. Keep the original native rig and export a deliberate compatible static derivative.

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

@@ -0,0 +1,14 @@
+# Build a revisable parametric design
+
+Use Slopcamera v3.3.1 or newer 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,172 @@
+# Build and refine authored scenes
+
+For an existing composition, go to [Refine an existing scene](#refine-an-existing-scene)
+for staging, interaction, contact, and final delivery review.
+
+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`.
+
+## Refine an existing scene
+
+Use this pass when an existing HTML, Three.js, or native scene needs better
+staging, character interaction, materials, and motion. Start with its retained
+source and a playable baseline. Finish with reviewed frames from the new encoded
+movie, the source that produced it, and specific remaining limitations.
+
+### Establish the version and shot list
+
+Check `slopcamera --version` and the relevant command help against the executable
+you will use. A source checkout, installed CLI, and installed skill can differ.
+Inspect the matching package or release before concluding that a feature is
+missing. Native ALGAL behavior authoring uses `scene behavior check|bake|audit`;
+read [directed scenes](directed-scenes.md#author-character-behaviors) for its
+contracts.
+
+Record each shot's time range, intended action, camera, principal objects, and
+visible defects. Preserve deliberate stylistic choices and identity constraints.
+Capture comparable baseline and revised frames at the same scene times. When
+adding a shot, update duration, cuts, captions, end fades, frame count, and review
+sample lists together.
+
+Assign independent scene or object groups to separate workers when useful. Keep
+one owner for shared rigs, camera conventions, render settings, generated source,
+and the final browser session. Join the changes before the aggregate review.
+
+### Repair what the camera reveals
+
+Review the whole shot before adding detail. Use this order to make each pass
+address the remaining visible problem:
+
+| Area | Review and repair |
+| --- | --- |
+| Staging | Make the principal action readable at delivery size. Check silhouettes, feet, faces, sight lines, and foreground occlusion throughout the camera move. Extend sets far enough to cover every intended view. |
+| Contact | Check soles against the floor, fingers against handles, carried objects against hands, and tools against their target surfaces. An object origin is rarely its contact point. |
+| Construction | Give prominent objects plausible thickness, supports, seams, and connections. Inspect stairs, railings, glazing, roofs, furniture, and machine housings for floating or intersecting parts. |
+| Materials | Distinguish metal, glass, painted surfaces, fabric, and foliage through their response to light. Keep roughness and small variations consistent with scale; uniform gloss and repeated bright windows can flatten a scene. |
+| Lighting | Establish a readable key light, restrained fill, and motivated practical lights. Check contact shadows, highlight clipping, bloom, depth-of-field focus, and dark detail in the encoded result. |
+| Motion | Give actions a cause, preparation, contact, follow-through, and rest. Review full motion when a pose depends on a preceding event. |
+
+Fix a contact or camera defect before covering it with bloom, grain, motion, or
+extra props. Concentrate detail where the camera can resolve it. Numerical
+geometry checks can catch penetration; they cannot establish that a face is
+visible, a gesture reads well, or a material looks convincing.
+
+### Make behavior serve an observable action
+
+Choose a few useful reactions: a commuter notices a sign, a listener looks toward
+the speaker, or two characters pass an object. Define the event sequence before
+varying timing. A handoff might use notice, pause, reach, contact, shared grip,
+release, and acknowledgment. Assign explicit prop ownership intervals and
+document which actor controls the shared phase.
+
+Use the native ALGAL interaction organism for phase sequencing, then bind its
+emitted channels to clips, attach/release events, or trajectory waypoints through
+a channel map. Retain the behavior document, scene binding, channel map, bake,
+and audit. Repeat the bake with identical inputs to check determinism. Change
+the seed deliberately when reviewing variants. Inspect advisory findings in the
+context of the channel's meaning; repeated event payloads can be intentional.
+
+The behavior trace establishes event timing. Its mapped performance still needs
+the right rig, clip sources, transforms, and contact solution. Measure gaze toward
+the actual target in the character's coordinate frame. Preserve a resting arm
+when only the other arm participates. Use small delays and bounded pose changes
+to separate reactions without giving every object continuous motion.
+
+Direct within the visible asset's limits. A mathematically exact gaze can turn a
+photographic face map into an unreadable profile. Review face visibility during
+the gesture and use a restrained glance or nod when that better communicates the
+intended acknowledgment.
+
+When adapting a procedural rig, document any proxy skeleton and the conversion
+between local and world transforms. Test the visible rig separately. An audit of
+a proxy does not establish the visible character's foot placement, grip, or
+whole-body physical validity.
+
+### Verify contact and time before the full render
+
+Evaluate each frame from its absolute timestamp. Reset transforms and state that
+can otherwise survive a seek. Keep behavior baking outside the frame callback;
+sample the retained result during playback. Test a timestamp, a later timestamp,
+and the original timestamp again, including ownership and pose endpoints.
+
+For each important contact, declare the measured surfaces or anchors and a
+tolerance in scene units. Sample the actual loaded rig through the interaction,
+including frames immediately before and after attach, release, impact, and
+planting events. Check finite transforms, grip error, floor clearance, ownership,
+and prop orientation. For moving crowds or vehicles, check geometry extents and
+intermediate times as well as center distances. Report sampling density and
+tolerances; sampled clearance is not continuous collision proof.
+
+Require finite measurements and actual samples for every required contact state.
+Missing contact data must fail validation rather than default to zero error.
+Ensure each reported contact and replay check contributes to the final pass/fail
+result.
+
+Render a short preview containing the entire difficult action. For an HTML scene,
+author a bounded preview request and map its local clock to the intended source
+time in the authored scene; preserve the full-scene request. For a directed scene,
+use the supported explicit render range. Do not assume a project-specific capture
+flag is a Slopcamera CLI option.
+
+Review every shot at its start, middle, and end, then inspect event boundaries,
+cuts, and changed camera coverage. A contact sheet reveals composition and
+continuity; a motion preview reveals timing, sliding, snapping, and occlusion.
+Use both when the change affects interaction. Record defects by shot, object,
+time, and visible consequence so another pass can reproduce them.
+
+### Verify the encoded movie
+
+Run the supported [HTML music-video](music-video.md), [directed-scene](directed-scenes.md),
+or [native studio](native-studio.md) render workflow from the converged source.
+Retain its source and runtime receipts. A completed frame loop does not establish
+successful encoding or browser cleanup; resolve any reported lifecycle failure
+before calling the render successful.
+
+Probe the delivery for dimensions, rational frame rate, decoded frame count,
+duration, color metadata, and expected audio streams. Derive expected frames from
+the selected workflow's timing rules. Decode review frames from this movie,
+including cuts, the final frame, and the contact phases. If an authored event
+falls between frame times, record the selected frame index and its actual time.
+Review color against the source frames; metadata alone does not prove the correct
+RGB-to-YUV conversion. Distinguish intentional fades from missing or black frames.
+
+Keep the previous delivery and hash both files when verifying replacement. A
+different hash proves different bytes, so also compare the intended visible
+changes. Deliver the new movie with a compact scene review, retained evidence,
+and the limitations that remain visible. Avoid a quality or physics claim that
+the review did not establish.
+
+For a custom capture optimization, compare decoded pixels against the supported
+capture path at representative lit frames, including transparent edges and
+post-processing. An opening black frame is insufficient evidence. Keep the
+ordinary capture path when equality is required and the comparison differs.
+Never bypass browser signature checks, disable its sandbox, or signal unrelated
+processes to make a render finish.