motionloom 2.2.0 → 2.4.0

package/docs/research/agent-skill-ecosystem-notes.md

@@ -0,0 +1,47 @@
+# Ghi chú evidence: kỹ năng nội bộ và Agent Skills đa nền tảng
+
+**Ngày khảo sát:** 15 tháng 8 năm 2026
+
+## ImageGen nội bộ
+
+Skill `imagegen` hiện có của Agent là một bộ hướng dẫn routing/production cho visual deliverable. Với game asset, skill đặt tiêu chí là silhouette tái sử dụng, perspective nhất quán và clean edges; với transparent asset, tiêu chí gồm alpha sạch, subject đầy đủ, không colored fringe hoặc background/shadow không mong muốn. Skill yêu cầu phân biệt creation/editing mang tính semantic với image processing thuần deterministic, và yêu cầu lightweight validation trước delivery.
+
+Điều này tạo một boundary rõ cho MotionLoom: ImageGen có thể là **nguồn tạo hoặc chỉnh visual asset**, còn MotionLoom nhận output cùng metadata, đo alpha/geometry/atlas/runtime và quản lý evidence/review. Không được giả định ImageGen tự phát hành seed, model version, license, rig map hoặc production approval. Vì không có API/credential contract trong core MotionLoom, adapter ban đầu phải là `scaffold` receipt importer, không phải provider invoker.
+
+## Codex Skills
+
+OpenAI mô tả Skill là bundle có version gồm file và `SKILL.md`, hỗ trợ local shell hoặc hosted container, và tương thích Agent Skills standard. Khi skill được mount, model nhìn metadata rồi quyết định kích hoạt; tài liệu cũng yêu cầu xem Skill là code/instruction đặc quyền, kiểm tra trước khi tích hợp và đặt approval cho high-impact action. [1]
+
+MotionLoom cần tiếp tục giữ `SKILL.md`, artifacts và local-only default, đồng thời chỉ nhận generator metadata từ một skill đã được user/project cài đặt. Một skill descriptor không phải bằng chứng rằng output asset đã được tạo đúng hoặc được người dùng phê duyệt.
+
+## Claude Code Skills
+
+Claude Code mô tả Skill là thư mục có `SKILL.md`, có thể được load khi relevant hoặc gọi trực tiếp; built-in skills như `/debug`, `/code-review` và `/verify` cũng là prompt-based orchestration. Tài liệu đặc biệt có giá trị với MotionLoom ở ý tưởng ghi lại run/verify recipe trong project skill để agent sau đó lặp lại workflow đã thành công thay vì suy đoán lại environment. [2]
+
+MotionLoom đã đi theo cùng hướng với Project Memory và `setup/status/repair`. Adapter registry sẽ chỉ lưu provider capability/evidence, không tự động chạy một external skill hay mở PR.
+
+## Gemini CLI Skills
+
+Gemini CLI cũng dùng Agent Skills standard với lifecycle discovery → activation → consent → injection → execution. Tài liệu nêu built-in, extension, user và workspace tiers; `.agents/skills/` được dùng làm alias interoperable. Activation cần consent và skill folder trở thành permitted path sau approval. [3]
+
+Điều này củng cố hai yêu cầu cho MotionLoom: registry phải mô tả **capability** thay vì vendor prompt; và skill/adapter có side effect phải có explicit user approval. MotionLoom nên phát hành artifacts portable tại workspace/package level, nhưng không được trở thành một catalog tải/chạy skills tùy ý.
+
+## Contract decision
+
+Adapter registry sẽ dùng các giá trị sau:
+
+| Field | Quyết định |
+|---|---|
+| `adapter_id` | Tên capability ổn định, ví dụ `local-fixture` hoặc `internal-imagegen`, không phải claim về ownership/model quality. |
+| `kind` | `fixture`, `internal_skill`, `external_provider` hoặc `manual_import`. |
+| `status` | `verified`, `scaffold` hoặc `blocked`, chỉ `verified` khi có regression và runtime evidence đúng phạm vi. |
+| `invocation_mode` | `none`, `manual`, `agent-mediated` hoặc `api`; core validator không thực thi invocation. |
+| `cost_class` | `included`, `metered`, `external`, `unknown`; informational only, không phải billing proof. |
+| `evidence_requirements` | Receipt, output hashes, source/provenance reference và runtime evidence tùy output kind. |
+| `approval` | Luôn external/user; registry/receipt không chứa quyền mở PR hay production approval. |
+
+## References
+
+[1]: https://developers.openai.com/api/docs/guides/tools-skills "OpenAI API — Skills"
+[2]: https://code.claude.com/docs/en/skills "Claude Code — Skills"
+[3]: https://geminicli.com/docs/cli/skills/ "Gemini CLI — Agent Skills"

package/docs/research/ai-animation-tools-2026-notes.md

@@ -0,0 +1,81 @@
+# AI Animation and Asset Tools — Research Notes
+
+> Working research notes. Claims below are discovery leads from official-site search results and must be verified by opening the source pages before inclusion in the final report.
+
+## Initial source leads
+
+| Tool / family | Official URL | Discovery lead to verify |
+|---|---|---|
+| PixelLab | https://www.pixellab.ai/ | AI pixel-art game assets, animated characters, sprite sheets and environments. |
+| PixelLab API | https://www.pixellab.ai/pixellab-api | API-oriented generation of characters, animations and environments for procedural/live asset creation. |
+| Runway | https://runway.com/product | Text-to-video and image-to-video generation, plus image generation/editing. |
+| DeepMotion | https://www.deepmotion.com/ | Browser-based AI motion capture and body tracking that produces 3D animation from video. |
+| Rokoko Vision | https://www.rokoko.com/products/vision | Video-to-3D animation through an AI mocap solver. |
+| Scenario | https://www.scenario.com/ | Style-consistent game asset generation and animated video positioning; workflow details require verification. |
+| Leonardo AI | https://leonardo.ai/news/how-to-generate-a-full-game-asset-suite-with-leonardo-ai | Game asset ideation, iteration and refinement workflow; official article requires verification. |
+| Ludo.ai | https://ludo.ai/features/sprite-generator | Sprite generation and animation workflow; official feature page requires verification. |
+| GameLab Studio | https://gamelabstudio.co/ | AI sprite-sheet and transparent animation generation; official claims require verification. |
+
+## Planned comparison dimensions
+
+1. Input controls: text, reference image, video, pose/motion reference, style training or project memory.
+2. Output model: raster frames, sprite sheet, atlas, 2D rig, 3D skeleton animation, video, vector/timeline or runtime component.
+3. Temporal/identity consistency: seed, reference locking, character/style model, pose control, frame geometry and loop controls.
+4. Production integration: export formats, API/CLI, engine/runtime adapters, metadata, versioning and deterministic replay.
+5. Human governance: provenance, license/source records, review checkpoints, editability and approval boundaries.
+6. MotionLoom relevance: which capability belongs in project memory, contracts, analyzers, runtime evidence, Dev Lab or handoff.
+
+## Verified findings — PixelLab
+
+Source pages opened:
+
+- https://www.pixellab.ai/
+- https://www.pixellab.ai/docs/tools/animate-with-skeletons
+
+The official product page exposes separate workflows for one-click animation, skeleton-based animation and text-described animation. It also lists 4/8 directional rotation, reference-based style consistency, true inpainting, scenes, tilesets and UI elements. The animation copy explicitly targets walking, running, attacking and custom sprite-sheet animations. The page also positions scene animation as text-described motion for animated environments and dynamic backgrounds.
+
+The skeleton documentation page is currently a product/tutorial-style page rather than a full API specification. It confirms the product surface includes skeleton controls, automatic character animation and reference-driven generation, but it does not yet provide enough public detail to claim deterministic skeleton export, frame hashing, atlas metadata or runtime bindings. Those remain questions for MotionLoom to verify at the artifact/export boundary instead of inferring them from visual output.
+
+Initial design lesson: a useful AI asset tool separates **character identity/style editing**, **motion authoring**, **directional rotation**, **environment/tileset generation** and **inpainting** into distinct operations. MotionLoom should model these as explicit artifact stages and contracts, not as one generic "generate animation" action.
+
+The official PixelLab API page exposes a more structured pipeline than the homepage alone suggests. It separates image generation, image operations, animation, rotation, inpainting/editing, map/tileset generation, character/object state management and prompt enhancement. Relevant animation operations include text animation, text animation v3 with optional start/end frames and up to 16 frames, skeleton animation, skeleton estimation, character animation and animation editing. It also exposes interpolation between images/animations and outfit transfer across frames. Character and object operations are persisted as reusable entities with later states and animations, which is a useful identity-first model.
+
+The API page also reveals concrete limits and options such as transparent output, forced palettes, init images, inpainting, direction/view controls, maximum canvas/frame sizes and explicit frame counts. These are implementation facts for PixelLab's API surface, not evidence that every output is production-safe. MotionLoom should treat them as source metadata and then measure the returned artifacts independently.
+
+The official style-reference guide states that users add one or more style reference images, describe the desired asset and generate multiple variations. It describes a grid/frame-output relationship based on the largest reference-image dimension and exposes a large reference-image count at small sizes. The important lesson is that style consistency is reference-conditioned and parameterized by output geometry; it is not merely a textual prompt convention. MotionLoom's identity manifest, palette/camera/scale fields and frame-geometry analyzer are the natural verification layer after such a generator.
+
+## Verified findings — Runway and DeepMotion
+
+Runway's official Gen-4 research page describes a reference-conditioned video workflow: visual references plus instructions are used to create images/videos while maintaining consistent characters, locations, objects, style, mood and cinematographic elements across scenes and perspectives. It emphasizes that this is achieved without fine-tuning or additional training. For MotionLoom, the transferable idea is a reusable **reference bundle** and scene-level identity rather than re-prompting a character from scratch for every shot. The non-transferable assumption is that visual consistency alone proves a game-ready frame contract; raster bounds, sockets, timing and runtime evidence still need independent checks.
+
+DeepMotion's official homepage exposes two distinct products/workflows: SayMotion for text-to-3D animation and Animate 3D for video-to-3D animation. It also exposes an Animate 3D API surface in the site navigation. The key architectural lesson is the separation between **motion source acquisition** (text or video) and **3D animation output**. MotionLoom should model body animation as a source-bound motion artifact with rig/skeleton compatibility, retargeting metadata and runtime evidence, not as an opaque generated clip.
+
+Rokoko Vision 3.0's official page describes a four-step workflow: upload a video, generate 3D motion, edit/view/loop the capture in Rokoko Studio, upload a character for retargeting, then export to FBX or BVH for tools such as Blender, Unity and Unreal. This is a strong reference for MotionLoom's body-rig path because it makes cleanup, looping, skeleton choice and export explicit stages after AI inference. The page also links integrations and motion-data workflows, reinforcing that the generated result is an editable motion artifact rather than only a rendered video.
+
+Luma's official Ray3.2 page positions multi-keyframe control, Modify Video and Motion/Structure settings as first-class controls. The page exposes FAQ topics for preserving actor/performance, lip-sync/dialogue timing, source-video frame rate, footage suitability and keyframe counts. Even where the page does not expose all answers in static extraction, the architecture is clear: preserve source motion/structure while changing appearance, and use explicit keyframes to direct continuity. MotionLoom can learn the separation between source motion, structural constraints and appearance transformation, while still requiring its own runtime telemetry and artifact checks.
+
+Scenario's official platform page describes an AI creative infrastructure spanning image, video, audio and 3D, with a custom-model workflow that trains on 5–100 reference images, supports custom LoRA models and embeds brand/style guidance. It also exposes visual multi-step workflows, batch generation, reusable templates, API and MCP integration. The page lists concrete game-oriented workflows such as splitting a character/object/scene into isolated components, pose transfer and character variation, 2D animation rigging sheets, 3D auto-rigging and concept-to-game-ready 3D. The lesson for MotionLoom is to treat an AI tool as an orchestrated graph of reusable steps and agents, not only a single model call. Any claims about Scenario's internal model quality or production readiness still require artifact-level validation.
+
+The previously discovered Adobe Firefly Video Model blog URL returned HTTP 404 when opened, so it is excluded as evidence for this report. Adobe Firefly remains a candidate source for a later pass using a currently valid official product or help page; no unsupported claim is made from the stale search snippet.
+
+Cascadeur's official AI-tools documentation is unusually explicit about the division of labor. It lists AutoPosing, Inbetweening, AutoInterpolation and Video Mocap as ML-based tools, while separating AutoPhysics, Ragdoll, Animation Unbaking and Fulcrum Motion Cleaning as non-ML tools. AutoPosing predicts a pose from activated manipulators and their locations; Inbetweening predicts motion between keyed poses using pose, timing, keyframe count and style; AutoInterpolation predicts interpolation/kinematics types; Video Mocap extracts actor poses and applies them to a rigged character. Cascadeur also states that its tools assist rather than replace the animator, and that users' animations are not collected for training. This is a strong model for MotionLoom's human-governed boundary: AI proposes or fills motion, deterministic tools clean/measure it, and the user remains the authority for acceptance.
+
+The current Adobe Firefly Help URL was found through official search results but returned no extractable page content in this browser session. It is therefore not treated as fully verified evidence here. The candidate workflow is camera-motion transfer from a reference video with a start frame, but this requires a future successful page extraction before being used for a strong claim.
+
+Kinetix's current official homepage describes video-to-animation models for 3D character animation and points to integration into Unity Muse, an in-game Emote Creator for OVERDARE, and AI-assisted animation in Adobe Mixamo. This is relevant because the output is positioned as reusable in-game 3D animation, not merely a video render, and because moderation is mentioned for the player-generated emote workflow. The official publication URL suggested by the page returned 404, so no additional technical claim is taken from it.
+
+## Cross-tool pipeline synthesis
+
+Across the verified sources, the strongest tools do not rely on one prompt-to-final-output step. They expose a sequence of controls and artifacts:
+
+| Pipeline layer | Patterns observed | MotionLoom implication |
+|---|---|---|
+| Identity/style | Reference images, custom style models, init images, palettes, persisted characters/objects | Keep identity manifest, reference hashes, palette/camera/scale and derivation chain as first-class inputs. |
+| Motion source | Text action description, skeleton/pose controls, keyed poses, video performance or camera-motion reference | Bind the source type and source hash to the motion spec; do not treat generated pixels as the only source of truth. |
+| Temporal construction | Explicit frame counts, start/end frames, inbetweening, interpolation, multi-keyframes, animation-to-animation editing | Expand action-set with source keyframes, timing, loop seam and editable intermediate evidence. |
+| Spatial/rig mapping | Skeleton estimation, retargeting, 2D rig sheets, 3D auto-rigging, camera/direction/projection controls | Add rig compatibility, socket map, anchor/pivot and coordinate-system metadata before runtime rendering. |
+| Cleanup/measurement | Studio cleanup, looping, physics tools, inpainting, frame editing, palette/geometry limits | Separate deterministic cleanup and measurement from model generation; fail closed on contamination/drift. |
+| Packaging/runtime | Sprite sheets, FBX/BVH, game-engine integration, API/MCP, reusable templates and persisted states | Make export contract, runtime adapter and Dev Lab evidence mandatory for claims of readiness. |
+| Governance | Licensed training data disclosures, moderation, style ownership, human review and approval boundaries | Keep provenance and user approval separate; record source/license/model details without self-asserted authority. |
+
+This synthesis suggests that MotionLoom's differentiator should not be another generator. It should be the **artifact compiler and review governor between generators and real runtimes**: accept outputs from multiple tools, normalize their source/identity/motion metadata, measure the artifacts, render them in the target runtime, and return a user-facing evidence bundle before any PR action.

package/docs/research/ai-animation-tools-2026-report.md

@@ -0,0 +1,168 @@
+# Báo cáo nghiên cứu: Các công cụ AI animation/asset và bài học cho MotionLoom
+
+**Ngày khảo sát:** 15 tháng 8 năm 2026  
+**Tác giả:** Manus AI  
+**Phạm vi:** Công cụ được chọn đại diện cho các nhóm tạo asset game 2D, video sinh chuyển động, motion capture/retargeting 3D và workflow AI đa bước. Báo cáo ưu tiên tài liệu/trang chính thức đã mở và đọc; các tuyên bố thương mại được xem là mô tả năng lực sản phẩm, **không** phải bằng chứng chất lượng production cho một output cụ thể.
+
+> **Kết luận ngắn:** Những công cụ tốt nhất không xử lý animation như một prompt đơn lẻ. Chúng tách identity/style, motion source, pose/keyframe, cleanup, export và engine integration thành các bước có thể chỉnh sửa. MotionLoom không nên trở thành một bản sao generator; điểm khác biệt có giá trị là làm **compiler + evidence governor** đứng giữa nhiều generator và runtime thật: tiếp nhận artifact, chuẩn hóa metadata, đo đạc deterministically, render, mở Dev Lab và giữ quyền phê duyệt ở người dùng.
+
+## 1. Khung so sánh
+
+Báo cáo dùng bảy tiêu chí để tránh đánh giá tool chỉ bằng chất lượng demo. Một pipeline phù hợp cho sản phẩm cần có đường đi từ intent đến artifact, từ artifact đến runtime, và từ runtime đến review có thể truy nguyên.
+
+| Tiêu chí | Câu hỏi đánh giá | Ý nghĩa đối với MotionLoom |
+|---|---|---|
+| **Identity & style** | Có giữ được character, palette, camera, direction hay brand style qua nhiều output không? | Cần identity manifest, reference hash và derivation chain. |
+| **Motion control** | Input là text, pose, skeleton, keyframe hay video performance? | Cần bind nguồn chuyển động vào motion spec. |
+| **Temporal consistency** | Có start/end frame, frame count, in-betweening, loop hoặc action editing không? | Cần action-set và frame geometry có thể đo. |
+| **Technical export** | Output là video, raster frame, sprite/atlas, 2D rig, FBX/BVH hay runtime component? | Cần export manifest và adapter runtime phù hợp. |
+| **Iteration** | Có inpainting, pose transfer, cleanup, retargeting hay workflow graph không? | Cần phân tách generator step với deterministic remediation. |
+| **Automation** | Có API, SDK, MCP, batch/job status hoặc entity state không? | Cần provider-neutral adapter/receipt trước khi tích hợp API. |
+| **Governance** | Có source/license, moderation, human review hoặc policy boundary không? | Provenance/evidence không được suy diễn thành approval. |
+
+## 2. Các tool tiêu biểu và cách chúng dựng pipeline
+
+### 2.1. PixelLab AI: pipeline 2D pixel-art hướng character/sprite/map
+
+PixelLab là ví dụ sát nhất với asset pipeline 2D game. Bề mặt sản phẩm tách one-click animation, skeleton animation, animation bằng mô tả text, directional rotation, inpainting, scenes, tilesets và UI assets. Các action như walk, run và attack được định vị là sprite animation; đây là điểm mạnh vì tool không gộp character, motion và environment vào một thao tác mơ hồ. [1] [4]
+
+Tài liệu API cho thấy một pipeline có cấu trúc hơn phần giao diện: image generation và editing, text animation, animation với start/end frame tùy chọn, skeleton estimation/animation, character animation, animation editing, interpolation, outfit transfer, map/tileset và trạng thái character/object có thể tái sử dụng. API còn công bố một số control thực dụng như output transparent, palette cưỡng bức, init image, inpainting, direction/view, số frame và giới hạn canvas. [2]
+
+Đặc biệt, hướng dẫn style consistency dùng một hoặc nhiều reference image, sinh biến thể, và ràng buộc đầu ra bằng geometry tham chiếu. Nó minh họa rằng consistency hữu ích không chỉ là prompt wording; nó là **reference-conditioned generation có control geometry**. [3]
+
+| PixelLab làm tốt | Điều không nên suy diễn | Bài học triển khai cho MotionLoom |
+|---|---|---|
+| Tách style, state, character, motion, rotation, map và inpainting thành operation riêng. [1] [2] | Output nhìn đồng nhất không chứng minh pivot, bbox, loop seam, socket hay atlas không contamination. | Nhận từng operation như một artifact stage; chạy identity/action-set/frame/atlas/map contracts sau generation. |
+| Có text/skeleton/start-end-frame controls và state có thể tái dùng. [2] | Không có bằng chứng công khai trong nguồn đã xem về deterministic replay hoặc runtime-ready export cho mọi artifact. | Lưu `generation-receipt`, `control-track` và hash cho input/output; render trong runtime target thay vì tin preview provider. |
+| Có reference/style, palette và transparent output. [2] [3] | Style reference không tạo ra artist authority hoặc production approval. | Bind reference/license/origin vào provenance, giữ `ai_generated` ở runtime-ready cho đến human review. |
+
+### 2.2. Runway và Luma: reference-conditioned video, continuity ở cấp shot
+
+Runway Gen-4 mô tả workflow dùng visual references cùng instruction để giữ character, location, object, style, mood và cinematographic elements qua scenes/perspectives mà không cần fine-tuning riêng. [5] Điều có thể học không phải là tin vào “consistent video”, mà là đưa **reference bundle** thành input độc lập của scene, thay vì viết lại prompt character ở mỗi shot.
+
+Luma Ray nhấn mạnh multi-keyframe, Modify Video và control Motion/Structure; bề mặt sản phẩm cũng nêu các câu hỏi về actor/performance preservation, lip-sync, source frame rate và số keyframe. [8] Đây là kiến trúc tách **performance/motion structure** khỏi **appearance transformation**, phù hợp cho video/cinematic asset nhưng không trực tiếp tạo ra sprite hoặc rig game-ready.
+
+| Điểm học được | Áp dụng chính xác vào MotionLoom | Giới hạn cần giữ |
+|---|---|---|
+| Reference bundle để tái dùng identity/cinematic direction. [5] | Thêm `reference_bundle` có hash, role và scope vào generation receipt/motion spec. | Không đánh đồng subject consistency trong video với frame geometry hoặc collision/sockets. |
+| Start/end/multi-keyframe và structure-conditioned editing. [8] | Ghi keyframe source, timestamps, expected pose/camera và seam vào action-set. | Keyframe chỉ là intent; phải render và đo artifact trả về. |
+| Source video có thể truyền performance/camera. [8] | Lưu source type và source hash, tách motion channel/camera channel/appearance channel. | Cần license, consent và provenance riêng cho footage/person performance. |
+
+### 2.3. DeepMotion, Rokoko, Cascadeur và Kinetix: body motion phải đi qua rig/retarget/edit
+
+DeepMotion tách SayMotion (text-to-3D animation) và Animate 3D (video-to-3D animation), đồng thời có bề mặt API cho Animate 3D. [6] Rokoko Vision trình bày rõ workflow upload video, tạo 3D motion, chỉnh sửa/xem/loop capture trong Rokoko Studio, upload character để retarget, rồi export FBX/BVH cho Blender, Unity và Unreal. [7] Cả hai cho thấy source acquisition là một bước riêng, không phải substitute cho target-rig acceptance.
+
+Cascadeur có cách mô tả đáng học về ranh giới AI. Tool này phân biệt AutoPosing, Inbetweening, AutoInterpolation và Video Mocap là ML-based; AutoPhysics, Ragdoll, Unbaking và motion cleaning là deterministic/non-ML tools. Inbetweening dựa trên pose, timing, số keyframe và style; video mocap đưa pose từ actor video vào character rig. Cascadeur nói rõ AI hỗ trợ quy trình animator thay vì thay thế animator. [10]
+
+Kinetix đưa video-to-animation vào bối cảnh vận hành game thông qua Unity Muse, Emote Creator trong OVERDARE và công nghệ AI animation cho Adobe Mixamo; trang sản phẩm cũng nêu moderation ở flow player-generated emotes. [11] Đây là nhắc nhở rằng reusable in-game motion cần integration và governance, không dừng ở clip được tạo.
+
+| Flow 3D đúng | Artifact bắt buộc nên có | Khoảng trống thường gặp nếu chỉ dùng AI output |
+|---|---|---|
+| Text/video performance → pose/motion inference → cleanup/loop → retarget → export → engine/runtime test. [6] [7] [10] | Source receipt, rig fingerprint, joint map, contact/foot-lock observations, action/event mapping, export manifest và runtime telemetry. | Foot sliding, missing joints, handedness/axis mismatch, bad root motion, event/socket mismatch và sự khác nhau giữa skeleton/mesh. |
+| AI pose/inbetweening → physics/cleanup → animator edit. [10] | Keyframe intent, generated segment, edit history và deterministic validation report. | Heuristic model score không chứng minh motion đã phù hợp gameplay hoặc review. |
+| Game/UGC integration → moderation/review. [11] | Candidate identity, policy result, user review, expiry và exact asset hash. | Moderation provider không thể thay user acceptance hoặc production approval. |
+
+### 2.4. Scenario: workflow graph, custom style và orchestration
+
+Scenario khác các generator đơn tuyến vì đặt image, video, audio và 3D vào một creative infrastructure. Trang chính thức mô tả custom model từ 5–100 reference image, custom LoRA, style/brand guidance; đồng thời có visual workflow builder, Node Agent, batch generation, reusable template, API và MCP. Các workflow public có cả component isolation, pose transfer, 2D rigging sheet, 3D auto-rigging và concept-to-game-ready-3D. [9]
+
+Điểm đáng học là **workflow-as-a-product**: một asset không chỉ có final PNG mà có graph tạo ra nó. Tuy vậy, Scenario không thay thế kiểm tra artifact của MotionLoom. Một LoRA hay template có thể giữ style, nhưng không tự chứng minh state/action/sprite geometry phù hợp runtime.
+
+## 3. Bản đồ pipeline hợp nhất
+
+Các tool trên sử dụng model khác nhau, nhưng pipeline tốt nhất hội tụ về cùng một chuỗi. MotionLoom nên dùng chuỗi này như một adapter boundary có thể tái sử dụng, thay vì bị khóa vào PixelLab, Runway hay một provider riêng.
+
+```text
+Project context / asset intent
+          ↓
+Reference bundle + identity/style controls
+          ↓
+Generation request (text / image / pose / skeleton / video)
+          ↓
+Provider result + immutable generation receipt
+          ↓
+Technical export normalization (frames / atlas / rig / FBX-BVH / video)
+          ↓
+Deterministic compiler (hash, geometry, seams, rig/socket, bounds)
+          ↓
+Target runtime render + telemetry + 0/50/100 evidence
+          ↓
+Dev Lab human review → explicit fix or explicit PR confirmation
+```
+
+| Lớp pipeline | Tool market thường cung cấp | MotionLoom hiện có | Kết luận |
+|---|---|---|---|
+| Project-aware intent | Variable; thường là prompt/workflow tại provider. | Project Context, durable Memory và Motion Spec. | **MotionLoom mạnh hơn** ở context/decision continuity giữa task. |
+| Reference/style | PixelLab, Runway, Scenario đưa reference/style thành control rõ ràng. [2] [3] [5] [9] | Identity/provenance contracts nhưng chưa có provider-neutral generation receipt chuẩn hóa public. | **Khoảng trống ưu tiên cao.** |
+| Motion construction | PixelLab skeleton/text animation; Luma keyframe; Cascadeur/DeepMotion/Rokoko mocap/inbetween/retarget. [2] [6] [7] [8] [10] | Motion Spec, action-set, body rig guidance và runtime adapters. | **Cần bridge rõ hơn** từ control track/rig output vào contracts. |
+| Geometry/packaging | Tool thường export/preview; mức chi tiết export khác nhau. | Frame Geometry, Atlas, Layered Map compiler và hash-based evidence. | **MotionLoom mạnh hơn** ở deterministic asset acceptance. |
+| Automation graph | Scenario có workflow/API/MCP; PixelLab/DeepMotion có API. [2] [6] [9] | CLI/Agent discovery, artifact bundle, report/handoff. | **Cần provider adapter layer**, không cần tự xây model. |
+| Runtime truth | Provider preview/engine integration khác nhau. | Runtimes thật, telemetry, visual truth, Dev Lab. | **MotionLoom mạnh hơn** ở runtime-bound review. |
+| Governance | Một số tool có moderation/training disclosure. [10] [11] | Source binding, tiered provenance, approval=false evidence, review-first PR gate. | **MotionLoom nên giữ nguyên lợi thế** và không nhận “approved” từ provider. |
+
+## 4. Các khoảng trống thực sự đáng đầu tư
+
+### 4.1. Provider-neutral generation receipt — ưu tiên 1
+
+Hiện MotionLoom đã có identity, provenance và consistency compiler, nhưng cần một artifact chuẩn hóa nằm **trước** export. Đề xuất `generation-receipt.schema.json` ghi provider, model/version khi provider công bố, request timestamp, control parameters, prompt hash (không cần lưu secret), seed nếu provider trả về, reference/input hashes, job ID, output hashes, declared license/source và capability limitations. Receipt không được cấp authority; nó chỉ làm bằng chứng truy nguyên generator step.
+
+**Acceptance criteria:** một fixture PixelLab-like, một video/mocap-like fixture và một offline adapter đều có thể ingest; receipt tamper hoặc output không khớp SHA-256 phải fail-closed; report phải trình bày receipt như evidence, không như approval.
+
+### 4.2. Control track và export normalization — ưu tiên 1
+
+`action-set` mô tả action/timing/seam tốt, nhưng cần bridge rõ ràng hơn với input điều khiển provider. Đề xuất `control-track.schema.json`: reference frame hashes, start/end/multi-keyframe, pose/skeleton reference, camera/direction track, intended action/event markers và source type. Song song, tạo `export-manifest.schema.json` cho frame sequence, sprite grid/atlas, 2D rig hoặc 3D file export.
+
+**Acceptance criteria:** importer không tự suy đoán grid/skeleton/axis. Khi metadata bị thiếu, trạng thái là `blocked` hoặc `needs_mapping`; khi đầy đủ, output được chuyển thành action-set/frame geometry/atlas hoặc rig contract có hash-bound links.
+
+### 4.3. 3D motion ingest và rig compatibility — ưu tiên 2
+
+Rokoko/DeepMotion/Cascadeur/Kinetix đều cho thấy video/text-to-motion chỉ là nửa đầu của quy trình. MotionLoom nên bổ sung `rig-compatibility` contract cho FBX/BVH/glTF ingest: coordinate system, unit scale, root, named joints, handedness, joint coverage, retarget mapping, root motion policy, contact markers, event/socket mapping. Đây là **contract + analyzer**, không phải một generator 3D mới.
+
+**Acceptance criteria:** fixture BVH/FBX tối giản hoặc metadata surrogate; missing named bone, duplicate joint map, axis mismatch, unbound weapon socket hoặc loop contact mismatch đều được báo chính xác; runtime adapter render candidate với telemetry 0/50/100.
+
+### 4.4. Adapter registry có capability/evidence — ưu tiên 2
+
+Không nên hard-code PixelLab/Runway/Scenario into core. Thay vào đó, thêm registry mô tả provider adapter: supported input controls, output kinds, replay guarantees, metadata availability, licensing fields, status `scaffold|verified`, and evidence requirements. Adapter chỉ được nâng `verified` sau cross-platform fixture, real export and runtime evidence. API credential phải ở connector/secret layer của project, không ở motion spec/receipt.
+
+**Acceptance criteria:** adapter `local-fixture` đạt verified trước; `pixellab` ban đầu là scaffold with documented import mapping; registry không cho quality gate suy diễn provider capability từ marketing claim.
+
+### 4.5. Dev Lab: source-to-runtime review rail — ưu tiên 3
+
+Dev Lab đã có evidence/review flow; bước kế tiếp là cho user thấy chuỗi generation receipt → controls → raw export → compiler results → runtime frame 0/50/100 trên một review rail. Mục tiêu là giảm vòng sửa “không rõ lỗi ở prompt, export hay runtime”, chứ không thêm dashboard trang trí.
+
+**Acceptance criteria:** mỗi candidate hiển thị hash-linked source/receipt, invalidation reason và failed contract; browser review vẫn yêu cầu decision từ user; UI không có nút tự-approve hoặc tự-mở PR.
+
+## 5. Đề xuất roadmap theo rủi ro thấp đến cao
+
+| Phase | Phạm vi | Giá trị | Điều kiện hoàn thành |
+|---|---|---|---|
+| **A — Artifact intake** | `generation-receipt`, `control-track`, `export-manifest`; offline fixtures; report binding. | Dùng được với mọi tool ngay cả khi không có API. | Schema + validator + tamper regressions + docs + npm package validation. |
+| **B — Provider bridge** | Adapter registry; importer `pixellab` ở mức metadata/export; local fixture adapter verified. | Có đường vào chuẩn mà không khóa vendor. | Capability registry, provider mapping tests, no-secret contract and failure states. |
+| **C — 3D motion bridge** | Rig compatibility, retarget map, FBX/BVH/glTF import evidence, runtime test. | Nối được mocap/AI body motion vào gameplay. | Cross-format fixtures, bone/socket/contact errors, runtime telemetry and Dev Lab review. |
+| **D — Review diagnosis** | Source-to-runtime Dev Lab rail, remediation label for failure layer. | Giảm iteration time và tăng khả năng sửa đúng chỗ. | User-tested review flow; no additional implicit approval side effect. |
+
+## 6. Những điều MotionLoom không nên sao chép
+
+MotionLoom không nên làm lại mô hình generation hay quảng cáo “consistent” dựa trên preview. Cũng không nên coi custom model, reference image, style lock, provider moderation, signed receipt hoặc quality score là proof rằng asset có license đủ, artist-authored, production-eligible hay production-approved. Các tool khảo sát truyền cảm hứng về **điều khiển** và **workflow granularity**; MotionLoom giữ vai trò kiểm chứng artifact, runtime truth và quyền quyết định của user.
+
+> Một integration chỉ đáng làm khi có thể trả lời rõ: artifact nào được tạo, hash nào ràng buộc nó, tool/provider cung cấp control nào, runtime nào đã render nó, lỗi nào được đo, và người dùng đã review candidate nào. Nếu thiếu một trong các câu này, nó là demo connector, chưa phải capability production.
+
+## 7. Khuyến nghị thực thi tiếp theo
+
+Nên bắt đầu **Phase A — Artifact intake** trước. Đây là phần độc lập provider, giữ đúng triết lý deterministic/artifact-first, tạo nền cho PixelLab, Scenario, Runway hay mocap tool mà không cần cấp API key hoặc biến MotionLoom thành generator. Sau Phase A, có thể chọn **PixelLab export importer** làm adapter đầu tiên vì nó khớp trực tiếp với asset identity, action-set, sprite/atlas và layered map compiler vừa hoàn thành.
+
+Không khuyến nghị gọi API của PixelLab hay bất kỳ provider nào ngay trong bước nghiên cứu. Integration API cần được thiết kế như một request riêng, đọc connector configuration trước, xác định rõ quyền truy cập/cost/terms, và bắt đầu ở trạng thái `scaffold` cho đến khi có evidence từ real export và target runtime.
+
+## References
+
+[1]: https://www.pixellab.ai/ "PixelLab — Official product page"
+[2]: https://www.pixellab.ai/pixellab-api "PixelLab API — Official API page"
+[3]: https://www.pixellab.ai/docs/tools/consistent-style "PixelLab — Consistent Style guide"
+[4]: https://www.pixellab.ai/docs/tools/animate-with-skeletons "PixelLab — Animate with Skeletons"
+[5]: https://runway.com/research/introducing-runway-gen-4 "Runway — Introducing Runway Gen-4"
+[6]: https://www.deepmotion.com/ "DeepMotion — Official product page"
+[7]: https://www.rokoko.com/products/vision "Rokoko Vision — Official product page"
+[8]: https://lumalabs.ai/ray "Luma Ray — Official product page"
+[9]: https://www.scenario.com/ "Scenario — Official platform page"
+[10]: https://cascadeur.com/help/category/285 "Cascadeur — Use Of AI Tools"
+[11]: https://kinetix.tech/ "Kinetix — Official product page"

package/docs/research/ai-pilot-ingest-notes.md

@@ -0,0 +1,29 @@
+# AI Pilot Ingest Notes
+
+## 2026-08-15 — ImageGen pilot asset capture
+
+The first generated robot master frame (`motionloom-ai-pilot-scout-idle.png`) contains an opaque dark background. It is therefore unsuitable as a frame-geometry source: treating its full canvas as subject pixels would conceal trim, padding, pivot, footline, and contamination issues.
+
+An isolated alpha-background variation (`motionloom-ai-pilot-scout-idle-alpha.png`) was generated from that master. It remains an **AI-generated pilot**, not artist-authored material and not a production-approved asset. Its final hash, dimensions, alpha bounds, consistency result, and Artifact Intake receipt must be measured from bytes before any ingest result is reported.
+
+Walk-cycle frames are handled independently under the same rule: no prompt claim, preview checkerboard, or intended transparency substitutes for actual PNG alpha/geometry measurement.
+
+## 2026-08-15 — Alpha-channel forensic correction
+
+The four files first named `*-alpha.png` were 8-bit RGB PNGs with no alpha channel. The subsequent `*-transparent.png` outputs were RGBA files, but every pixel still had alpha `255`: the dark scene background was painted into the pixels. The pilot builder now rejects both conditions rather than interpreting a filename, an RGBA color type, or a checkerboard preview as proof of isolated geometry.
+
+`scripts/isolate-alpha-background.py` was added as a narrow deterministic recovery step for an **edge-connected, visually reviewed flat background**. It publishes an input/output hash report and leaves `human_review_required: true`. A first idle-frame run at RGB Manhattan tolerance `24` left visible background bands, so it was rejected as unsuitable. Tolerance selection and visual inspection are material evidence; the tool must not turn an imperfect isolation into an approval or an assertion of provider-native alpha.
+
+The source-bound `build-ai-pilot.py` invocation against all four generated `*-transparent.png` files then failed before writing `controls.json`: `scout-idle.png has no transparent padding; an isolated alpha frame is required`. This is the intended boundary. There is no real pilot Artifact Intake report, consistency contract, runtime candidate, rig contract, or PR-ready result derived from these bytes. The Dev Lab card at `/lab?pilot=scout-alpha` presents that blocked evidence and disables review staging.
+
+## 2026-08-15 — V2 residual-artifact finding
+
+A successful edge-connected alpha-isolation report with `residual_edge_foreground_pixels: 0` is necessary but not sufficient. Visual review of the v2 isolated master exposed several detached horizontal opaque bands to the robot's right. Those pixels were not edge-connected and were therefore outside the isolator's intentionally narrow scope. The source remains unsuitable for ingest until a clean regeneration or a targeted visual edit removes the detached artifacts; a hash report alone is not a cleanliness approval.
+
+The independently generated v3 master initially appeared to repeat the same class of failure when its alpha PNG was shown on a black renderer background. A targeted edit successfully replaced its smoky/green background with a flat dark field, and the alpha-isolator produced a valid hash-bound report with zero residual edge pixels. A subsequent composite preview on a light field confirmed that the apparent long black bars were transparent pixels rendered against black, not canvas-spanning residue. The v3 master has clean padding and no detached macro artifact, so it may proceed as a review-required pilot source. Minor pixel-edge irregularities remain visible in the source and are deliberately not treated as production approval.
+
+## 2026-08-15 — Gemini-assisted pose generation checkpoint
+
+The authenticated Gemini browser session reached its upload menu. No source image has yet been transferred and no Gemini output is part of the pilot. Any later result must record Gemini provider/model/task metadata as `ai_generated`, then pass the existing alpha, geometry, contamination, hash-bound Intake, and review-required gates without exception.
+
+The Gemini upload menu can be displayed in the authenticated browser, but the initial automated menu selection did not expose a file input. This is recorded as a browser-integration state only; it did not transfer a source file or produce a generation.

package/examples/agent-consumer/ai-generated-pilot/hero-male.json

@@ -0,0 +1,10 @@
+{
+  "fixture": "ai-generated-pilot",
+  "asset_id": "hero-male-ai-pilot",
+  "framework": "body-rig",
+  "purpose": "Deterministic runtime-ingest fixture; not production art and not artist-authored.",
+  "bones": ["root", "pelvis", "chest", "head", "hand_r", "hand_l"],
+  "animations": ["idle", "attack", "hit", "death"],
+  "events": ["weapon_attach", "vfx_hit"],
+  "provenance_note": "This fixture demonstrates AI-generated origin and must remain outside production approval."
+}

package/examples/agent-consumer/ai-generated-pilot-provenance.json

@@ -0,0 +1,55 @@
+{
+  "schema_version": "1.0",
+  "provenance_id": "hero-male-ai-pilot-provenance",
+  "task_id": "mission-1.17.5-ai-pilot",
+  "scene": "hero-male-ai-pilot",
+  "created_at": "2026-08-14T00:00:00Z",
+  "asset": {
+    "id": "hero-male-ai-pilot",
+    "path": "hero-male.json",
+    "type": "runtime-pilot",
+    "framework": "body-rig",
+    "version": "0.1.0"
+  },
+  "authority": "ai_generated",
+  "readiness": "runtime_ready",
+  "generator": {
+    "model": "declared-by-agent-at-generation-time",
+    "task_id": "mission-1.17.5-ai-pilot",
+    "source": "agent-created-pilot",
+    "generated_at": "2026-08-14T00:00:00Z",
+    "agent": "codex"
+  },
+  "license": {
+    "spdx": "UNLICENSED",
+    "source": "internal-generation",
+    "attribution": "Generated pilot retained for runtime testing; production distribution requires a separate rights decision."
+  },
+  "files": [
+    {
+      "path": "hero-male.json",
+      "role": "runtime-pilot",
+      "sha256": "fc723dce3005fb2d16fe6df2e20a116f361b2b2b82b4aff7045c186c55190c27"
+    }
+  ],
+  "provenance_chain": [
+    {
+      "step": "generate",
+      "actor": "agent:codex",
+      "source": "agent-created-pilot",
+      "timestamp": "2026-08-14T00:00:00Z"
+    },
+    {
+      "step": "runtime-test",
+      "actor": "runtime:motionloom",
+      "source": "internal-runtime-evidence",
+      "timestamp": "2026-08-14T00:00:00Z"
+    }
+  ],
+  "runtime_evidence": {
+    "status": "pass",
+    "runtime": "motionloom-body-rig-runtime",
+    "tested_at": "2026-08-14T00:00:00Z",
+    "evidence_path": "runtime-evidence.json"
+  }
+}

package/examples/agent-consumer/ai-pilot-scout/CHATGPT-HANDOFF.md

@@ -0,0 +1,70 @@
+# ChatGPT handoff — Scout v3 walk sources
+
+## Cách dùng
+
+1. Mở một cuộc trò chuyện ChatGPT mới và upload file **`motionloom-ai-pilot-scout-v3-idle-alpha.png`**.
+2. Gửi **khối nền tảng** bên dưới, sau đó gửi **mỗi pose ở một tin nhắn riêng**. Không yêu cầu ChatGPT làm contact sheet hoặc tạo cả ba trong cùng một ảnh.
+3. Khi một pose đã hoàn tất, tải **file PNG gốc** do ChatGPT trả về. Không dùng screenshot, không flatten lên nền đen và không tự resize/crop/pad file.
+4. Đổi tên file tải về đúng tên dưới từng pose, rồi gửi lại ba file PNG gốc cùng URL hoặc ID cuộc trò chuyện ChatGPT nếu hiển thị.
+
+> Đây là source `ai_generated` cho pilot review. Nó không phải asset `artist_authored`, không được suy diễn license, và không thay thế human production approval.
+
+## Khối nền tảng — gửi một lần trước pose đầu tiên
+
+```text
+The attached file motionloom-ai-pilot-scout-v3-idle-alpha.png is the locked visual identity reference for one review-only MotionLoom pilot. Treat it as a source reference, not as a request to redesign the character.
+
+For every requested pose, produce exactly ONE separate, complete 2D pixel-art robot scout source sprite. Preserve the same cream, orange, black, and cyan palette; head shape; antenna; face; shoulder pads; torso; hands; feet; pixel density; crisp outlines; apparent scale; camera; and left-to-right orientation. Only change the limb pose required by the named walk phase.
+
+Output requirements are mandatory:
+- transparent RGBA PNG source, exactly 1920 × 1920 pixels;
+- exactly one isolated character, no duplicate, no crop, no text, no caption, no UI, no frame, no prop;
+- no black, white, checkerboard, coloured, textured, or gradient background;
+- no floor, contact shadow, cast shadow, glow, particles, smoke, dust, reflection, or stray bands;
+- hard crisp pixel-art edges: no blur, no feathering, no anti-aliased halo;
+- approximately 800 px visible character width and 1450 px visible character height;
+- centered near x=940; leave at least 120 px of fully transparent empty padding on each of the four edges;
+- the lowest opaque sole pixels must align near y=1626, with both feet fully inside the canvas.
+
+Do not zoom, crop, mirror, rotate, recolor, restyle, add accessories, alter the character scale, or generate a pose sheet. If you cannot preserve the transparent 1920 × 1920 source canvas and the required empty padding, say so instead of silently changing those requirements.
+```
+
+## Pose 1 — contact right
+
+```text
+Create pose `contact-right` now. This is the forward contact phase of a left-to-right walk cycle: the RIGHT foot is planted forward on the shared footline near y=1626; the LEFT leg trails naturally behind; arms counter-swing; torso stays upright. It must be a distinct walk action pose, not an idle variation. Return one transparent PNG source only.
+```
+
+Rename the downloaded original file to:
+
+```text
+motionloom-ai-pilot-scout-v3-chatgpt-contact-right.png
+```
+
+## Pose 2 — passing
+
+```text
+Using the same locked attached Scout v3 reference and the same output geometry, create pose `passing` now. This is the passing phase of the same left-to-right walk cycle: one leg passes beneath the upright body; stride is compact and balanced; both feet remain fully visible and inside the canvas; arms counter-swing. It must be a distinct walk action pose, not an idle variation. Return one transparent PNG source only.
+```
+
+Rename the downloaded original file to:
+
+```text
+motionloom-ai-pilot-scout-v3-chatgpt-passing.png
+```
+
+## Pose 3 — contact left
+
+```text
+Using the same locked attached Scout v3 reference and the same output geometry, create pose `contact-left` now. This is the complementary forward contact phase of the same left-to-right walk cycle: the LEFT foot is planted forward on the shared footline near y=1626; the RIGHT leg trails naturally behind; arms counter-swing. Do not mirror or redesign contact-right; preserve the locked visual identity and make this a distinct walk action pose. Return one transparent PNG source only.
+```
+
+Rename the downloaded original file to:
+
+```text
+motionloom-ai-pilot-scout-v3-chatgpt-contact-left.png
+```
+
+## Khi gửi output lại
+
+Gửi ba file PNG nguyên gốc theo đúng tên, không zip nếu giao diện có thể upload trực tiếp. Nếu ChatGPT hiển thị một conversation URL, task ID, hoặc thời điểm tạo, gửi kèm thông tin đó. MotionLoom sẽ tự đo alpha, geometry, padding, footline, contamination, identity drift và SHA-256; prompt không tự cấp intake, runtime candidate hay approval.

package/examples/agent-consumer/ai-pilot-scout/CODEX-HANDOFF.md

@@ -0,0 +1,80 @@
+# Codex handoff — Scout v3 walk sources
+
+## Mục tiêu và ranh giới
+
+Bạn đang hỗ trợ tạo **ba source sprite AI độc lập** cho review-only pilot của MotionLoom. Đây là việc tạo **source bytes mới**, không phải post-process các file ChatGPT đã bị reject. Dùng capability tạo ảnh mà môi trường Codex thực sự có; nếu không có capability đó, hãy dừng và báo rõ blocker thay vì tạo placeholder, screenshot hoặc PNG giả.
+
+Mọi output phải giữ `authority: ai_generated`. Không được gắn `artist_authored`, `production_eligible`, `production_approved`, license suy diễn hoặc runtime approval.
+
+## Reference bắt buộc
+
+Dùng file sau làm **khóa nhận diện**, không redesign:
+
+```text
+motionloom-ai-pilot-scout-v3-idle-alpha.png
+```
+
+Nếu file reference chưa có trong workspace Codex, yêu cầu người dùng upload/copy đúng file trước khi tạo bất kỳ pose nào.
+
+## Cách thực hiện bắt buộc
+
+1. Tạo **mỗi pose trong một request/image riêng**. Không làm contact sheet, sprite sheet hoặc ba nhân vật trong một canvas.
+2. Mỗi lần tạo phải yêu cầu renderer trả **PNG RGBA gốc 1920 × 1920**. Đây là kích thước source, không được tạo 1254×1254 rồi resize/canvas-pad sau đó.
+3. Lưu nguyên bytes gốc, không crop, resize, pad, alpha-isolate, flatten, screenshot hoặc tối ưu lại file để bypass gate.
+4. Trả ba PNG và metadata có thể biết được: provider/tool, model (nếu UI hiển thị), request/task/conversation ID hoặc URL, timestamp và prompt cuối cùng. Nếu metadata không tồn tại, nói rõ là `not exported`; không bịa receipt.
+5. Sau khi trả output, để MotionLoom chạy preflight độc lập. Codex không tự chạy Artifact Intake, không cấp runtime candidate, không mở PR và không tự phê duyệt.
+
+> **Failure policy:** Nếu tool không bảo toàn canvas 1920×1920 RGBA với empty padding yêu cầu, trả `blocked` cùng thông tin tool đã dùng. Không sửa bytes có sẵn để làm pass.
+
+## Capability preflight — bắt buộc trước ba pose
+
+Chỉ tạo thử **`contact-right` trước**. Ngay sau khi công cụ trả file gốc, kiểm tra metadata/bytes thực tế trước khi tạo `passing` hoặc `contact-left`:
+
+| Điều kiện | Kết quả cần có | Khi fail |
+|---|---|---|
+| Canvas | `1920 × 1920` | Dừng; không tạo hai pose còn lại. |
+| Color mode | `RGBA` với alpha thật | Dừng nếu nhận `RGB` hoặc alpha bị flatten. |
+| Background | Các pixel ngoài nhân vật trong suốt thật | Dừng nếu nền đen, trắng, caro hoặc grid bị rasterize. |
+| Export semantics | File gốc, không screenshot hay preview | Dừng nếu tool chỉ cho preview không có PNG source. |
+
+> Lần thử Codex `exec-6c962cac-7e7f-491b-b0a8-e7c4ee7d2412` đã trả 1254×1254 RGB với checkerboard rasterized. Đó là **giới hạn exporter đã quan sát**, không phải lỗi cần chữa bằng resize, alpha isolate hoặc canvas padding. Chỉ thử lại khi capability khác có thể xuất PNG RGBA 1920×1920 gốc.
+
+## Prompt nền tảng cho image-generation capability
+
+Gửi nguyên khối sau cùng master reference. Giữ nguyên tiếng Anh để công cụ tạo ảnh diễn giải hình học chính xác hơn.
+
+```text
+The attached file motionloom-ai-pilot-scout-v3-idle-alpha.png is the locked visual identity reference for one review-only MotionLoom pilot. Treat it as a source reference, not as a request to redesign the character.
+
+Create exactly ONE separate, complete 2D pixel-art robot scout source sprite for the named walk pose. Preserve the same cream, orange, black, and cyan palette; head shape; antenna; face; shoulder pads; torso; hands; feet; pixel density; crisp outlines; apparent scale; camera; and left-to-right orientation. Only change the limb pose required by the named walk phase.
+
+Mandatory source geometry:
+- original transparent RGBA PNG, exactly 1920 × 1920 pixels;
+- one isolated character only; no duplicate, no crop, no text, no caption, no UI, no frame, no prop;
+- no black, white, checkerboard, coloured, textured or gradient background;
+- no floor, contact shadow, cast shadow, glow, particles, smoke, dust, reflection or stray bands;
+- hard crisp pixel-art edges; no blur, feathering or anti-aliased halo;
+- approximately 800 px visible character width and 1450 px visible character height;
+- centered near x=940; at least 120 px of fully transparent empty padding on every edge;
+- lowest opaque sole pixels aligned near y=1626, with both feet fully inside the canvas.
+
+Do not zoom, crop, mirror, rotate, recolor, restyle, add accessories, alter character scale or generate a pose sheet. If you cannot preserve the transparent 1920 × 1920 source canvas and required empty padding, report failure instead of silently changing requirements.
+```
+
+## Ba pose cần tạo
+
+Sau khối nền tảng, tạo lần lượt từng pose bằng một request riêng.
+
+| Pose | Prompt bổ sung | Tên file output bắt buộc |
+|---|---|---|
+| `contact-right` | `Create pose contact-right now. This is the forward contact phase of a left-to-right walk cycle: the RIGHT foot is planted forward on the shared footline near y=1626; the LEFT leg trails naturally behind; arms counter-swing; torso stays upright. Return one transparent PNG source only.` | `motionloom-ai-pilot-scout-v3-codex-contact-right.png` |
+| `passing` | `Using the same locked reference and output geometry, create pose passing now. One leg passes beneath the upright body; stride is compact and balanced; both feet remain fully visible inside the canvas; arms counter-swing. Return one transparent PNG source only.` | `motionloom-ai-pilot-scout-v3-codex-passing.png` |
+| `contact-left` | `Using the same locked reference and output geometry, create pose contact-left now. The LEFT foot is planted forward on the shared footline near y=1626; the RIGHT leg trails naturally behind; arms counter-swing. Do not mirror or redesign contact-right. Return one transparent PNG source only.` | `motionloom-ai-pilot-scout-v3-codex-contact-left.png` |
+
+## Handoff lại MotionLoom
+
+Gửi nguyên ba PNG theo đúng tên cùng metadata đã xuất được. MotionLoom sẽ ghi provider trung thực (ví dụ capability/tool thực tế mà Codex đã dùng), tính SHA-256 và đo alpha, canvas, subject bounds, padding, footline, contamination và identity. Chỉ khi bốn frame — master v3 và ba pose — pass, pipeline mới được phép chạy:
+
+```text
+build-ai-pilot → Artifact Intake → consistency → runtime candidate → runtime render → Dev Lab review-first
+```