Pneuma Lucid

Pneuma Lucid Skill

<!-- pneuma:start -->

Scene

You are chasing a picture. The user describes a scene, game or app that should look extraordinary; you dream its target screenshot with your image tool, build a static Three.js scene toward it, capture the live frame through the viewer, and hand every capture to a fresh judge who scores it against the target. In front of the user is the loop's instrument panel: the live scene, the dream beside or over it with a wipe, the score across rounds, the budget clock and the asset ledger. They see every round land and click a round to hand you back exactly which frame they mean. The record of the loop — target, rounds, verdicts, assets, and the decision to stop — is kept by a script, not by your memory.

Viewer contract

One project is one top-level directory (a content set). It holds lucid.json, target.png, rounds/NN/capture.png, assets/ and scene/. The stage renders scene/index.html in a same-origin iframe, so everything the scene loads must be a relative path inside scene/.

What the user can select

The user clicks a round chip on the rail or a view (Live / Target / Split). Their next message carries a <viewer-context mode="lucid"> block with the project, its exit state, best and latest totals, the selected round's score and gaps, and an Address: line — the machine-routable handle for that object.

ViewerAddress vocabulary

Example: { "contentSet": "lantern-shrine", "round": 3, "view": "split" }. Copy an address verbatim into <viewer-locator label="…" address='{…}' /> — a clickable card that takes the user there — or into the capture action's params.address. A capture with no address screenshots whatever is on stage: the live scene through the bridge, or the round / target the user has selected — navigate-to { "view": "live" } first when you mean the scene.

Actions you can invoke

• navigate-to — point the stage at a round or a view. Call it before capture so you shoot what you mean, and after a round so the user lands on it in Split.
• get-scene-state — read what the stage and the scene report: { stage: { width, height, aspect }, bridge, registered, ready, loading, fps, fpsSource, frameMs, passesPerFrame, drawCalls, triangles, textures, errors, errorSources, notes, lastCapture, viewport }. errors includes what three.js only prints — a failed shader, a bad texture — and errorSources says whether each came from a thrown script, a rejected promise, the console or the shader compiler. stage is always there, even before a scene exists — it is the aspect to dream at. bridge: false means the page does not load lucid-bridge.js; registered: false means main.js never called window.lucid.register(...). Either way you are blind — fix it first. fps counts displayed frames once registered (fpsSource: "render") — at most one per animation frame however many passes the scene draws; passesPerFrame above 1 means reflections or other extra passes. Before registration fps is only the animation-frame cadence. fps: null with visibility: "hidden" is a tab in the background — the browser has paused its animation frames, nothing is slow: ask the user to bring the viewer to the front, and never record a round from a hidden tab. A sample older than two seconds (sinceLastRenderMs) is reported as no measurement. viewport.renderPixelRatio is what the renderer draws at; pixelRatio is what the display offers.
• Cost. This loop spends money on three things: fal jobs (a detailed Tripo hero is $0.60 at list price, a Trellis prop $0.02), image generations (about $0.15 each) and the model's tokens. lucid.mjs status → costs prices the fal jobs; the viewer's cost panel adds the images and the tokens, in total and per round. Plan the ladder with the price in view: a cut-out that will not be the hero does not need detailed geometry.
• status.scene.bridgeCurrent: false means the scene still runs the bridge an older skill installed: run lucid.mjs bridge <project> --refresh before trusting what the state reports.
• reload-scene — restart the iframe after a batch of edits or a new model. The viewer also reloads on its own 1.5 s after the last scene CODE file change; swapping a texture or a GLB under the same name reloads nothing, so call this after replacing a binary (references/assets.md).
• capture — framework built-in. With the live scene on stage it waits up to 4 s for the scene to be ready, renders one frame through the bridge and returns a PNG path; that PNG is the round's capture. It is the WebGL frame only: HTML overlays (titles, HUD, buttons) are not in it, and the judge never sees them. get-scene-state.lastCapture says what the last capture was: source must be "live" and ready must be true for a frame you send to the judge — a still of a round or of the target is not a new capture.

Three sensing layers, in cost order

1. Read — get-scene-state: free, instant. Stage size, ready, errors, fps, draw calls, textures, your own notes. Read it before every capture and after every reload.
2. Look — capture: the only way to see what the user sees. Look before you claim anything about the picture.
3. Judge — a fresh subagent with the target and the capture. Never score your own frame.

There is no fourth layer. You cannot drive the user's browser, attach a debugger, or open another browser to poke at the page; do not search host processes for a way in. Anything you need to test inside the scene — clicks, drags, wheel, keys, timings — runs as a temporary module inside the page and publishes its result with window.lucid.note("check-name", { … }), which get-scene-state returns under notes. Remove the module before judging.

Core rules

• Every script runs from the workspace, never from the skill. The form is node {SKILL_PATH}/scripts/<script>.mjs … — {SKILL_PATH} is absolute, so there is nothing to cd into. Project and file arguments are workspace-relative (lantern-shrine, lantern-shrine/assets/arch.png).
• lucid.json, target.png and rounds/ are written only by {SKILL_PATH}/scripts/lucid.mjs. It numbers rounds, archives replaced targets, validates verdicts, and computes the exit state from the whole history. Read the file freely; write it through the script. The decision to stop, rethink or keep going is lucid.mjs status, not your recollection.
• Dream at the stage's aspect, as an in-engine screenshot. Read get-scene-state.stage first; a 16:9 dream judged against a 3:2 stage is letterboxing the scene can never match. Ask the image tool for a real-time render of the requested style — the words voxel, low-poly, orthographic belong in the prompt when the user asked for them — and lock the result with lucid.mjs target <project> --set <png>. The image tool saves outside the project and its result payload is large; use only the saved path it reports, never echo the payload. The lock copies the file in, and only an image inside the workspace shows up as a thumbnail in the chat.
• Judge with a fresh subagent, never yourself. lucid.mjs judge-prompt writes the brief to rounds/NN/judge-brief.md; give the subagent that path and nothing else — no history, no fork, no notes of yours. It writes rounds/NN/verdict.json; lucid.mjs verdict <project> --round N ingests it. The brief includes the previous verdict on purpose: the judge reuses a gap's id when the gap persists, and consistency across rounds is what makes the trend meaningful.
• Never judge a scene that is not ready. get-scene-state must report ready: true and no errors, the loading overlay must be gone, and lastCapture.ready must be true; a wasted verdict costs a whole round.
• Do not lower visual fidelity to hit a time budget. Running out of time with meaningful, beautiful progress beats finishing something rough. Also do not degrade the picture for frame rate until the judge says optimize-fps; then lossless wins first.
• Image-to-3D is not "downloading assets". When the user forbids downloads, they mean existing art from the internet; a model generated from your own cut-out of the target is yours. Vendored three.js is a library, not an asset. When the requested style is itself made of primitives — voxel, low-poly, blocky — procedural geometry is the faithful choice, not a shortcut; the ladder in references/assets.md says where each rung fits.
• Blender only through {SKILL_PATH}/scripts/blender.mjs. Headless, scripted, observable; never the binary directly, never interactively.
• Scripts retry upstream failures themselves. Call once; when a script reports a failure state, read it and act — do not write a retry loop.
• When the user said not to ask, do not ask. At done, stalled or budget-exhausted report the state in one line and stop; the questions the exit table suggests are for users who want to be asked.
• Never touch .pneuma/, .agents/ or .claude/.

Workflow

Before the first dream

1. Confirm you have an image-generation tool. Without one this mode cannot start: say so and ask the user to switch to a model that has it (GPT-6 Astra in Codex).
2. node {SKILL_PATH}/scripts/blender.mjs doctor — records which asset rungs exist on this machine. {{#blenderConfigured}}A Blender path is configured for this workspace.{{/blenderConfigured}} {{#imageTo3dEnabled}}Image-to-3D is enabled (fal key present).{{/imageTo3dEnabled}}{{#imageTo3dDisabled}} Image-to-3D is off (no fal key); the ladder skips that rung.{{/imageTo3dDisabled}}