motionloom 2.3.0 → 2.5.0

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/docs/research/ai-repository-benchmark-2026-08-16.md

@@ -0,0 +1,75 @@
+# AI Repository Benchmark — research ledger
+
+**Ngày bắt đầu:** 2026-08-16
+**Phạm vi:** Các repository/tool AI công khai có bài học workflow, packaging hoặc runtime verification có thể đánh giá cho MotionLoom. Đây không phải là danh sách khuyến nghị tích hợp dependency.
+
+## Phương pháp
+
+Mỗi candidate được kiểm tra qua nguồn chính thức, README/license, yêu cầu triển khai, bề mặt security và mức độ phù hợp với invariant MotionLoom. Star count chỉ là tín hiệu phụ; không dùng làm bằng chứng chất lượng hay an toàn. Không thực thi code bên thứ ba trong đợt nghiên cứu này.
+
+## Phát hiện ban đầu
+
+| Candidate | Nhóm | Điều nguồn chính thức xác nhận | Bài học tiềm năng cho MotionLoom | Rủi ro/không sao chép |
+|---|---|---|---|---|
+| [Coze Studio](https://github.com/coze-dev/coze-studio) | Agent workflow | Công cụ phát triển agent all-in-one với prompt, RAG, plugin, workflow; có templates, low/no-code canvas, API/SDK và self-host qua Docker Compose. README cảnh báo rõ public deployment có bề mặt registration, Python workflow execution, SSRF và API privilege risks. License Apache-2.0. | Progressive disclosure: quick setup, sau đó mới model/plugin/workflow configuration. Hiển thị explicit security posture bên cạnh workflow launch. | Không áp dụng visual canvas như authority; MotionLoom phải giữ artifact identity, runtime evidence và user review là nguồn truth. Không gọi code execution node tùy ý từ app/Dev Lab. |
+| [Dify](https://github.com/langgenius/dify) | Agent workflow | Nền tảng app LLM có workflow, RAG, agents, model management, observability và APIs; quick start rõ ràng qua Docker Compose; mô tả environment/config separation. License là Dify Open Source License dựa trên Apache-2.0 với điều kiện bổ sung. | Onboarding theo tầng: cài nhanh, dashboard init, cấu hình môi trường rõ; observability là bề mặt sản phẩm chứ không phải log ẩn. | Không sao chép license/model hosting approach; không dùng dashboard telemetry làm bằng chứng production approval. Không mở mơ hồ các provider credential vào repository. |
+| [ComfyUI](https://github.com/Comfy-Org/ComfyUI) và [workflow templates](https://github.com/Comfy-Org/workflow_templates) | Visual workflow | Node graph cho image/video/audio/3D/text; JSON save/load workflows, reusable subgraphs, templates, local API, App Mode và khả năng recover workflow/seed từ media được hỗ trợ. Repo template dùng manifest regenerated với SHA-256 mismatch gate; production chỉ deploy workflow có `status: approved`, preview có thể hiển thị trạng thái khác. | Đưa `approved/rejected/deprecated` vào index workflow/template, bắt buộc manifest hash và expose một review surface giản lược cho end user thay vì tất cả graph controls. | Không xem JSON graph/seed là provenance hoặc runtime evidence. Không nhận custom-node metadata như source tin cậy; mọi external template phải qua intake và identity binding của MotionLoom. |
+| [Wan2.1](https://github.com/Wan-Video/Wan2.1) | Video generation | Model suite hỗ trợ T2V, I2V, FLF2V, editing/VACE; README công bố rõ task/resolution/model và links checkpoint. Có integration Diffusers/ComfyUI và nêu ràng buộc VRAM, resolution stability, model-specific prompt guidance. | `generation-profile` phải tách task/model/resolution/frames/provider; lấy capability, hardware expectation và model/checkpoint identity thành evidence thay vì claim chung chung “AI video generated”. | Không tích hợp model runtime vào MotionLoom core và không suy diễn quality từ model name. Kết quả video/pose từ bất kỳ provider nào vẫn là `ai_generated`, cần geometry/consistency/runtime review. |
+| [HunyuanVideo](https://github.com/Tencent-Hunyuan/HunyuanVideo) | Video/human animation | Cung cấp inference/weights, I2V, Avatar, custom generation, benchmark và các integration. README ghi rõ dependency CUDA/Linux, memory requirement cao và phạm vi environment đã test. | Cần consumer-facing capability card: platform, runtime, GPU/memory, tested environment, source model/version và failure mode trước khi Agent đề xuất một generation route. | Không hứa “one-click” nếu phần cứng/OS không đáp ứng. Không dùng self-reported benchmark để thay runtime verification hay human approval. |
+| [Xinference](https://github.com/xorbitsai/inference) | Local model serving | Model server self-hosted cho language, speech và multimodal; có OpenAI-compatible REST, RPC, CLI, WebUI, Docker/Kubernetes examples và thể hiện rõ CPU/Metal/GPU/distributed capabilities. README có migration notes cho breaking change. | Đăng ký **capability card** và compatibility/migration note theo adapter version; Agent chỉ đề xuất provider/runtime đã thỏa platform, hardware, credential và health-check profile. | MotionLoom không trở thành model server, không mở endpoint model nội bộ ra artifact/Dev Lab, không tự chạy Docker/model download từ brief người dùng. |
+| [ModelScope](https://github.com/modelscope/modelscope) | Model registry / MaaS | Unified abstraction cho inference, training, evaluation, export, deployment; model/dataset hub, version/cache management, modular task pipeline và Docker images theo CPU/GPU. README cũng nêu dependency/OS incompatibilities của một số model. | Tách **identity** (provider/model/checkpoint/version/license) khỏi **capability** (task, input constraints, platform, hardware, known limitations), và fail closed khi metadata tối thiểu thiếu. | Không coi registry listing là license/provenance đã xác minh, không nhận “few lines to run” là bằng chứng reproducibility hoặc cross-platform support. |
+| [CogVideo](https://github.com/zai-org/CogVideo) | Video generation | README công bố task T2V/I2V/continuation, model task matrix, resolution/frame divisibility, precision, VRAM/timing benchmark, requirement Python và model-specific license notes. Nó cũng nêu prompt optimization và external model dependence. | Mở rộng `generation-profile` thành matrix bắt buộc: task, model/checkpoint, resolution, frame formula, precision, expected VRAM/time, prompt-transform provider và source URLs. | Không chuyển benchmark tự công bố thành SLA; không biến prompt enhancement bởi external LLM thành `artist_authored` hoặc ẩn provider ở provenance. |
+
+## Metadata GitHub tại thời điểm khảo sát
+
+Snapshot dưới đây được lấy bằng GitHub CLI lúc **2026-08-16**. Nó chỉ là tín hiệu maintenance/community, không phải chứng nhận security, chất lượng hay tính phù hợp để tích hợp.
+
+| Repository | Stars / forks | License GitHub nhận diện | Cập nhật gần nhất lúc khảo sát | Kết luận sàng lọc |
+|---|---:|---|---|---|
+| `coze-dev/coze-studio` | 21,453 / 3,117 | Apache-2.0 | 2026-08-16 | Mature reference cho progressive onboarding và self-host security posture. Không là dependency candidate. |
+| `langgenius/dify` | 152,585 / 24,091 | Other (Dify Open Source License) | 2026-08-16 | Reference tốt cho product observability; cần tránh mọi code/license reuse. |
+| `Comfy-Org/ComfyUI` | 127,883 / 15,057 | GPL-3.0 | 2026-08-16 | Reference tốt cho workflow packaging/manifest; không phù hợp để import code vào package MotionLoom. |
+| `Wan-Video/Wan2.1` | 16,833 / 3,364 | Apache-2.0 | 2026-08-16 | Reference cho generation task/capability matrix và điều kiện runtime. |
+| `Tencent-Hunyuan/HunyuanVideo` | 12,429 / 1,312 | Other | 2026-08-16 | Reference cho disclosure GPU/environment; license và model terms cần review theo từng checkpoint. |
+| `zai-org/CogVideo` | 12,956 / 1,326 | Apache-2.0 | 2026-08-16 | Reference cho matrix resolution/frames/precision/VRAM; không coi benchmark là SLA. |
+| `xorbitsai/inference` | 9,500 / 858 | Apache-2.0 | 2026-08-16 | Reference cho adapter capability/health-check/migration policy; không biến MotionLoom thành model server. |
+| `modelscope/modelscope` | 9,091 / 961 | Apache-2.0 | 2026-08-16 | Reference cho tách model identity khỏi capability; registry listing không thay provenance. |
+
+## Decision log sơ bộ
+
+| Pattern | Quyết định | Lý do và guardrail MotionLoom |
+|---|---|---|
+| Quick start theo tầng, chỉ mở gate chuyên sâu khi cần | **Áp dụng ngay** | Phù hợp onboarding một-lệnh hiện có; deep gates vẫn fail-closed và không bị ẩn khỏi artifact. |
+| Runtime capability card có adapter/platform/constraint/evidence | **Đã triển khai** | `motionloom capability card --format json` xuất projection chỉ đọc từ registry đã validate; không làm thay provenance, runtime evidence hoặc selection. |
+| Generation profile có model/checkpoint/platform/hardware/constraint | **Hoãn có gate** | Bổ sung thông tin quyết định cho Agent trước khi gọi provider chỉ sau khi có schema, validator, provenance binding và regression; không mở provider credential trong core. |
+| Hash-bound workflow/template manifest và trạng thái `approved/rejected/deprecated` | **Thí nghiệm có gate** | Chỉ áp dụng cho profile/template nội bộ sau khi có schema, validator và regression; không đồng nhất template approval với `production_approved`. |
+| Visual node canvas hoặc dashboard như execution authority | **Từ chối** | Làm mờ artifact identity và mở khả năng thực thi node tùy ý, trái mô hình deterministic review-first. |
+| Nhúng model server, tự tải model, hoặc provider credential vào MotionLoom core | **Từ chối** | Tăng bề mặt attack, chi phí vận hành và rủi ro secret; chỉ dùng adapter capability/card và explicit user setup. |
+| Tuyên bố generated asset “artist-authored” vì prompt/model tốt | **Từ chối** | Vi phạm provider-truthful provenance và human-governed production boundary. |
+
+## Cải tiến đã áp dụng
+
+Capability card được triển khai như một **projection chỉ đọc** trên `capability-registry.json`, không phải registry hay policy thứ hai. Lệnh `motionloom capability card --format json` xác thực hash evidence trước khi xuất `id`, declared status, adapter version, compatibility, thời điểm kiểm chứng, inputs/outputs, evidence reference, limitations, fallback, risk và side-effect level. Card luôn nhắc Agent gọi selection trước execution; selection mới áp dụng evidence freshness/integrity.
+
+| Hạng mục | Trạng thái | Cách kiểm chứng | Guardrail giữ nguyên |
+|---|---|---|---|
+| `motionloom capability card --format json` | Hoàn thành | Thử bằng registry repository thật và npm shortcut `pnpm intelligence:card` | Không chọn runtime, không refresh evidence, không tạo commit/PR. |
+| Validation registry trước export | Hoàn thành | Regression cố ý sửa SHA-256 evidence; card trả lỗi non-zero | Fail-closed khi evidence thiếu, sai hash hoặc thoát repository. |
+| Agent-facing CLI/help, npm script, agent-card, README | Hoàn thành | `pnpm docs:check`, CLI help và regression alias | Chỉ công bố discovery; không nâng `scaffold_only` thành `verified`. |
+| Generation profile model/checkpoint/hardware | Chưa triển khai | Chưa có schema hay validator | Không suy diễn provider/model identity; tiếp tục dùng provenance/intake hiện hữu. |
+| Hash-bound workflow/template recipe | Chưa triển khai | Cần schema riêng, approval-state vocabulary và test | Không đồng nhất template approval với `production_approved`. |
+
+Kết quả regression: `pnpm test` pass toàn bộ suite, bao gồm export card, alias CLI và rejection với evidence bị sửa. `pnpm docs:check` và `git diff --check` cũng pass. Không có dependency hay code bên thứ ba nào được thêm từ các repository khảo sát.
+
+## Nguồn
+
+1. [Coze Studio README và self-host/security guidance](https://github.com/coze-dev/coze-studio)
+2. [Dify README, self-hosting, observability và license notice](https://github.com/langgenius/dify)
+3. [Dify Cloud product overview](https://dify.ai/)
+4. [ComfyUI README: workflow JSON, API, App Mode và offline posture](https://github.com/Comfy-Org/ComfyUI)
+5. [ComfyUI workflow templates: manifest, SHA-256 validation và release filtering](https://github.com/Comfy-Org/workflow_templates)
+6. [Wan2.1 README: task matrix, integration và inference requirements](https://github.com/Wan-Video/Wan2.1)
+7. [HunyuanVideo README: model scope, hardware requirements và test environment](https://github.com/Tencent-Hunyuan/HunyuanVideo)
+8. [Xinference README: local serving, APIs, deployment và migration](https://github.com/xorbitsai/inference)
+9. [ModelScope README: MaaS abstraction, registry, pipeline và platform constraints](https://github.com/modelscope/modelscope)
+10. [CogVideo README: video task/memory matrix, precision, model scope và prompt guidance](https://github.com/zai-org/CogVideo)

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
+```

package/examples/agent-consumer/ai-pilot-scout/README.md

@@ -0,0 +1,39 @@
+# AI Scout Pilot Ingest
+
+This example is a **real-byte, local workspace flow** for an AI-generated four-frame scout robot pilot. The repository does not version the generated PNG bytes. Run the portable builder against four user-held, alpha-isolated PNG frames; it copies the source bytes into `.motionloom/pilots/ai-pilot-scout/`, measures the alpha geometry, and produces the JSON contracts there.
+
+The pilot uses `authority: ai_generated` and stays **review-required**. Its receipt is explicitly a post-hoc, hash-bound ingest record because a provider-native ImageGen receipt was not exported. The result may demonstrate that all bundle links and measured geometry validate. It must never be interpreted as artist-authored authority, provider provenance completeness, runtime verification, production eligibility, or human approval.
+
+If a provider returns a fully opaque dark canvas despite a transparency request, run `scripts/isolate-alpha-background.py` first only when the background is visibly high-contrast and edge-connected. It rejects residual opaque pixels at the canvas edge by default, because those normally indicate contamination instead of a safely isolated sprite. The tool emits an alpha-isolation report, but that report is evidence of a deterministic post-process, not proof of source alpha or approval. Review the result visually before building the bundle.
+
+```bash
+python3 scripts/build-ai-pilot.py \
+  --idle /absolute/path/scout-idle-transparent.png \
+  --contact-right /absolute/path/scout-contact-right-transparent.png \
+  --passing /absolute/path/scout-passing-transparent.png \
+  --contact-left /absolute/path/scout-contact-left-transparent.png \
+  --overwrite
+
+python3 scripts/artifact-intake.py report \
+  --root . \
+  --registry artifact-adapter-registry.json \
+  --controls .motionloom/pilots/ai-pilot-scout/controls.json \
+  --receipt .motionloom/pilots/ai-pilot-scout/receipt.json \
+  --export-manifest .motionloom/pilots/ai-pilot-scout/export.json \
+  --output .motionloom/pilots/ai-pilot-scout/artifact-intake-report.json
+
+python3 scripts/runtime-candidate.py report \
+  --root . \
+  --input .motionloom/pilots/ai-pilot-scout/candidate.json \
+  --output .motionloom/pilots/ai-pilot-scout/runtime-candidate-report.json
+```
+
+Use `--frame-url ID=URL` when the four frames are hosted for Dev Lab. The builder carries those URLs only in `devlab-pilot-evidence.json`; it does not treat URL reachability as evidence of quality, runtime behavior, review, or approval.
+
+> The builder rejects ordinary RGB files and a fully opaque image. A visible checkerboard painted into an RGB PNG is **not** transparency. This restriction makes frame geometry and contamination checks meaningful.
+
+When any source fails preflight, the builder exits non-zero and writes only `partial-handoff.json` beside the copied source bytes. That handoff binds the original SHA-256, any measurable alpha/canvas/padding metrics, provider identity and exact refusal reasons. It deliberately does **not** emit `controls.json`, a receipt, candidate, runtime render or Dev Lab review link. Replace the source independently; do not resample, add transparent margins or edit metadata to make rejected bytes pass.
+
+## Current pilot handoff
+
+The checked-in [`partial-handoff.json`](partial-handoff.json) records the current real-byte pilot boundary: one v3 master was alpha-isolated, visually checked and retained outside this repository; the independent walk phases could not be generated before the image quota was exhausted. No intake bundle, runtime candidate, render evidence or Dev Lab candidate has been emitted from a repeated idle image. Resume only with three independently generated and reviewed action frames, then run the exact commands above.

package/examples/agent-consumer/ai-pilot-scout/chatgpt-geometry-correction-prompt.md

@@ -0,0 +1,55 @@
+# ChatGPT corrective prompt — Scout v3 walk frames
+
+Upload **only** `motionloom-ai-pilot-scout-v3-idle-alpha.png` as the reference image. Generate each requested pose in a separate turn and download the original PNG, not a screenshot.
+
+> Treat the reference as a locked production-pilot sprite sheet source. Preserve the robot exactly; change only the limb pose required by the requested walk phase.
+
+## Non-negotiable output contract
+
+Copy this block into **every** generation request, then append one pose block below.
+
+```text
+Use the attached Scout v3 idle sprite as the exact visual and geometry reference.
+
+Create ONE complete 2D pixel-art character sprite on a 1920 × 1920 pixel canvas. The canvas background must be truly transparent (RGBA alpha 0), with no black, checkerboard, coloured, shadow, floor, glow, particles, text, border, duplicate character, crop, or prop.
+
+Do not redesign, restyle, zoom, crop, rotate, mirror, recolor, or change the camera. Keep the cream/orange/black/cyan robot identity, head, antenna, face, shoulder pads, torso, hands, feet, palette, pixel density, outlines, and apparent scale from the reference. Draw the entire robot at the same approximate scale as the reference, vertically standing on the same baseline.
+
+Geometry requirements: leave at least 120 px transparent padding on all four canvas edges. Keep the opaque character approximately 800 px wide by 1450 px tall, centered near x=940, with the feet baseline near y=1626. The character must not occupy more than 55% of canvas width. Use crisp hard pixel edges only; do not add anti-aliased blur.
+
+This is an AI-generated source asset for a review-only MotionLoom pilot. It must not imply artist authorship, production approval, runtime approval, or a licence.
+```
+
+## Pose 1 — contact right
+
+Append this after the contract:
+
+```text
+Pose: walk cycle contact-right. The robot’s RIGHT foot is planted forward at the baseline; the LEFT leg trails slightly behind. Counter-swing the arms naturally. Keep both feet fully visible and preserve the locked body scale and centered composition.
+
+Return only the single transparent-background PNG. Save it as: motionloom-ai-pilot-scout-v3-chatgpt-contact-right.png
+```
+
+## Pose 2 — passing
+
+Append this after the contract:
+
+```text
+Pose: walk cycle passing phase. One leg passes beneath the body with a compact, balanced gait; the body remains upright and the foot baseline stays near y=1626. Counter-swing the arms naturally. Keep both feet fully visible and preserve the locked body scale and centered composition.
+
+Return only the single transparent-background PNG. Save it as: motionloom-ai-pilot-scout-v3-chatgpt-passing.png
+```
+
+## Pose 3 — contact left
+
+Append this after the contract:
+
+```text
+Pose: walk cycle contact-left. The robot’s LEFT foot is planted forward at the baseline; the RIGHT leg trails slightly behind. This must be the complementary phase to contact-right, not a mirror/redesign. Counter-swing the arms naturally. Keep both feet fully visible and preserve the locked body scale and centered composition.
+
+Return only the single transparent-background PNG. Save it as: motionloom-ai-pilot-scout-v3-chatgpt-contact-left.png
+```
+
+## Before sending files back
+
+Do not flatten the PNG or put it on a black background. Send the three original downloaded files to MotionLoom in the order above and retain the ChatGPT conversation/task context if available. MotionLoom will measure alpha, padding, identity geometry and file hashes independently; satisfying the prompt does not approve the candidate.