@hraness/slopcamera 3.2.4

package/skills/slopcamera/references/customization.md

@@ -0,0 +1,77 @@
+# Fonts and icon adapters
+
+`slopcamera` deliberately ships no commercial font and no large icon set.
+
+## Custom font
+
+Create `slopcamera.config.ts` beside the source:
+
+```ts
+import type { DiagramConfig } from "@hraness/slopcamera"
+
+export default {
+  font: {
+    family: "Your Font",
+    monoFamily: "Your Mono, ui-monospace, monospace",
+    files: [
+      {
+        path: "./fonts/YourFont-Regular.ttf",
+        weight: 400,
+        embed: false,
+      },
+      {
+        path: "./fonts/YourFont-Semibold.ttf",
+        weight: 600,
+        embed: false,
+      },
+    ],
+  },
+} satisfies DiagramConfig
+```
+
+The PNG renderer reads those local files. With `embed: false`, SVG output names
+the family but does not copy font bytes; serve the font through the website or
+fall back through CSS. Set `embed: true` only when the font license permits
+redistribution and self-contained SVG is worth the added file size.
+
+`monoFamily` names a system or site-provided CSS fallback stack for source
+fields that use `"fontFamily": "mono"`. Font files in this config belong to
+the primary `family`; Slopcamera does not embed separate mono-family files. The
+editable `.tldr` export maps the two source roles to tldraw's `sans` and `mono`
+families while the SVG and PNG adapter owns the configured typography.
+
+Do not commit a commercial font merely because it exists on the local machine.
+
+## Custom icon
+
+An icon definition has a view box and SVG body:
+
+```ts
+import type { DiagramConfig } from "@hraness/slopcamera"
+
+export default {
+  icons: {
+    inbox: {
+      viewBox: "0 0 24 24",
+      body:
+        '<path d="M4 5h16v14H4zM4 14h4l2 2h4l2-2h4" ' +
+        'fill="none" stroke="currentColor" stroke-width="1.5" ' +
+        'stroke-linecap="round" stroke-linejoin="round"/>',
+    },
+  },
+} satisfies DiagramConfig
+```
+
+Reference it with `"icon": "inbox"` on a rectangle or ellipse. The renderer
+uses `currentColor`, so one definition works in both themes. The `.tldr`
+adapter embeds the icon as an SVG image asset; the card, icon, and label remain
+separate movable tldraw shapes.
+
+To use a third-party icon package, write a small local adapter that converts the
+package's data into `{ viewBox, body }`. Keep that package in the consuming
+repository rather than adding it to `slopcamera`. Preserve the icon package's
+license and attribution requirements.
+
+Icon bodies may contain ordinary SVG geometry such as `path`, `circle`, `rect`,
+`line`, `polyline`, and `polygon`. Scripts, event handlers, `foreignObject`, and
+embedded web content are rejected.

package/skills/slopcamera/references/diagrams.md

@@ -0,0 +1,153 @@
+# Create and revise diagrams
+
+Use the installed `slopcamera` CLI as the deterministic adapter. Keep the authored
+`.diagram.json` source; treat `.light.svg`, `.dark.svg`, `.light.png`,
+`.dark.png`, and `.tldr` as replaceable exports.
+
+## Follow the prompt literally
+
+Treat the user's prompt as the complete content specification.
+
+- Preserve supplied labels, values, relationships, relative sizes, and
+  omissions.
+- Add only neutral mechanics needed to draw those facts.
+- Do not invent a title, subtitle, legend, annotation, example, implication,
+  category, metric, tick, connector, or decorative claim.
+- Do not expand a short label into a sentence. Prefer the user's own one-to-three
+  word label.
+- When updating, remove rejected content without replacing it with a new
+  elaboration.
+
+## Find the source
+
+1. Read local repository instructions and look for `slopcamera.config.*`.
+2. Search for an existing same-subject `.diagram.json` before creating one.
+3. Update that source rather than editing generated images or creating a
+   duplicate.
+4. Follow local vault instructions and existing diagram/note directories. Use
+   `info/diagrams/<slug>.diagram.json` with `info/notes/<slug>.md` only when
+   that is the established convention. A vault named `kb/` does not imply a
+   nested `info/` directory. Do not invent a vault or migration layout.
+5. Link the diagram through its companion note when local instructions require
+   one, following the host's image-embedding convention.
+6. Outside a vault, default to `diagrams/<slug>.diagram.json`.
+
+## Compose the visual
+
+Read [visual-communication.md](visual-communication.md) before
+creating or materially redesigning a diagram.
+
+Apply these defaults deeply:
+
+- Use rounded rectangles for ordinary concepts. Equal roles get equal sizes,
+  radii, stroke weights, icon sizes, and label treatment.
+- Leave at least 96px—and preferably 120–200px—between connected shapes so
+  arrows read as relationships rather than seams.
+- Put icons directly inside their semantic shape. Do not place a bordered icon
+  tile inside another bordered card.
+- Use three to seven primary elements when the prompt permits abstraction.
+- Establish a clear reading order and align peers to a shared grid.
+- Use whitespace before borders, colors, or prose to separate groups.
+- Use one color distinction by default. A supplied system with several stable
+  roles may use a small repeated semantic palette, but every role must remain
+  legible through its label, icon, or position without hue.
+- Keep icons supportive: a label must still carry the meaning.
+- Prefer one visible boundary per object and one visible stroke per axis or
+  connector.
+- Box content is vertically centered as one measured icon-and-text group. Do
+  not compensate with source-coordinate nudges.
+- Set `labelFontSize`, `labelFontFamily`, or `labelWeight` when one box label
+  needs a different treatment. Use `"fontFamily": "mono"` for a supplied
+  identifier, type, or relation, not as decoration.
+- Use `labelRows` for two to four supplied text roles inside one box. Each row
+  can set `text`, `fontSize`, `fontFamily`, and `weight`; `labelRowGap` controls
+  the measured gap. Do not combine `labelRows` with the legacy `label` fields.
+- Edge labels support the same font family, size, and weight controls plus
+  `labelPosition` and `labelOffset`. Keep relation labels short.
+- In positioned diagrams, distribute fan-in or fan-out connectors with
+  `startPosition` and `endPosition` from `0` to `1`. On left and right sides,
+  zero is the top and one is the bottom. On top and bottom sides, zero is the
+  left and one is the right.
+
+Do not “improve” literal data to satisfy these preferences. The prompt wins.
+
+## Let deterministic layout own ordinary coordinates
+
+Use a coordinate-free `stack` layout for one horizontal or vertical sequence:
+
+```json
+{
+  "layout": {
+    "type": "stack",
+    "direction": "horizontal",
+    "gap": 160,
+    "align": "center"
+  }
+}
+```
+
+- Array order controls placement only. Draw an edge only when the prompt
+  supplied that relationship.
+- Keep stack shapes to rectangles or ellipses and omit `x` and `y`.
+- Use the default 160px gap unless the prompt or publication frame requires a
+  different runway.
+- Switch to positioned mode for branching, non-adjacent edges, charts, free
+  text, lines, or deliberately unequal placement. Do not force those meanings
+  into a one-dimensional stack.
+- If a stack does not fit, increase the canvas or reduce authored dimensions
+  explicitly. Do not silently shrink shapes or gaps.
+
+## Author and render
+
+Use the public schema URL or run `slopcamera diagram init` for a starter:
+
+```sh
+slopcamera diagram check diagrams/<slug>.diagram.json --strict
+slopcamera diagram render diagrams/<slug>.diagram.json
+```
+
+The render command replaces five exports whose common stem is the document’s `name`, not necessarily the input filename. `diagram init first.diagram.json` starts with `name: "example-flow"`, so its exports are `example-flow.*`. Inspect both
+light and dark output when layout or contrast is uncertain. Address all useful
+lint findings; change the source, then rerender.
+
+For a directed connector, positive `bend` moves its quadratic control point to
+the viewer's right side of the source-to-target chord; negative moves it left.
+For a left-to-right connector, positive bends down and negative bends up. The
+visible midpoint moves by half the authored bend value. Inspect branching
+connectors instead of guessing their sign.
+
+If the repository uses its own font or icon package, read
+[customization.md](customization.md). Do not add MonoLisa or another
+proprietary or restricted font to the repository. Default SVG rendering embeds
+the bundled Nebula Sans Book and Bold faces. PNG rendering loads those exact
+assets for ordinary proportional text while retaining host discovery for
+explicit mono and custom font roles.
+
+
+## Use tldraw 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.
+
+## Verify
+
+1. Run `slopcamera diagram check <source> --strict`.
+2. Run `slopcamera diagram render <source>`.
+3. Confirm all five artifacts exist beside the source or in the requested
+   output directory.
+4. Inspect light and dark output at actual size.
+5. Confirm peer shapes do not imply false differences.
+6. Confirm connectors are long, bound to the intended shapes in `.tldr`, and
+   do not cross labels.
+7. If a companion note is required, confirm its path and visual reference.

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

@@ -0,0 +1,42 @@
+# Author and direct editable scenes
+
+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 `slopcamera scene plan scene.json --request request.json --json` before rendering. A frame request is:
+
+```json
+{
+  "cameraId": "camera_hero",
+  "selection": { "kind": "frame", "timeUs": 1000000 },
+  "mode": { "kind": "beauty" }
+}
+```
+
+Render with `slopcamera scene render scene.json --request request.json --json`. Inspect the actual output before delivery. A contact sheet uses explicit `timesUs`, `columns`, `cellWidth`, and `cellHeight`; a video uses a half-open microsecond range and rational `{numerator, denominator}` frame rate. Keep images, text, and diagrams in camera-view layers when their flat layout matters. A different aspect requires an explicit camera/layout decision.
+
+Keep asset payloads local, declared, and digest-bound. Never invent provenance, units, font coverage, or color metadata to force admission. Unsupported GLB features, fonts, and color profiles need an explicit asset conversion or a different authoring workflow. The scene parser never executes source or downloads resources. Existing reviewed HTML workflows remain suitable for effects outside the closed scene profile.
+
+For a media project, finish ordinary timeline/audio edits before V2 migration. Read `slopcamera operations show spatial.project.migrate --json` and snapshot the exact project basis. Migration retains the old media state in one immutable aggregate; old editing commands then reject the V2 head. Scene patches require both the project basis and scene digest, plus explicit all-shot or selected-shot retargeting.
+
+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.
+
+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.
+
+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 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.
+
+## Share native assets and camera samples
+
+On current source, `studio asset <studio-id> --output-id <id> --asset-id <asset-id> --representation native|encoded-video [--frame <index>] --json` admits one exact successful native output or existing encode. Preserve the returned asset, binding and receipt together. Admission never executes source or silently transcodes an incompatible GLB. Use named frame indices; do not select an implicit latest derivative.
+
+`scene camera-track <scene.json> --request <request.json> --output <track.json> --json` evaluates explicit calibrated samples without a browser. Use `slopcamera help scene` for the request contract. The native helper transfers camera intrinsics, pose, world scale and clock; it does not guarantee equal lighting or shader output between renderers. Keep native rigs in the native bundle and use a compatible static model when the portable representation cannot preserve them.

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

@@ -0,0 +1,18 @@
+# Direct short generated clips
+
+These commands require current source. Check the installed `slopcamera help direct` and [installation reference](install.md) before preparing a paid session.
+
+
+Use `slopcamera direct --help` for the installed command contract and read the [complete directing guide](https://github.com/hraness/slopcamera/blob/main/docs/directing-video.md) for recipe examples. Start with `slopcamera direct init recipe.json --json`, edit the stable `direct_<id>` and ordered shots, then run `slopcamera direct plan recipe.json --json`. Planning reads live Gateway capabilities, per-second pricing, and image transport requirements without a paid generation. Use [gateway-media.md](gateway-media.md) for model discovery and process-local credentials. Gateway reads `AI_GATEWAY_API_KEY` before `VERCEL_OIDC_TOKEN`.
+
+To use a rendered scene frame, pass the exact returned PNG path to `slopcamera direct anchor --input <image> --json`. Set a shot's `firstFrame` to `{kind: "image", source: <complete returned reference>}`. The import is local; generation uploads only the exact references acknowledged by `--allow-cloud-upload` on that invocation. A later shot can instead set `firstFrame` to `{kind: "shot-end", shotId: "<earlier-shot-id>"}` to use its currently accepted predecessor's final decoded frame. Optional `lastFrame` needs a first frame and live model support. Retain authored prompts for every shot and inspect motion, geometry, lighting, and identity at each join. Endpoint conditioning doesn't carry a provider neural checkpoint or complete 3D world state.
+
+For a shot whose planned `inputTransport` is `url`, configure an existing private Vercel Blob store and include `--allow-reference-hosting` alongside `--allow-cloud-upload`. H3 Max currently needs this path for image conditioning. Blob prefers `VERCEL_OIDC_TOKEN` with `BLOB_STORE_ID`, then falls back to `BLOB_READ_WRITE_TOKEN`; a Gateway API key alone cannot authorize Blob. The adapter copies at most two exact retained PNG, JPEG, or WebP images of 30 MiB each, verifies bytes and private access, then grants the model signed GET access that expires 15 minutes after issuance. It doesn't publish public URLs or retain credentials and signed URLs. GET access doesn't imply support for every provider download method. Budget for Blob storage, operations, and transfer separately from the Gateway estimate.
+
+Create the retained budget once with `slopcamera direct start recipe.json --budget-usd <authorized-USD> --json`. Generate one deliberate take with `slopcamera direct generate <direct-id> --shot <shot-id> --attempt <take-id> --allow-paid-generation --json`; include the upload and hosting flags required by its references and planned transport. Inspect the actual output, then record `slopcamera direct review <direct-id> --attempt <take-id> --decision accepted|rejected --note <review> --json`. Acceptance requires a completed video with its retained endpoint. A successful provider response can still fail local timestamp or color admission; retain those paid bytes for inspection and explicit conversion. Supported opaque 8-bit YUV with missing color tags uses the retained `untagged-8bit-yuv-assume-bt709-v1` policy: missing transfer, primaries, and matrix mean BT.709; missing range means limited range. Receipts preserve the observed tags and assumptions. Endpoint images become sRGB; conflicting tags, HDR, 10-bit formats, and video with alpha are rejected without tone mapping. Admitted RGB formats are opaque `rgb24`, `bgr24`, and `gbrp`. A rejected output and its budget reservation remain retained; another generation needs a new take ID and explicit paid invocation.
+
+Activate changed recipes with `slopcamera direct revise <direct-id> --recipe revised.json --json`. Inspect selection status with `slopcamera direct inspect <direct-id> --json`. Changing a shot or selecting a different predecessor invalidates dependent takes; unrelated accepted shots stay valid. Old recipes and takes remain available. After interruption, use `slopcamera direct resume <direct-id> --attempt <take-id> --json`. Resume reconciles local receipts and missing endpoint extraction without resubmitting a provider call. A missing journal on resume cannot release a reserved or ambiguous take; recovery can still attach a completed local receipt. Only a new reservation proven undispatched during its generation invocation can be released. The budget uses catalog estimates, not settled invoices or a provider spending cap; Gateway may make several provider attempts even with client retries disabled.
+
+Inspect `referenceHosting` in generation results or error details. `cleanupRequired: true` needs follow-up through the included `receiptPath` and `cleanupCommand`; the receipt may be absent when unreadable. Retain `artifacts/slopcamera/private/directing-blob/<direct-id>/<take-id>/receipt.json` after failures. Only per-entry `cleanup: "deleted"` confirms removal; `pending` or `uncertain` needs attention. Access expiry doesn't delete storage. Run `slopcamera direct cleanup <direct-id> --attempt <take-id> --json` with credentials for the same Blob store to reconcile exact objects. Cleanup is repeatable and never regenerates video; an absent object can remain uncertain when the original upload's remote outcome is unknown. Automatic cleanup runs after completed or proven-undispatched calls and preserves references for ambiguous calls. Manual cleanup revokes future object access, so let an active generation finish if it still needs its references. Resume is local and doesn't perform Blob cleanup.
+
+Run `slopcamera direct assemble <direct-id> --json` only when all shots have current accepted takes. Assembly returns an ordinary V1 video project with clips in recipe order and cuts based on measured video spans. Source audio plays at unity gain within each span; leading or trailing audio outside it is trimmed so audio padding doesn't extend the video placement. Cumulative native rational video durations determine floored microsecond cuts. The version-two assembly receipt records video spans, cut positions, and audio trims under a new assembly identity while retaining older projects and take records. YUV clips use a retained sRGB RGB derivative encoded losslessly with FFmpeg `libx264rgb`, using the endpoint's color interpretation and complete copied audio. Placements apply the trims; derivative admission verifies frame timestamps, final-frame duration, geometry, and audio timing. Original media remains unchanged. This local encode is bounded to 120 seconds and 512 MiB per derivative. Keep the original, derivative, and normalization receipts, which bind source/output hashes, interpretation, and encoder version. Inspect the returned project ID, apply ordinary timeline or audio edits, and use `slopcamera project render plan|run <project-id> --json` for delivery. Review, resume, and assembly are local and need no cloud credential. This path doesn't replace candidate footage in the V2 scene compositor. Preserve receipt and source files when reusing a project or continuing a directing session.

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

@@ -0,0 +1,26 @@
+# Make an educational film
+
+Use current-source `studio init lesson --template manim-lesson` for Manim visuals, or combine existing diagrams and spatial scenes when they better express the subject. Read [native studio](native-studio.md) for retained jobs and [video projects](video-projects.md) for composition.
+
+Preserve supplied mathematical facts, units and labels. Separate an explanatory illustration from a measured simulation or formal proof. Use tested lesson helpers for layout, axes, typography, equations and camera framing; inspect the actual rendered notation and endpoints rather than trusting syntactically valid code.
+
+## Retain and render visuals
+
+The Manim starter contains a scene, lesson data and explicit toolkit helpers. Its initial profile is Cairo, 480×854, 24 fps and ten seconds of silent visuals. Select the exact Python environment; dependencies such as Typst belong to that environment. Edit the scene/data, retain every helper with `studio bundle`, then copy the returned bundle hash into a new job ID. Use `studio plan`, `probe` and an explicitly trusted `run` before `inspect`, `encode` and `assemble`.
+
+Native frame intervals are half-open. Keep the lesson's animation clock inside the declared interval; a requested duration does not stretch or align independently authored content. Retain the original high-precision frames and source, even if an ordinary delivery uses a smaller derivative.
+
+## Place narration and effects explicitly
+
+Manim owns silent visuals. Narration or SFX references in lesson data do not automatically synthesize, import, align or place audio. Use caller-supplied audio, an authorized local voice tool, or [Gateway speech](gateway-media.md), then inspect duration and place its exact file in the ordinary project:
+
+```sh
+slopcamera project add <project-id> narration.wav --role dialogue --at 0 --json
+slopcamera project add <project-id> cue.wav --role other --at 3 --json
+```
+
+Imported audio has unverified synchronization. For independently authored timestamps, inspect the complete edit and use `--allow-unverified-sync` only when that provisional timing is intended. For synchronized recordings, measure/apply alignment first. Keep subtitles and transcript wording reviewable; authored word times and mouth cues are not measured alignment. Rhubarb cues describe mouth shapes, not word boundaries.
+
+## Review the explanation
+
+Inspect meaningful frames, equations, crop and safe areas at delivery dimensions. Check that narration describes the visible state at the same time, effects do not mask speech, and the ending has no clipped sound or black padding. Play the actual audio when supported; otherwise report duration, levels and timing checks without claiming listening. Keep the explanation's original source, audio and project timing independently revisable.

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

@@ -0,0 +1,134 @@
+# Generate media through Vercel AI Gateway
+
+Use this workflow when the user asks Slopcamera to generate an image, video, spoken
+audio, or transcript. The Slopcamera process uses the caller's Vercel AI Gateway
+credential. It has no Slopcamera account, credential store, or hosted project.
+
+## Start with the intended role
+
+Clarify what the generated media needs to do in the final project:
+
+- the subject or message;
+- the source files that control identity, composition, or timing;
+- the number of alternatives;
+- the delivery aspect ratio and duration when relevant; and
+- the details that must remain recognizable or unchanged.
+
+Preserve the user’s subject, supplied copy, identity constraints and requested omissions. A literal generation request keeps its literal prompt; a creative brief can require authored scene details. Vary only the dimensions the request leaves open.
+
+## Discover a current model
+
+The Gateway catalog changes independently of Slopcamera. Inspect it instead of
+guessing a model ID or provider option:
+
+```sh
+slopcamera ai models list --type image --json
+slopcamera ai models list --type video --json
+slopcamera ai models list --type speech --json
+slopcamera ai models list --type transcription --json
+slopcamera ai models show <model-id> --json
+```
+
+Choose a model whose reported capabilities match the requested input and
+output. Do not assume that an image model accepts references, a video model
+accepts first and last frames, or a speech model exposes a particular voice.
+Use `slopcamera help ai` for the current common flags. Put provider-specific options
+in a private ignored JSON file and pass it with `--provider-options`.
+
+## Keep credentials out of the project
+
+Prefer a process-local environment variable:
+
+```sh
+export AI_GATEWAY_API_KEY='<value>'
+```
+
+When the workspace is linked and the user is authenticated with Vercel, prefer
+`vercel env run -- bun "$SLOPCAMERA_SOURCE_ROOT/apps/desktop/dist/cli/main.js" <arguments>`. [Source installation](install.md) defines this root; its shell function cannot be launched by another program. Vercel injects credentials only into that child invocation. Slopcamera reads `AI_GATEWAY_API_KEY` first and
+`VERCEL_OIDC_TOKEN` second. Never place either credential on argv, in a
+project file, in provider options, in a prompt, or in task output.
+
+## Generate the requested media
+
+Use a prompt file when the brief is long enough that shell quoting could alter
+it.
+
+```sh
+slopcamera ai image generate \
+  --model <image-model-id> \
+  --prompt-file image-brief.txt \
+  --aspect-ratio 16:9 \
+  --count 3
+
+slopcamera ai video generate \
+  --model <video-model-id> \
+  --prompt-file shot-brief.txt \
+  --image product.png \
+  --duration 6 \
+  --aspect-ratio 16:9 \
+  --allow-cloud-upload
+
+slopcamera ai speech generate \
+  --model <speech-model-id> \
+  --text-file script.txt \
+  --format wav
+
+slopcamera ai transcribe interview.wav \
+  --model <transcription-model-id> \
+  --format all \
+  --allow-cloud-audio-upload
+```
+
+The image and video commands also support masks, first and last frames,
+multiple references, resolution, FPS, seed, generated audio, and bounded
+provider options when the selected model reports those capabilities.
+
+## Treat local upload as a separate decision
+
+Slopcamera never uploads local reference media or transcription audio implicitly.
+Use `--allow-cloud-upload` only when the task authorizes sending each named local reference to Gateway and the model provider. Use `--allow-cloud-audio-upload` for authorized transcription audio. Reuse explicit authorization already given; ask only when the selected upload or spending scope is missing.
+
+A public HTTPS reference may still be sensitive because its URL is visible in
+shell and process history. Do not use signed, private, local-network, or
+credential-bearing URLs.
+
+## Inspect and import the selected output
+
+Outputs and immutable receipts are written below
+`artifacts/slopcamera/generated/`. Slopcamera decodes self-describing media before it
+suggests a project import command. Inspect each candidate at its intended size
+or duration. For a reference-led request, verify silhouette, lettering,
+proportions, color, and other identity-bearing details before selecting it.
+
+When a generated artifact belongs in an existing video project, use the exact
+`slopcamera project add ...` command returned by Slopcamera rather than reconstructing its
+path or role. Generated images and video normally enter as b-roll; generated
+speech normally enters as dialogue.
+
+Never automatically retry an interrupted or failed paid generation. Slopcamera uses
+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.
+
+## Finish the task
+
+Report:
+
+- the selected model and the capability that justified it;
+- which local files, if any, were explicitly uploaded;
+- each useful generated output and receipt path;
+- the project import command or imported placement when applicable; and
+- what you inspected before accepting the result.
+
+## Directing and the portable image command
+
+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.
+
+## Style recipes
+
+For the rubber-stamp travel field-note layout (photograph left, small hand-stamped
+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.

package/skills/slopcamera/references/install.md

@@ -0,0 +1,62 @@
+# Install and diagnose Slopcamera
+
+Use this reference when the CLI is unavailable, a command differs from the installed release, or `slopcamera doctor` reports a missing dependency for the selected workflow.
+
+## Install the CLI
+
+Slopcamera requires Bun 1.3.14 or newer. Check the current machine before changing
+it:
+
+```sh
+command -v bun
+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 currently installs from source. No renamed release archive has been published. 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.
+
+For a new source checkout:
+
+```sh
+git clone --branch main https://github.com/hraness/slopcamera.git slopcamera-source
+cd slopcamera-source
+git rev-parse HEAD > ../slopcamera-source-commit.txt
+bun install --frozen-lockfile --ignore-scripts
+bun run build:sdk
+bun run build:desktop:cli
+export SLOPCAMERA_SOURCE_ROOT="$PWD"
+slopcamera() { bun "$SLOPCAMERA_SOURCE_ROOT/apps/desktop/dist/cli/main.js" "$@"; }
+```
+
+Keep the checkout and commit record. Restore the same path and function in a later shell. The function is local to that shell; another program cannot launch it as an executable. For an already linked Vercel workspace, use the built entrypoint explicitly:
+
+```sh
+vercel env run -- bun "$SLOPCAMERA_SOURCE_ROOT/apps/desktop/dist/cli/main.js" ai models list --type image --json
+```
+
+Vercel injects credentials only into that child. Use the same explicit launcher for each provider call that needs those credentials. Do not infer the source root from the current production directory. Inspect the resulting host:
+
+```sh
+slopcamera --help
+slopcamera doctor --json
+slopcamera workflows list --json
+slopcamera skill path
+```
+
+`slopcamera skill install` installs that same checkout’s guide for Codex by default; use `--target claude` or `--target agents` for another Agent Skill reader. Optional native engines remain separate. Do not invoke historical paid World Labs commands as a substitute for missing capabilities.
+
+## 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
+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.
+
+Gateway generation uses the caller's `AI_GATEWAY_API_KEY` or
+`VERCEL_OIDC_TOKEN`. Keep credentials in the process environment and never
+persist, print, or place them on argv. A missing credential is not permission
+to switch providers.

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

@@ -0,0 +1,31 @@
+# Direct a native film studio
+
+These commands require current source; check [installation](install.md) and `slopcamera help studio`.
+
+Use `slopcamera studio` when the deliverable needs native Blender, CadQuery or Manim authoring. Keep the native source, caches and exact settings alongside review frames and final clips. This complements the existing Three/Spark scene and ordinary video-project workflows.
+
+1. Choose a starter with `slopcamera studio init <directory> --template blender-product|blender-character|blender-shaded-street|blender-cloth|blender-fluid|cadquery-bracket|manim-lesson`.
+2. Edit the source, explicit file list and typed job. Retain all helpers and input assets with `slopcamera studio bundle <source.json> --json`. After source edits, use its new `bundleSha256` and a new job ID.
+3. Inspect `slopcamera studio plan <job.json> --json`. It does not load a native engine. Use `studio probe` with an explicit `--blender-bin` or `--python` path to inspect the installed runtime.
+4. Run the requested trusted source using `slopcamera studio run <job.json> --allow-trusted-code` and the same explicit runtime selection. This executes as the current user without an OS sandbox. Importing an asset or source is not permission to execute downloaded code.
+5. Review actual geometry, frames, simulation caches and physical output receipts. For a successful PNG sequence, `slopcamera studio encode <studio-id> --output-id beauty --json` returns a verified video derivative. Use `studio assemble <studio-id> --output-id beauty --json` to create an ordinary project from an opaque sequence, add the selected video/audio with `project add`, and render the intended delivery.
+
+The default Blender starter requests Cycles GPU. Missing GPU support fails instead of silently switching to CPU. A separate bake job retains a native scene and caches; rendering an existing cache is a separate source bundle and job. Native control rigs, materials and physics are broader than the portable spatial scene contract.
+
+`studio assets search|describe|plan|import` provides a free Poly Haven HDRI/PBR/glTF route. Search and selections are JSON inputs, and import consumes the complete saved plan. Preserve attribution, license, all listed dependencies and returned hashes. Import does not insert or execute the asset. Other native assets should come from user-supplied or explicitly authorized downloads, with their actual license and dependencies retained.
+
+Use the existing Gateway catalog, generation, speech and transcription operations for missing images, reference clips and narration. Provider calls use their normal cost and upload controls; native rendering does not make a paid call. Manim owns silent visuals. The ordinary project owns narration, music and effects, so audio revisions do not require rerendering mathematical animation. Distinguish authored word/mouth cues from measured alignment and review the final sound when playback is available; report signal-only checks otherwise.
+
+A failed or interrupted job is never automatically rerun. `studio inspect` rechecks retained evidence; `studio reconcile` restores only a matching completed validation checkpoint. Review custody before choosing a new job. Do not delete a machine activity marker to bypass unresolved work.
+
+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.
+
+## 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.
+
+Use [directed scenes](directed-scenes.md) for calibrated `scene camera-track` samples, world-space media and saved splats. Three and Blender share explicit geometry/camera data or rendered pixels, not one live renderer or automatic lighting equivalence. The external vgpu example uses its own pinned Node/Dawn environment, not a fourth studio engine.
+
+Encoding preserves PNG masters. RGB sequences produce lossless RGB video; straight RGBA produces QTRLE MOV. A 16-bit sequence records its 8-bit derivative policy. `studio assemble` initially admits opaque sRGB sequences up to 4096 pixels per side, 4000 frames and 60 seconds; transparent and linear/data passes need their explicit compositing paths.
+
+For `.studio.run()` inside a durable local workflow, use [workflows and SDK](workflows-sdk.md). Generic plan approval never supplies native authority: execution needs invocation-scoped `--allow-trusted-code` plus the selected studio runtime. For Manim visuals with narration, read [educational video](educational-video.md); lesson audio references do not automatically synthesize or place tracks.