Add a game artwork integration workflow and REA companion example

.agents/skills/integrate-game-art/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: integrate-game-art
+description: "Plan, obtain, validate, and integrate DreamLayer artwork into a playable game while preserving its mechanics. Use when a game needs background, character, UI, or sprite files; not for gameplay-only work or another image service."
+---
+
+# Integrate game art
+
+Inspect the game before requesting art: engine and import settings, logical world units,
+collision bodies, pivots, sprite dimensions, alpha requirements, animation timing, camera,
+and asset paths. Separate visual dimensions from physics dimensions. Keep a playable
+geometry baseline and record the behavior that must survive the artwork swap.
+
+Read the bundled [workflow contract](references/workflow-contract.md) for supported clients,
+authentication, billing, polling, download, and recovery. Installation supplies instructions;
+it does not connect or authenticate an MCP server. Inspect the actual available tool schema.
+If the connected client lacks download or sprite fields, use the supported client from that
+contract, or retain bundled assets and report the limitation.
+
+## Plan and obtain
+
+- Inventory reusable artwork and its license/provenance first. A downloaded sample is not
+  a new generation. Code-authored scenery should be labeled separately from DreamLayer art.
+- Produce a dry-run asset plan with role, output path, dimensions/aspect, reference, operation,
+  transparency, and estimated credits. Read live capabilities and balance before paid work.
+  Track the total authorized cap across all operations, including cutouts and animation.
+  Reserve an unresolved job's estimated charge until its canonical status resolves it.
+- For image operations use `generate-or-edit-image`; for animation use
+  `sprite-sheet-from-reference`, when installed. Both follow the bundled contract. If a task
+  skill is absent, use the contract and actual public schemas instead of inventing fields.
+- Save request, idempotency key, execution ID, and event cursor locally without credentials.
+  Resume existing jobs after interruptions. Download to a new path and verify the file before
+  marking an asset available. Never rerun generation to repair a download failure.
+
+## Integrate and verify
+
+Inspect each image. Check decoded format, dimensions, actual transparent pixels, visual
+coherence, ground anchor/pivot, frame order, and per-frame timing. Prefer a reviewed still
+frame when animation details drift; disclose the decision. Use the delivered timing array
+when it differs from a rounded duration label, and record the discrepancy.
+
+Keep collision and timing code independent of texture size. Add a baseline/artwork toggle
+when useful for comparison. Validate both modes with the same deterministic input sequence,
+then play a complete loop in the actual browser or engine. Test controls, pause/restart,
+small screens, and reduced motion for decorative animation. For Godot/Unity use their
+installed import skills; do not claim an engine was tested because its import files exist.
+
+Record file digests, dimensions, upstream revision or generation execution ID, transformations,
+historical costs separately from new charges, and any unverified behavior.
+
+## Runnable example, no paid calls
+
+The [Relay garden example](https://github.com/TheDesignFounder/dreamlayer-game-assets)
+bundles an original DreamLayer environment, six matching game objects, and a geometry mode. With Node.js 22.19+ on the 22.x line (or another REA-supported version):
+
+```sh
+git clone https://github.com/TheDesignFounder/dreamlayer-game-assets.git
+cd dreamlayer-game-assets
+npm ci
+npm test
+npm run validate:assets
+npm run art:plan
+npm start
+```
+
+Open `http://127.0.0.1:4177/demo/`. No viewer key or credits are needed. Its plan script
+submits nothing and defaults to a zero-credit cap. New generation uses the authenticated
+canonical workflow above. The example's read-only recovery script never resubmits a job.
+
+Only when the task actually needs artifact investigation, read
+[the REA companion](references/rea-investigation.md). Ordinary game artwork does not require REA.

.agents/skills/integrate-game-art/references/rea-investigation.md

@@ -0,0 +1,27 @@
+# Optional REA investigation
+
+Use Reverse Engineer Anything when a shipped, compiled, or minified artifact helps answer
+a bounded behavior question. If readable project source already answers the question,
+inspect it directly. DreamLayer is an artwork tool, not a REA analysis provider.
+
+Record origin, version/revision, redistribution permission, SHA-256, and the exact question.
+Preserve original bytes and keep analysis Evidence private until sanitized. Distinguish
+REA observations, the agent's interpretation, runtime verification, and later source checks.
+
+Relay garden uses a self-authored minified JavaScript target. It is a controlled example,
+not a recovered commercial game and not a blind evaluation. REA 6.5.0 locates a Math.hypot
+read, its enclosing function, and a caller relation. The agent interprets the artifact's
+formula; numeric runtime tests establish the bounded equivalence. REA reports partial
+coverage and unresolved facts, which must remain in the account.
+
+```sh
+# Inside the example after npm ci; the pinned REA CLI needs no native analysis engine.
+npm run investigate
+npm test
+```
+
+Full local Evidence is written under `.local/`. The public excerpt is not an importable
+Evidence record. Read the example's `docs/rea-workflow.md` for exact commands and boundaries.
+For REA MCP setup use [REA's official installation guide](https://github.com/morluto/rea/blob/main/docs/installation.md).
+Do not claim CLI execution proves MCP registration. Installing this skill registers neither
+REA nor DreamLayer. Do not modify upstream REA for the example.

.agents/skills/integrate-game-art/references/workflow-contract.md

@@ -0,0 +1,46 @@
+# DreamLayer workflow contract
+
+Use the installed DreamLayer MCP tools, or the pinned CLI when MCP is unavailable.
+Read the actual tool schema before calling. Never pass fields a client does not expose.
+
+## Setup
+Requires Node.js >=22.12 and a DreamLayer API key from https://platform.dreamlayer.io.
+Install the supported sprite-capable beta: `npm install -g dreamlayer@0.4.0-beta.4`.
+MCP: `npx -y @dreamlayer/mcp@0.4.0-beta.5`. Supply DREAMLAYER_API_KEY to the server process using the host's secret settings. Never commit keys or put them in prompts.
+The stable npm tag remains 0.3.0. Do not claim it supports this complete workflow.
+
+## Before paid work
+1. Read dreamlayer_capabilities and dreamlayer_balance (or CLI capabilities/balance --json). If either fails, resolve it before spending.
+2. Confirm the requested operation is advertised. Ordinary completed image operations currently cost one credit each; obtain the live cost from capabilities. A multi-step edit and cutout costs two operations.
+3. Use the user's already-authorized operation, number of outputs and credit budget. Ask only if missing. Never buy credits or expand the batch implicitly.
+4. For file operations, verify input readability and a new output path before submitting. Upload once using dreamlayer_upload_image; preserve its input_asset_id.
+5. Save a unique idempotency_key and the complete request locally before each generation. Do not store credentials in the job record.
+
+## Execute and recover
+Select operation explicitly: text_to_image; image_to_image; background_remove; upscale; sprite_sheet.
+All except text_to_image require input_asset_id. Generate returns execution_id, status, asset, question and last_event_id.
+Preserve IDs/cursor after each response. For running work, call dreamlayer_execution or dreamlayer_events; do not generate a replacement after a timeout.
+A needs_input result is a question, not a failed generation. Continue using conversation_id and respond.
+For completed work, dreamlayer_download writes an absolute new local path. Never treat a returned asset URL as proof that the local file exists.
+On a local download error, repair the destination and download the same execution.
+File-based CLI retries upload a new asset; use status and download after uncertainty rather than rerunning the paid command.
+Stop at insufficient credits, invalid request, unsupported operation, or an unresolved contract error. Keep recoverable state; do not loop paid retries.
+
+## Output acceptance
+Inspect the saved image or preview. Check dimensions, transparency if requested, text spelling, reference fidelity and the intended use. Label uninspected outputs.
+PNG output does not establish SVG/vector structure, pixel-perfect art, trademark clearance, print compliance, exact product fidelity or consistent animation.
+API documentation: https://docs.dreamlayer.io/agent-api
+Recovery: https://docs.dreamlayer.io/agent-api/jobs-and-events
+
+## CLI examples
+```sh
+dreamlayer capabilities --json
+dreamlayer balance --json
+dreamlayer generate "Original image brief" --aspect 1:1 --idempotency-key UNIQUE_SAVED_KEY --out concept.png --json
+dreamlayer edit reference.png "Change the background to a simple studio scene" --idempotency-key UNIQUE_SAVED_KEY --out edited.png --json
+dreamlayer cutout reference.png --idempotency-key UNIQUE_SAVED_KEY --out cutout.png --json
+dreamlayer status EXECUTION_ID --json
+dreamlayer download EXECUTION_ID --out recovered.png --json
+```
+Placeholder IDs and keys must be replaced. Check CLI --help for supported flags; --max-credits is for sprite jobs.
+

.cline/skills/integrate-game-art/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: integrate-game-art
+description: "Plan, obtain, validate, and integrate DreamLayer artwork into a playable game while preserving its mechanics. Use when a game needs background, character, UI, or sprite files; not for gameplay-only work or another image service."
+---
+
+# Integrate game art
+
+Inspect the game before requesting art: engine and import settings, logical world units,
+collision bodies, pivots, sprite dimensions, alpha requirements, animation timing, camera,
+and asset paths. Separate visual dimensions from physics dimensions. Keep a playable
+geometry baseline and record the behavior that must survive the artwork swap.
+
+Read the bundled [workflow contract](references/workflow-contract.md) for supported clients,
+authentication, billing, polling, download, and recovery. Installation supplies instructions;
+it does not connect or authenticate an MCP server. Inspect the actual available tool schema.
+If the connected client lacks download or sprite fields, use the supported client from that
+contract, or retain bundled assets and report the limitation.
+
+## Plan and obtain
+
+- Inventory reusable artwork and its license/provenance first. A downloaded sample is not
+  a new generation. Code-authored scenery should be labeled separately from DreamLayer art.
+- Produce a dry-run asset plan with role, output path, dimensions/aspect, reference, operation,
+  transparency, and estimated credits. Read live capabilities and balance before paid work.
+  Track the total authorized cap across all operations, including cutouts and animation.
+  Reserve an unresolved job's estimated charge until its canonical status resolves it.
+- For image operations use `generate-or-edit-image`; for animation use
+  `sprite-sheet-from-reference`, when installed. Both follow the bundled contract. If a task
+  skill is absent, use the contract and actual public schemas instead of inventing fields.
+- Save request, idempotency key, execution ID, and event cursor locally without credentials.
+  Resume existing jobs after interruptions. Download to a new path and verify the file before
+  marking an asset available. Never rerun generation to repair a download failure.
+
+## Integrate and verify
+
+Inspect each image. Check decoded format, dimensions, actual transparent pixels, visual
+coherence, ground anchor/pivot, frame order, and per-frame timing. Prefer a reviewed still
+frame when animation details drift; disclose the decision. Use the delivered timing array
+when it differs from a rounded duration label, and record the discrepancy.
+
+Keep collision and timing code independent of texture size. Add a baseline/artwork toggle
+when useful for comparison. Validate both modes with the same deterministic input sequence,
+then play a complete loop in the actual browser or engine. Test controls, pause/restart,
+small screens, and reduced motion for decorative animation. For Godot/Unity use their
+installed import skills; do not claim an engine was tested because its import files exist.
+
+Record file digests, dimensions, upstream revision or generation execution ID, transformations,
+historical costs separately from new charges, and any unverified behavior.
+
+## Runnable example, no paid calls
+
+The [Relay garden example](https://github.com/TheDesignFounder/dreamlayer-game-assets)
+bundles an original DreamLayer environment, six matching game objects, and a geometry mode. With Node.js 22.19+ on the 22.x line (or another REA-supported version):
+
+```sh
+git clone https://github.com/TheDesignFounder/dreamlayer-game-assets.git
+cd dreamlayer-game-assets
+npm ci
+npm test
+npm run validate:assets
+npm run art:plan
+npm start
+```
+
+Open `http://127.0.0.1:4177/demo/`. No viewer key or credits are needed. Its plan script
+submits nothing and defaults to a zero-credit cap. New generation uses the authenticated
+canonical workflow above. The example's read-only recovery script never resubmits a job.
+
+Only when the task actually needs artifact investigation, read
+[the REA companion](references/rea-investigation.md). Ordinary game artwork does not require REA.

.cline/skills/integrate-game-art/references/rea-investigation.md

@@ -0,0 +1,27 @@
+# Optional REA investigation
+
+Use Reverse Engineer Anything when a shipped, compiled, or minified artifact helps answer
+a bounded behavior question. If readable project source already answers the question,
+inspect it directly. DreamLayer is an artwork tool, not a REA analysis provider.
+
+Record origin, version/revision, redistribution permission, SHA-256, and the exact question.
+Preserve original bytes and keep analysis Evidence private until sanitized. Distinguish
+REA observations, the agent's interpretation, runtime verification, and later source checks.
+
+Relay garden uses a self-authored minified JavaScript target. It is a controlled example,
+not a recovered commercial game and not a blind evaluation. REA 6.5.0 locates a Math.hypot
+read, its enclosing function, and a caller relation. The agent interprets the artifact's
+formula; numeric runtime tests establish the bounded equivalence. REA reports partial
+coverage and unresolved facts, which must remain in the account.
+
+```sh
+# Inside the example after npm ci; the pinned REA CLI needs no native analysis engine.
+npm run investigate
+npm test
+```
+
+Full local Evidence is written under `.local/`. The public excerpt is not an importable
+Evidence record. Read the example's `docs/rea-workflow.md` for exact commands and boundaries.
+For REA MCP setup use [REA's official installation guide](https://github.com/morluto/rea/blob/main/docs/installation.md).
+Do not claim CLI execution proves MCP registration. Installing this skill registers neither
+REA nor DreamLayer. Do not modify upstream REA for the example.

.cline/skills/integrate-game-art/references/workflow-contract.md

@@ -0,0 +1,46 @@
+# DreamLayer workflow contract
+
+Use the installed DreamLayer MCP tools, or the pinned CLI when MCP is unavailable.
+Read the actual tool schema before calling. Never pass fields a client does not expose.
+
+## Setup
+Requires Node.js >=22.12 and a DreamLayer API key from https://platform.dreamlayer.io.
+Install the supported sprite-capable beta: `npm install -g dreamlayer@0.4.0-beta.4`.
+MCP: `npx -y @dreamlayer/mcp@0.4.0-beta.5`. Supply DREAMLAYER_API_KEY to the server process using the host's secret settings. Never commit keys or put them in prompts.
+The stable npm tag remains 0.3.0. Do not claim it supports this complete workflow.
+
+## Before paid work
+1. Read dreamlayer_capabilities and dreamlayer_balance (or CLI capabilities/balance --json). If either fails, resolve it before spending.
+2. Confirm the requested operation is advertised. Ordinary completed image operations currently cost one credit each; obtain the live cost from capabilities. A multi-step edit and cutout costs two operations.
+3. Use the user's already-authorized operation, number of outputs and credit budget. Ask only if missing. Never buy credits or expand the batch implicitly.
+4. For file operations, verify input readability and a new output path before submitting. Upload once using dreamlayer_upload_image; preserve its input_asset_id.
+5. Save a unique idempotency_key and the complete request locally before each generation. Do not store credentials in the job record.
+
+## Execute and recover
+Select operation explicitly: text_to_image; image_to_image; background_remove; upscale; sprite_sheet.
+All except text_to_image require input_asset_id. Generate returns execution_id, status, asset, question and last_event_id.
+Preserve IDs/cursor after each response. For running work, call dreamlayer_execution or dreamlayer_events; do not generate a replacement after a timeout.
+A needs_input result is a question, not a failed generation. Continue using conversation_id and respond.
+For completed work, dreamlayer_download writes an absolute new local path. Never treat a returned asset URL as proof that the local file exists.
+On a local download error, repair the destination and download the same execution.
+File-based CLI retries upload a new asset; use status and download after uncertainty rather than rerunning the paid command.
+Stop at insufficient credits, invalid request, unsupported operation, or an unresolved contract error. Keep recoverable state; do not loop paid retries.
+
+## Output acceptance
+Inspect the saved image or preview. Check dimensions, transparency if requested, text spelling, reference fidelity and the intended use. Label uninspected outputs.
+PNG output does not establish SVG/vector structure, pixel-perfect art, trademark clearance, print compliance, exact product fidelity or consistent animation.
+API documentation: https://docs.dreamlayer.io/agent-api
+Recovery: https://docs.dreamlayer.io/agent-api/jobs-and-events
+
+## CLI examples
+```sh
+dreamlayer capabilities --json
+dreamlayer balance --json
+dreamlayer generate "Original image brief" --aspect 1:1 --idempotency-key UNIQUE_SAVED_KEY --out concept.png --json
+dreamlayer edit reference.png "Change the background to a simple studio scene" --idempotency-key UNIQUE_SAVED_KEY --out edited.png --json
+dreamlayer cutout reference.png --idempotency-key UNIQUE_SAVED_KEY --out cutout.png --json
+dreamlayer status EXECUTION_ID --json
+dreamlayer download EXECUTION_ID --out recovered.png --json
+```
+Placeholder IDs and keys must be replaced. Check CLI --help for supported flags; --max-credits is for sprite jobs.
+