@hraness/slopcamera 3.2.7 → 3.3.1

package/skills/slopcamera/references/diagrams.md

@@ -124,21 +124,12 @@ assets for ordinary proportional text while retaining host discovery for
 explicit mono and custom font roles.
 
 
-## Use tldraw deliberately
+## Use browser canvas tooling deliberately
 
-The generated `.tldr` file is editable interchange and does not require the
-tldraw SDK or desktop app to create. Open it in tldraw Offline when a person
-wants direct canvas editing:
-
-```sh
-slopcamera canvas open diagrams/<slug>.tldr
-```
-
-If the optional app is absent, `slopcamera canvas install` resolves the current
-official release, verifies its published SHA-256 digest, and launches the
-platform installer. The app imports `.tldr` as an unsaved document; save it
-there to create its newer native `.tldraw` bundle. Never rewrite a native
-`.tldraw` ZIP/SQLite bundle directly.
+The generated `.tldr` file is editable interchange and does not require a
+separate application to create. Open it in a browser-based canvas editor when a
+person wants direct canvas editing. Slopcamera does not install or launch a
+diagram editor or application bundle, and `.tldraw` application bundles are outside its contract.
 
 ## Verify
 

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

@@ -2,7 +2,7 @@
 
 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.
+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 +22,35 @@ 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.
+
+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.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.
 
@@ -51,7 +51,7 @@ slopcamera skill path
 ## Add only required optional tools
 
 Treat `slopcamera doctor --json` as the readiness report. Install FFmpeg, a supported
-browser, native capture support, VTracer, tldraw Offline, or another optional
+browser, native capture support, VTracer, or another optional
 dependency only when the requested workflow needs it and the user has
 authorized that machine change. Slopcamera obtains its checksum-pinned VTracer on
 first vectorization use; do not replace that path with an unverified binary.

package/skills/slopcamera/references/music-video.md

@@ -95,10 +95,27 @@ Maintain multisample antialiasing on the scene render target if adding
 post-processing. Bound draw calls, geometry, and shader work, and validate frame
 zero before a full render.
 
+Set `audio.reactivity` to `{ "profile": "bands-v1" }` when local lights or
+materials should follow separate bass, midrange, treble, and overall-energy
+envelopes. Slopcamera derives these bands offline from the verified soundtrack
+(35–180 Hz, 180–2,000 Hz, 2,000–12,000 Hz), smooths them, and retains a
+hash-bound 60 Hz JSON resource named `audio-reactivity`. Load that resource once
+with `SlopcameraOverlay.asset("audio-reactivity")`, pass its JSON to
+`SlopcameraOverlay.prepareAudioReactivity`, and sample by integer microseconds
+inside `onFrame`. The profile is limited to ten minutes and returns zero outside
+its analyzed range. It is an envelope for animation, not a flash-safety
+certificate.
+
 Smooth effects are not a seizure-safety certificate. The timing and pulse helpers
 do not analyze rendered flashes or certify safety. Review the actual result and
 avoid claiming a safety guarantee.
 
+For emissive trails and communication ribbons, discard inactive fragments before
+computing color, clamp nonnegative bases before fractional `pow`, and handle
+degenerate segment vectors. Review native lossless frames when a glow appears as
+a block or stripe. Small diagnostics should use area averaging; ordinary video
+resampling can turn legitimate dark shadows into black samples.
+
 ## Validate, render, and review
 
 ```sh
@@ -116,9 +133,12 @@ Use returned `output.path`, `receipt.path`, `source.path`, `projectId`, and
 `projectPath`. Artifact paths are relative to the workspace root. The retained
 job includes original HTML, declared resources, original music when supplied,
 source and render receipts, lossless RGB `scene.mp4`, and delivery `video.mp4`.
-The delivery is H.264 with optional 48 kHz stereo AAC at 320 kb/s. Its ordinary
-project keeps the scene video and original music separate. Input files remain
-unchanged.
+The delivery is H.264 with optional 48 kHz stereo AAC at 320 kb/s. Both generated
+media files use the 512 MiB local media bound. The scene intermediate is checked
+for its complete declared frame count before retention; when the bound truncates
+it, the command reports an actionable bounded-render error and suggests lowering
+the canvas, frame rate, or duration. Its ordinary project keeps the scene video
+and original music separate. Input files remain unchanged.
 
 The returned `source.path` identifies a reusable `source.json` request with the
 original canvas, frame rate, timing, seed, parameters, and other render settings.

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/reference-led-3d.md

@@ -1,7 +1,7 @@
 # Reference-led Three.js and metallic treatments
 
 Use this guide only when Slopcamera's complete local Code Mode host is available.
-It ships in this repository alongside the thin desktop capture shell. The
+It ships in this repository alongside the local CLI host and optional unbundled menu-bar companion. The
 portable `@hraness/slopcamera/code` and `@hraness/slopcamera/workflow`
 entrypoints intentionally expose no HTML renderer, Three.js operation, or
 arbitrary source execution. Those capabilities belong to the local host.

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.