motionloom 2.1.0 → 2.3.0

package/.agents/skills/motionloom/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: motionloom
+description: Load the canonical MotionLoom Skill from the repository root for project-aware animation production, runtime evidence, Dev Lab review and review-first PR handoff.
+---
+
+# MotionLoom Agent Skills surface
+
+This is a **portable discovery alias**, not a second copy of the Skill. Load the canonical [`SKILL.md`](../../../SKILL.md) from the repository root and use [`agent-card.json`](../../../agent-card.json) for machine-readable capabilities. Before using the Skill, run:
+
+```text
+motionloom discovery check --root <motionloom-checkout> --json
+```
+
+Keep the review boundary intact: a candidate may be rendered and reviewed, but approval is never inferred and a PR is never opened without explicit user confirmation.

package/.claude/skills/motionloom.md

@@ -0,0 +1,5 @@
+# MotionLoom for Claude Code
+
+Use MotionLoom when the task creates, fixes, validates, renders or hands off animation inside an existing project. Load the repository-root [`SKILL.md`](../../SKILL.md) as the canonical instruction source and [`agent-card.json`](../../agent-card.json) for capability discovery. Do not copy or fork the workflow into this file.
+
+Start with `motionloom discovery check --root <motionloom-checkout> --json`, then follow the required lifecycle: project context → source binding → runtime evidence → Dev Lab browser review → user-confirmed handoff. `approval` remains `false` until the user explicitly approves.

package/.codex/skills/motionloom.md

@@ -0,0 +1,11 @@
+# MotionLoom for Codex
+
+Use MotionLoom for project-aware animation work, including Lottie/dotLottie, Rive, GSAP, Framer Motion, body rigs and runtime-backed review. Load the canonical repository-root [`SKILL.md`](../../SKILL.md) and use [`agent-card.json`](../../agent-card.json) rather than duplicating instructions.
+
+Verify discovery first:
+
+```text
+motionloom discovery check --root <motionloom-checkout> --json
+```
+
+Always produce task-bound artifacts and runtime evidence, suggest/open the internal Dev Lab after rendering, report unresolved issues, and stop before commit/push/PR unless the user explicitly confirms.

package/AGENTS.md

@@ -0,0 +1,17 @@
+# MotionLoom Agent Router
+
+This repository exposes one canonical Agent Skill: [`SKILL.md`](SKILL.md). Load it when the task concerns animation production, motion design, asset binding, runtime rendering, Dev Lab review or PR handoff. Use [`agent-card.json`](agent-card.json) for machine-readable capabilities and [`agent-surfaces.json`](agent-surfaces.json) for installation/discovery compatibility.
+
+## First action
+
+Run the offline discovery check from the checkout root:
+
+```text
+motionloom discovery check --root . --json
+```
+
+Then follow the lifecycle in `SKILL.md`. The repository may coordinate Lottie, dotLottie, Rive, GSAP and Framer Motion, but it does not replace those runtimes. Render evidence, provenance, semantic checks and browser review are separate states. **Do not infer user approval from a passing heuristic, signature, screenshot or quality gate.**
+
+## Source of truth
+
+Do not duplicate or edit Agent-specific copies of the workflow. If this router conflicts with `SKILL.md`, the canonical root Skill and machine-readable schemas win. Use `references/agent-interoperability.md` for discovery details and `docs/AGENT-INTEGRATION.md` for installation examples.

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable MotionLoom changes are documented here. The project follows semantic versioning for the npm package and keeps major contract changes in dedicated release notes under [`docs/releases/`](docs/releases/).
 
+## [Unreleased]
+
+No unreleased changes are recorded.
+
+## [2.3.0] - 2026-08-14
+
+### Added
+
+- AI-first, human-governed asset provenance contract with explicit authority/origin tiers, readiness states, generator/derivation metadata, per-file SHA-256, license/source records, runtime evidence and human-review boundaries.
+- Cross-platform `motionloom asset-provenance` commands for validation, classification, reporting and runtime/production checks, plus a transparent AI-generated pilot fixture.
+- One-command `npx --yes motionloom setup` onboarding for real projects, with package-manager detection, local devDependency installation, project-bound context and durable Project Memory bootstrap.
+- Read-only `motionloom status`, safe `motionloom repair`, dry-run JSON output and an idempotent managed `AGENTS.md` router for Agent integration.
+- Canonical `npx` installation recipe in Agent discovery plus Ubuntu/macOS/Windows onboarding regressions and package/docs guards.
+
+### Fixed
+
+- Production quality and PR preflight now fail closed when an asset is unknown, self-asserted as artist-authored, not production-eligible or missing a manifest-bound provenance record; `production_approved` remains human-only.
+- Setup JSON output no longer mixes package-manager logs with machine-readable results, and repair/status routing does not trigger an unintended full setup.
+
+### Verified
+
+- Full regression, onboarding and installation-matrix tests, discovery contract, docs audit, Skill Doctor, skill-creator validation, quality validation, npm tarball dry-run and diff hygiene pass.
+
+### Boundary
+
+- Setup never commits, pushes, opens a PR, grants approval or promotes asset provenance. User review remains required before any PR handoff.
+
+## [2.2.0] - 2026-08-13
+
+### Added
+
+- Canonical Agent interoperability surfaces for `.agents/skills`, `.claude`, `.codex`, source discovery and cross-platform installation checks.
+- Consumer fixtures for Lottie/dotLottie, Rive, GSAP, Framer Motion, body rigs and multi-scene continuity.
+- Visual Truth Contract with frame hashes, runtime/source provenance, deterministic perceptual signals, region explanations and review-required semantics.
+- Append-only, hash-chained Remediation Learning ledger for user-confirmed outcomes, correction counts, first-pass acceptance, issue-class outliers and benchmark provenance.
+
+### Fixed
+
+- Quality CI now rebuilds the context-bound replay bundle after runtime, report and attestation artifacts are generated, preventing stale replay hashes from rejecting an otherwise valid changed-scene gate.
+
+### Verified
+
+- Mainline Quality, Documentation and Package Hygiene, and Security workflows pass on the replay-remediation commit.
+- The local release candidate passes the full regression, docs/Skill validation, runtime adapter, discovery, installation matrix, Visual Truth, Remediation Learning, attestation and npm tarball checks.
+
+### Boundary
+
+- This is a release candidate prepared from the green mainline. Remote tag creation, GitHub Release creation and npm publication remain explicit maintainer actions; evidence and heuristics never grant user approval.
+
 ## [2.1.0] - 2026-08-13
 
 ### Added
@@ -37,5 +86,7 @@ See the [2.0.0 release note](docs/releases/2.0.0.md).
 
 The 1.5.0–1.9.0 milestones established runtime evidence, browser review, Intelligence Core, semantic lint, continuity, telemetry and trust-boundary hardening. Their detailed notes are available in [`docs/releases/`](docs/releases/).
 
+[2.2.0]: docs/releases/2.2.0.md
+[2.3.0]: docs/releases/2.3.0.md
 [2.1.0]: docs/releases/2.1.0.md
 [2.0.0]: docs/releases/2.0.0.md

package/README.md

@@ -14,7 +14,7 @@ MotionLoom is an independent open-source Agent Skill for building UI motion, Lot
 
 > **MotionLoom is not an auto-approval layer.** A valid signature, a passing heuristic, or a successful render proves only the contract it checks. Visual quality, intent, accessibility and PR authorization remain reviewable human decisions.
 
-> **Release posture:** the repository source and `package.json` are at **2.1.0**. The public npm registry currently serves **2.0.0** and no GitHub tag/Release for 2.1.0 exists yet; a maintainer must perform the protected manual release before the registry and GitHub release state change.
+> **Release posture:** `motionloom@2.3.0` is the current release target and packages one-command onboarding, project-bound setup/status/repair and the AI-first human-governed asset provenance contract. Verify npm/GitHub publication metadata separately; passing evidence never implies user approval.
 
 ## Why MotionLoom
 
@@ -55,15 +55,26 @@ Every handoff is machine-readable. The typical bundle under `artifacts/<task-id>
 
 ## Quick start
 
-### Install the public CLI
+### Recommended: one command from the project
 
 ```bash
-npm install --global motionloom
-motionloom doctor --json
-motionloom --help
+cd /path/to/your/project
+npx --yes motionloom setup
+npx --no-install motionloom status
+```
+
+This is the easiest path for a project owner. The wizard detects the host project, installs MotionLoom locally as a development dependency, merges an idempotent `AGENTS.md` router, runs discovery and creates fresh project context plus durable `.motionloom/project-memory.json`. It never commits, pushes, opens a PR or grants asset approval.
+
+Preview or repair the same flow without memorizing low-level commands:
+
+```bash
+npx --yes motionloom setup --dry-run --json   # preview; no install or file changes
+npx --yes motionloom setup --yes              # accept safe defaults
+npx --no-install motionloom status --json     # read-only readiness report
+npx --no-install motionloom repair --yes      # restore only missing managed pieces
 ```
 
-MotionLoom supports **Node.js 18+** and **Python 3.11+** on Ubuntu, macOS and Windows. The npm wrapper is the cross-platform surface: it discovers the platform Python executable and delegates to the same canonical contracts used by a repository checkout.
+MotionLoom supports **Node.js 18+** and **Python 3.11+** on Ubuntu, macOS and Windows. `npx` is the recommended first-run surface; after setup, use the project-local binary through `npx --no-install motionloom ...`. A global install remains optional, not required.
 
 ### Start from a real project
 
@@ -72,30 +83,30 @@ Run the first commands from the project that owns the animation. Do not copy the
 ```bash
 cd /path/to/your/project
 
-# Understand the project and bootstrap/recover durable memory.
-motionloom analyze . --init-memory
-motionloom memory inspect --project-root . --json
+# Setup already analyzed the project and bootstrapped durable memory.
+npx --no-install motionloom status --json
+npx --no-install motionloom memory inspect --project-root . --json
 
 # Bound traversal when the host project is large; truncation is reported, never hidden.
-motionloom analyze . --max-files 2500 --max-bytes 25000000 --max-seconds 10
+npx --no-install motionloom analyze . --max-files 2500 --max-bytes 25000000 --max-seconds 10
 
 # Plan and generate the scene using the selected framework.
 python3 /path/to/MotionLoom/src/core/spec.py generate loading \
   --context project-context.json --output motion-spec.json --loop
 
 # Render real runtime evidence and prepare the Dev Lab review handoff.
-motionloom render loading
-motionloom devlab loading
+npx --no-install motionloom render loading
+npx --no-install motionloom devlab loading
 
 # Validate the exact task bundle before any Git side effect.
-motionloom quality-gate --scene loading \
+npx --no-install motionloom quality-gate --scene loading \
   --context project-context.json \
   --task-dir artifacts/loading-task \
   --require-browser-review --require-intelligence --require-p1 \
-  --require-benchmark --require-telemetry --require-attestation
+  --require-benchmark --require-telemetry --require-attestation --require-asset-provenance
 
 # Local-only by default. A user must review and explicitly authorize side effects.
-motionloom pr loading --task-dir artifacts/loading-task
+npx --no-install motionloom pr loading --task-dir artifacts/loading-task
 ```
 
 For a source checkout, use `git clone https://github.com/lenhonbp/MotionLoom.git`, run `npm install`, and replace the global command with `node bin/motionloom.mjs` or the corresponding Python/Node script shown in the [development guide](CONTRIBUTING.md).
@@ -138,6 +149,8 @@ MotionLoom keeps distinct layers distinct:
 | Layer | It proves | It does not prove |
 |---|---|---|
 | Runtime evidence | The selected runtime produced the declared snapshots and observed state | That the motion is aesthetically correct or user-approved |
+| Visual Truth Contract | Baseline/candidate frame identity, dimensions, provenance and review-required regions are bound to the scene | That a changed frame is acceptable or user-approved |
+| Remediation Learning | User-confirmed correction outcomes and deterministic benchmark history with first-pass metrics | That aggregate history can approve a new animation or replace review |
 | Provenance | Which source/material/product bytes were used and how they hash | That the source is appropriate beyond the declared authority/license contract |
 | Semantic lint and benchmark | Bounded rule findings, risk signals and performance measurements | Human visual quality or intent acceptance |
 | Signed attestation | A trusted signer signed the same task-bound hashes under the policy | Reviewer consent, accessibility approval or PR authorization |
@@ -145,6 +158,32 @@ MotionLoom keeps distinct layers distinct:
 
 `approval` remains `false` in attestation and verifier artifacts. The default PR mode is local-only (`OPEN_PR=0`); commit, push and pull-request operations remain explicit side effects.
 
+## Asset provenance tiers
+
+MotionLoom separates **asset origin**, **runtime readiness**, **production eligibility** and **human approval**. This is essential for AI-first workflows: an Agent may create a valid pilot, ingest it into the real runtime and expose it in Dev Lab without being allowed to call that pilot artist-authored or approved for production.
+
+| Authority / origin | Runtime behavior | Production behavior |
+|---|---|---|
+| `ai_generated` | `runtime_ready` when hashes, license metadata and runtime evidence pass | Never `production_eligible` |
+| `ai_assisted` | `runtime_ready` after contract validation | Eligible only after recorded human sign-off and full gate |
+| `ai_assisted_human_reviewed` | `runtime_ready` | `review_required` until the declared production gate is complete; no automatic approval |
+| `artist_authored` | Runtime-testable when the package is valid | Eligible after verified authority, license, runtime and quality checks; not from Agent self-assertion |
+| `unknown` | `blocked` | Blocked |
+
+The readiness value `production_approved` is reserved for a human decision and is not minted by `asset-provenance`, `quality-gate`, attestation or any Agent. Use the following commands against the exact scene artifact:
+
+```bash
+motionloom asset-provenance validate --input src/output/<scene>/asset-provenance.json --json
+motionloom asset-provenance check --input src/output/<scene>/asset-provenance.json \
+  --root src/output/<scene> --mode runtime \
+  --manifest src/output/<scene>/manifest.json --json
+motionloom asset-provenance check --input src/output/<scene>/asset-provenance.json \
+  --root src/output/<scene> --mode production \
+  --manifest src/output/<scene>/manifest.json --json
+```
+
+The [AI-generated pilot fixture](examples/agent-consumer/ai-generated-pilot-provenance.json) demonstrates the intended boundary: it is transparent and runtime-ingestible, but it cannot pass a production gate merely because an Agent declared it complete.
+
 ## How an Agent uses the Skill
 
 The public integration surfaces are intentionally small and inspectable:
@@ -162,6 +201,7 @@ The Skill can trigger or suggest an internal browser-capable Agent to open the D
 |---|---|
 | `SKILL.md` | Installable Agent Skill contract |
 | `agent-card.json` | Capability discovery and side-effect policy |
+| `agent-surfaces.json`, `.agents/`, `.claude/`, `.codex/` | Cross-Agent discovery aliases and portability contract |
 | `bin/motionloom.mjs` | Cross-platform npm CLI entrypoint |
 | `src/core/` | Analyzer, Motion Spec and runtime snapshot engine |
 | `src/rig/` | Character body rig and pose engine |
@@ -172,6 +212,9 @@ The Skill can trigger or suggest an internal browser-capable Agent to open the D
 | `docs/` | Framework selection, checklists, audits and release notes |
 | `dev-lab/` | Self-contained browser review workbench and harness |
 | `artifacts/<task-id>/` | Per-task evidence, report and handoff bundle |
+| `schemas/visual-truth.schema.json`, `scripts/visual-truth.py` | Provenance-bound visual comparison and review explanation contract |
+| `schemas/remediation-history.schema.json`, `scripts/remediation-learning.py` | Append-only remediation/benchmark ledger and aggregate learning metrics |
+| `schemas/asset-provenance.schema.json`, `scripts/asset-provenance.py` | Tiered origin, authority, readiness, license, hash and human-review gate for asset candidates |
 | `tests/` | Regression, adversarial and deep-stress evaluation harnesses |
 
 ## Documentation map
@@ -184,6 +227,8 @@ The Skill can trigger or suggest an internal browser-capable Agent to open the D
 | Understand Agent intelligence | [Intelligence Core](references/intelligence-core.md) and [roadmap](ROADMAP.md) |
 | Run labeled project evaluation | [Project corpus manifest](tests/evals/project-corpus.json) and `python3 scripts/eval-projects.py --allow-insufficient` |
 | Understand trust boundaries | [Signed attestation](references/signed-attestation.md) and [2.0.0 release note](docs/releases/2.0.0.md) |
+| Classify AI-generated or assisted assets | [Asset provenance tiers](schemas/asset-provenance.schema.json), `motionloom asset-provenance`, and the [production checklist](docs/CHECKLIST.md) |
+| Validate visual truth before review/PR | `motionloom visual-truth build|validate` and [production checklist](docs/CHECKLIST.md) |
 | Check current evidence posture | [Current status](docs/STATUS.md), [external corpus evidence](docs/audits/external-project-corpus-2026-08-13.md) and [historical audit snapshot](AUDIT-REPORT.md) |
 | Contribute code or docs | [CONTRIBUTING.md](CONTRIBUTING.md) |
 | Report a vulnerability or request help | [SECURITY.md](SECURITY.md) and [SUPPORT.md](SUPPORT.md) |

package/ROADMAP.md

@@ -2,18 +2,24 @@
 
 MotionLoom's roadmap is organized around one question: **does this reduce incorrect animation iterations while keeping the user in control of quality and Git side effects?** A roadmap item is not complete because a prompt or template exists; it is complete when the contract, evidence, regression coverage and Agent handoff are inspectable.
 
-## Current baseline: 2.1.0
+## Current baseline: 2.3.0 release target
 
-The current repository baseline includes project-aware analysis, durable Project Memory, context-bound Motion Spec, source binding, real runtime adapters for Lottie/dotLottie/SVG cutout/Rive/GSAP/Framer Motion, Dev Lab browser review, Intelligence Core, semantic and continuity feedback, runtime telemetry, external evidence verification, signed attestation and cross-platform CLI/CI contracts.
+The current repository baseline includes project-aware analysis, durable Project Memory, context-bound Motion Spec, source binding, real runtime adapters for Lottie/dotLottie/SVG cutout/Rive/GSAP/Framer Motion, Dev Lab browser review, Intelligence Core, semantic and continuity feedback, runtime telemetry, external evidence verification, signed attestation, Agent interoperability surfaces, Visual Truth, Remediation Learning, AI-first asset provenance and cross-platform CLI/CI contracts. The `2.3.0` release target adds one-command project onboarding without weakening review or Git side-effect boundaries.
 
 ## Next milestones
 
 | Milestone | Focus | Acceptance signal | Status |
 |---|---|---|---|
-| **2.2** | Visual Truth Contract | Provenance-bound frame comparison with `pass`, `fail`, `warn` and `unknown`; no automatic user approval | Planned |
-| **2.3** | Remediation Learning | User-confirmed correction count, first-pass acceptance and rerender-avoidance ledger | Planned |
+| **2.2** | Visual Truth Contract | Provenance-bound frame comparison with `pass`, `fail`, `warn` and `unknown`; no automatic user approval | Included in 2.2.0 candidate |
+| **2.3** | Remediation Learning | User-confirmed correction count, first-pass acceptance and rerender-avoidance ledger | Included in 2.2.0 candidate |
 | **2.4** | Runtime Scale | Multi-project, browser and device corpus with capability compatibility explanations | Planned |
-| **2.5** | Agent Interoperability | Versioned schemas, compatibility matrix and replayable task bundles across Agents | Planned |
+| **2.5** | Agent Interoperability | Versioned schemas, compatibility matrix and replayable task bundles across Agents | Included in 2.2.0 candidate |
+| **2.6** | Agent-created Asset Provenance | Explicit origin/authority/readiness tiers; runtime ingest without automatic production approval; fail-closed production gate | Included in 2.3.0 release target |
+| **2.7** | One-command Onboarding | Project-bound setup/status/repair, Agent router merge, durable memory bootstrap and cross-platform installation recipe | Included in 2.3.0 release target |
+
+## Working-tree implementation status
+
+The current implementation pass has delivered the contracts behind milestones 2.2, 2.3, 2.5, 2.6 and 2.7: canonical Agent discovery/install surfaces, consumer fixtures and a Ubuntu/macOS/Windows matrix; Visual Truth is bound into scene manifests, Dev Lab handoff and the review-first quality gate; Remediation Learning records hash-chained benchmark/outcome history; CI replay evidence is rebuilt after generated artifacts; asset provenance remains production fail-closed; and `npx --yes motionloom setup` bootstraps a project without overwriting its Agent guidance. The remaining work is maintainer release verification and paired evaluation on additional real projects.
 
 ## Product principles
 

package/SECURITY.md

@@ -4,7 +4,8 @@
 
 | Version | Security fixes |
 |---|---|
-| `2.1.x` | Supported |
+| `2.2.x` | Release candidate; support begins on publication |
+| `2.1.x` | Current published line; supported until 2.2.0 publication |
 | `2.0.x` | Best effort while upgrading |
 | `<2.0.0` | Not supported |
 
@@ -20,7 +21,7 @@ MotionLoom can read and write files in the host project, invoke runtimes and pre
 
 Path guards, task identity, source/manifest hashes, evidence freshness, signer policy and approval invariants are security-relevant contracts. Report any bypass that allows cross-project memory, cross-task evidence, stale runtime output or unreviewed Git side effects.
 
-See the [signed attestation reference](references/signed-attestation.md), [browser review contract](references/browser-review-contract.md) and [2.1.0 release note](docs/releases/2.1.0.md) for the current threat model and limitations.
+See the [signed attestation reference](references/signed-attestation.md), [browser review contract](references/browser-review-contract.md) and [2.2.0 release note](docs/releases/2.2.0.md) for the current threat model and limitations.
 
 ## CI/CD controls
 

package/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   validate, review, or deliver animation inside an existing project.
 license: MIT
 metadata:
-  version: "2.1.0"
+  version: "2.3.0"
   target_frameworks: "lottie,dotlottie,rive,gsap,framer-motion,spine,threejs"
   verified_runtimes: "lottie-json,dotlottie-package,svg-cutout-rig,rive,gsap,framer-motion"
 ---
@@ -18,21 +18,29 @@ metadata:
 
 Treat every animation request as a production task, not as an isolated asset-generation prompt. Always bind the work to the host project's context, emit machine-readable artifacts, render through the target runtime, expose review evidence in Dev Lab, and stop before commit when a required gate or user confirmation is missing.
 
+## Fast onboarding for a real project
+
+When MotionLoom is not installed in the host project, prefer the single cross-platform entrypoint `npx --yes motionloom setup`. It detects the project root and package manager, installs a local devDependency, safely merges a marked MotionLoom router block into `AGENTS.md`, runs discovery, creates project-bound context and durable memory, and returns `ready`, `needs_setup` or `blocked`. Use `npx --yes motionloom setup --dry-run --json` before mutation, `npx --no-install motionloom status --json` for read-only checks, and `npx --no-install motionloom repair --yes` to re-apply only missing managed pieces. Never use setup to commit, push, open a PR, grant approval or promote asset provenance.
+
+For Agent or CI composition, consume JSON and preserve the exit code. If the project is already a source checkout, use `node bin/motionloom.mjs setup --project-root <project> --motionloom-root <motionloom-checkout> --skip-install`; do not copy `project-context.json` or `.motionloom/project-memory.json` from the MotionLoom repository.
+
 ## Required workflow
 
-1. **Understand** — read the host project manifest and run `motionloom analyze <project-path> --init-memory` (or `python scripts/analyze.py <project-path> --init-memory` in a repository checkout). Load `project-context.json` and `.motionloom/project-memory.json` from the audited project. If context is missing, stale or ambiguous, stop at `needs_context` and refresh before generation.
+1. **Understand** — run `motionloom setup` once for a new host project, then read the host project manifest and load the generated `project-context.json` and `.motionloom/project-memory.json`. For an already configured project, run `motionloom status --json` and refresh with `motionloom analyze <project-path> --init-memory` when context is missing, stale or ambiguous. In a repository checkout, the equivalent is `node bin/motionloom.mjs setup` or `python scripts/analyze.py <project-path> --init-memory`.
 2. **Plan** — classify the animation, select a framework, and generate a context-bound `motion-spec.json` with timing, easing, loop, accessibility, performance and source authority.
 3. **Source** — resolve an authoritative asset from the project or `assets/library/`. Record attribution, license and checksum in the scene manifest's required `source_binding`; the binding's SHA-256 must match the bytes referenced by `manifest.file`. Do not promote an unknown or placeholder asset to production.
+3a. **Classify asset provenance** — create or load `asset-provenance.json` with `motionloom asset-provenance`. Treat Agent-created material as ingestible only when its origin, generator task, license, file hash and derivation chain are explicit. `ai_generated` may be runtime-tested but is never production-eligible; `ai_assisted` requires human sign-off; `artist_authored` and `production_approved` cannot be self-asserted by an Agent or quality gate. Use `check --mode runtime` for candidate ingest and `check --mode production` only for a full production gate.
 4. **Generate** — use the matching template or rig implementation. For body animation, preserve named anatomy, pivot and parent-first hierarchy.
 5. **Render** — run the platform-neutral Node entrypoint for scene output, or `node scripts/runtime-adapters.mjs` for the verified Rive/GSAP/Framer Motion adapter matrix. Acceptance requires runtime evidence at 0/50/100%, not a static placeholder. Keep the render metadata beside the snapshots.
 6. **Bind Intelligence Core** — build a framework-neutral `motion-ir.json`, `project-graph.json`, `provenance.json`, `replay-bundle.json`, `semantic-lint-report.json` and `semantic-lint-benchmark.json` with `python3 scripts/intelligence.py`. Select only a capability registry entry whose status is `verified`, whose evidence is fresh and whose compatibility matches the target environment. A confidence score or benchmark result can prioritize investigation; neither can replace deterministic or human acceptance.
 6a. **Harden the trust boundary** — keep artifact and task bundles inside the repository/task root, reject symlinked evidence, bind replay to its exact `task_dir`, `task_id` and scene, select one deterministic report bundle per scene, and require browser candidate/review identity and expiry checks before readiness. The Dev Lab must reject cross-origin or identity-mismatched artifact bases. In strict runtime-observability runs, capture `runtime-telemetry.json` and a read-only `evidence-verifier-report.json`; verifier output must preserve `approval: false`. These checks expose risk and prevent evidence mixing, but do not turn heuristics or evidence integrity into approval.
 6b. **Attest** — derive a canonical statement from the exact scene/task hashes, sign it with an Ed25519 key through `scripts/attestation.py`, and verify it with the independent `scripts/attestation-verifier.py` against a fail-closed `trust-policy.json`. DSSE/SLSA-compatible attestation proves signer and binding integrity only; `approval` must remain `false` and never replaces user review.
-7. **Browser review handoff** — run `python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url <internal-lab-url>`. The hook prepares the exact candidate and emits a JSON action for a browser-capable Agent. Trigger or suggest that Agent to open the emitted URL, inspect frames 0/50/100, scrub the timeline and ask the user to review. This is not a separate Dev Lab Skill; it is a required post-render handoff.
+7. **Visual truth and browser review handoff** — after runtime rendering, build `visual-truth.json` from real baseline/candidate PNGs with `motionloom visual-truth build`. The contract records frame hashes, dimensions, runtime/source/manifest provenance and region-level review explanations; a changed frame means `review_required`, never automatic failure or approval. Then run `python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url <internal-lab-url>`. The hook prepares the exact candidate and emits a JSON action for a browser-capable Agent. Trigger or suggest that Agent to open the emitted URL, inspect frames 0/50/100, scrub the timeline and ask the user to review. This is not a separate Dev Lab Skill; it is a required post-render handoff.
 8. **Review capture** — the browser Agent calls `window.__lab.getReview()` after the user approves or requests changes, then persists it with `python3 scripts/report.py review --task-dir artifacts/<task-id> --candidate-id <id> --decision approved|changes_requested --reviewer user`. A change request returns to generation; no approval means no PR.
-9. **Validate** — run `motionloom review-hook validate --task-dir artifacts/<task-id>`, `motionloom intelligence semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500`, `motionloom runtime-telemetry <scene> artifacts/<task-id>`, the independent attestation verifier, `motionloom report-contract --root . --scenes-file <changed-scenes> --require-attestation`, `motionloom quality-gate --scene <scene> --context <context-path> --task-dir artifacts/<task-id> --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation`, and `motionloom doctor --json` when validating the Skill package itself.
+9. **Validate** — run `motionloom asset-provenance check --input src/output/<scene>/asset-provenance.json --root src/output/<scene> --mode runtime|production --manifest src/output/<scene>/manifest.json`, `motionloom visual-truth validate --root . --input src/output/<scene>/visual-truth.json --scene <scene> --task-id <task-id>`, `motionloom review-hook validate --task-dir artifacts/<task-id>`, `motionloom intelligence semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500`, `motionloom runtime-telemetry <scene> artifacts/<task-id>`, the independent attestation verifier, `motionloom report-contract --root . --scenes-file <changed-scenes> --require-attestation`, `motionloom quality-gate --scene <scene> --context <context-path> --task-dir artifacts/<task-id> --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-visual-truth --require-asset-provenance`, and `motionloom doctor --json` when validating the Skill package itself.
 10. **Report** — create or update an artifact bundle with `python3 scripts/report.py`. Record facts with `report.py add`, structural defects with `report.py structure`, collect checksums with `report.py collect`, and run `report.py check` before rendering the final report. The final report must state completed, verified, not completed, blocked/failed, structure problems, browser candidate/review evidence and the recommended next Agent/Skill.
-11. **Confirm** — only after approved browser review and a passing quality gate run the platform-neutral PR preparation command. Commit, push and open PR are explicit side effects.
+11. **Learn** — after a user-confirmed fix or a deterministic benchmark, record it with `motionloom remediation-learning record-outcome|record-benchmark`. Run `summary` to expose correction count, first-pass acceptance, success rate, issue-class outliers and benchmark pass rate. Only `--user-confirmed` outcomes contribute to remediation acceptance metrics.
+12. **Confirm** — only after approved browser review and a passing quality gate run the platform-neutral PR preparation command. Commit, push and open PR are explicit side effects.
 
 ## Durable Project Memory
 
@@ -61,6 +69,7 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - Read `docs/ROADMAP-INTELLIGENCE.md` before extending graph, provenance, capability or replay behavior.
 - Read `references/intelligence-core.md` before building or validating Intelligence Core artifacts.
 - Read `docs/research/AGENT-PROTOCOL-FINDINGS.md` before exposing MotionLoom through Agent tools or MCP resources.
+- Read `references/agent-interoperability.md` when installing MotionLoom into Codex, Claude Code, Cursor, OpenCode or another Agent environment; run `motionloom discovery check --root <motionloom-checkout> --json` before relying on a surface.
 
 ## Non-negotiable contracts
 
@@ -72,9 +81,14 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - Destructive Git actions require explicit confirmation. Use `OPEN_PR=0` for local review-only runs.
 - Intelligence Core artifacts are task-bound: graph, provenance, Motion IR and replay evidence must not be reused across tasks without revalidation.
 - Provenance hashes materials and products; replay must fail on tampered or missing files; stale capability evidence must not be selected for production acceptance.
+- Asset provenance is tiered: `ai_generated` is `runtime_ready` but not `production_eligible`; `ai_assisted` becomes eligible only after human sign-off; `ai_assisted_human_reviewed` remains review-bound; `artist_authored` requires a verified human/artist record and full gate; `unknown` is `blocked`.
+- `production_approved` is a human decision only. An Agent, generator metadata, signed attestation or quality gate may preserve or verify a decision but may never mint it; `approval` remains `false` in machine-generated evidence.
+- Asset provenance binds each declared file to a SHA-256, license/source metadata, generator or derivation chain, runtime evidence and, where applicable, human review. Production checks fail closed on unknown origin, self-asserted artist authority, missing evidence or hash drift.
 - Browser-review candidates are single-use, time-bounded and bound to the exact task, scene and candidate identity; Dev Lab artifact/task bases must be same-origin and identity-consistent before staging a review decision.
 - Report completeness must select one deterministic passing task bundle per scene and fail on ambiguous ties; a valid artifact is never sufficient to bypass explicit user approval.
 - Runtime telemetry must bind task, scene, source, manifest, Motion IR and deterministic scrub points; tampered, stale, missing or cross-task telemetry is a verification failure.
+- Visual Truth must bind baseline/candidate PNG hashes, dimensions, source, manifest, runtime evidence and Motion IR where available; it explains changed regions for review but never emits approval.
+- Remediation Learning history is append-only and hash-chained; correction counts and first-pass acceptance guide the next Agent but never approve an artifact or replace current-task evidence.
 - Signed attestation must bind the same task, scene, context, source, manifest, Motion IR and evidence hashes; unknown, expired or revoked signers fail closed. Attestation verification is an integrity result only and must preserve `approval: false`.
 
 ## Framework boundary
@@ -85,6 +99,8 @@ The audited production paths are **Lottie JSON runtime rendering, dotLottie v2 p
 
 Every production `src/output/<scene>/manifest.json` must include a `source_binding` object matching `schemas/scene-manifest.schema.json`. The acceptance gate rejects a missing binding, a mismatched source path, an unknown license/authority or a stale SHA-256.
 
+Every production candidate that includes generated or assisted material must also reference `asset-provenance.json`. Validate it with `motionloom asset-provenance`; use runtime mode to allow safe ingest/testing and production mode to require `production_eligible`. This contract is deliberately separate from step-level `schemas/provenance.schema.json`: the former answers who/what created an asset and whether it may advance, while the latter records the pipeline steps that handled it.
+
 The Intelligence Core contracts are defined in `schemas/project-graph.schema.json`, `schemas/provenance.schema.json`, `schemas/capability-registry.schema.json`, `schemas/motion-ir.schema.json`, `schemas/signed-attestation.schema.json` and `schemas/trust-policy.schema.json`. They make project relationships, supply-chain steps, runtime selection, framework-neutral intent and signer trust inspectable without relying on prose.
 
 ```bash
@@ -101,6 +117,25 @@ node scripts/runtime-adapters.mjs
 # Capture and verify runtime telemetry without Bash dependencies.
 motionloom runtime-telemetry <scene> artifacts/<task-id>
 
+# Build and validate a provenance-bound visual comparison from real runtime PNGs.
+motionloom visual-truth build --root . --scene <scene> \
+  --baseline src/output/<scene>/snapshot/frame-00.png \
+  --candidate src/output/<scene>/snapshot/frame-100.png \
+  --source src/output/<scene>/<source-file> \
+  --manifest src/output/<scene>/manifest.json \
+  --runtime-evidence artifacts/<task-id>/runtime-adapters/runtime-evidence.json \
+  --motion-ir artifacts/<task-id>/motion-ir.json --task-id <task-id> \
+  --output src/output/<scene>/visual-truth.json
+motionloom visual-truth validate --root . --input src/output/<scene>/visual-truth.json \
+  --scene <scene> --task-id <task-id>
+
+# Record only a user-confirmed remediation outcome, then summarize durable learning.
+motionloom remediation-learning record-outcome --history artifacts/remediation-history.jsonl \
+  --event-id outcome-001 --issue-id easing-drift --summary "User accepted easing correction" \
+  --result pass --correction-count 1 --source-task-id <task-id> --user-confirmed --json
+motionloom remediation-learning summary --history artifacts/remediation-history.jsonl \
+  --output artifacts/remediation-summary.json --json
+
 # Build the task-bound Intelligence Core artifacts.
 python3 scripts/intelligence.py motion-ir build --task-dir artifacts/<task-id>
 python3 scripts/intelligence.py graph build --task-dir artifacts/<task-id>

package/agent-card.json

@@ -1,9 +1,15 @@
 {
   "card_version": "1.0",
   "name": "motionloom",
-  "version": "2.1.0",
-  "description": "Project-aware animation production with durable Project Memory, graph, provenance, framework-neutral motion IR, runtime verification and telemetry, DSSE-compatible signed attestation, external evidence verification, semantic feedback, continuity checks, internal browser review, trust-boundary hardening and deterministic Agent handoff.",
+  "version": "2.3.0",
+  "description": "Project-aware animation production with durable Project Memory, graph, step-level provenance, tiered asset provenance, framework-neutral motion IR, runtime verification and telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, external evidence verification, semantic feedback, continuity checks, internal browser review, trust-boundary hardening and deterministic Agent handoff.",
   "capabilities": [
+    "project.setup",
+    "project.status",
+    "project.repair",
+    "agent.discovery.check",
+    "agent.discovery.source",
+    "agent.discovery.install-matrix",
     "project.analyze",
     "project.memory.init",
     "project.memory.inspect",
@@ -18,6 +24,10 @@
     "motion.ir.build",
     "motion.ir.validate",
     "asset.provenance",
+    "asset.provenance.classify",
+    "asset.provenance.validate",
+    "asset.provenance.report",
+    "asset.provenance.production-gate",
     "provenance.emit",
     "provenance.verify",
     "capability.discover",
@@ -42,6 +52,12 @@
     "runtime.verify.framer-motion",
     "runtime.telemetry.capture",
     "runtime.telemetry.validate",
+    "visual-truth.build",
+    "visual-truth.validate",
+    "remediation-learning.record-outcome",
+    "remediation-learning.record-benchmark",
+    "remediation-learning.validate",
+    "remediation-learning.summary",
     "evidence.verify.external",
     "attestation.statement.build",
     "attestation.sign.ed25519",
@@ -61,12 +77,15 @@
     "project-manifest",
     "animation-request",
     "source-asset"
+    ,"asset-provenance"
   ],
   "output_artifacts": [
+    "agent-discovery-report",
     "project-context",
     "motion-spec",
     "runtime-scene",
     "source-binding",
+    "asset-provenance",
     "dotlottie-package",
     "runtime-evidence",
     "runtime-telemetry",
@@ -86,6 +105,9 @@
     "replay-bundle",
     "semantic-lint-report",
     "semantic-lint-benchmark",
+    "visual-truth",
+    "remediation-history",
+    "remediation-summary",
     "hardening-audit-report",
     "project-memory",
     "continuity-report",
@@ -132,6 +154,13 @@
     }
   ],
   "entrypoints": {
+    "setup": "npx --yes motionloom setup --project-root <project-path>",
+    "setup_dry_run": "npx --yes motionloom setup --project-root <project-path> --dry-run --json",
+    "status": "npx --no-install motionloom status --project-root <project-path> --json",
+    "repair": "npx --no-install motionloom repair --project-root <project-path> --yes --json",
+    "discovery_check": "motionloom discovery check --root <motionloom-checkout> --json",
+    "discovery_source": "motionloom discovery source --root <motionloom-checkout> --json",
+    "discovery_install_matrix": "motionloom discovery install-matrix --root <motionloom-checkout> --json",
     "analyze": "motionloom analyze <project-path> --init-memory",
     "memory_init": "motionloom memory init --project-root <project-path>",
     "memory_inspect": "motionloom memory inspect --project-root <project-path> --json",
@@ -159,12 +188,21 @@
     "semantic_lint_benchmark": "python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500",
     "continuity": "python3 scripts/intelligence.py continuity build --task-dirs artifacts/<task-id>...",
     "fix_plan": "python3 scripts/intelligence.py fix-plan build --task-dir artifacts/<task-id> --reports semantic-lint-report.json continuity-report.json",
-    "quality_gate_p1": "python3 scripts/quality-gate.py --scene <scene> --context <path> --task-dir artifacts/<task-id> --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry",
+    "asset_provenance_check": "motionloom asset-provenance check --input src/output/<scene>/asset-provenance.json --root src/output/<scene> --mode runtime|production --manifest src/output/<scene>/manifest.json --json",
+    "asset_provenance_classify": "motionloom asset-provenance classify --input <asset-provenance.json> --json",
+    "asset_provenance_validate": "motionloom asset-provenance validate --input <asset-provenance.json> --json",
+    "asset_provenance_report": "motionloom asset-provenance report --input <asset-provenance.json> --json",
+    "quality_gate_p1": "python3 scripts/quality-gate.py --scene <scene> --context <path> --task-dir artifacts/<task-id> --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-asset-provenance",
     "attestation_statement": "python3 scripts/attestation.py statement --scene-dir src/output/<scene> --task-dir artifacts/<task-id> --context <project-context.json> --output artifacts/<task-id>/attestation-statement.json",
     "attestation_build": "python3 scripts/attestation.py build --statement artifacts/<task-id>/attestation-statement.json --private-key <key> --key-id <key-id> --output artifacts/<task-id>/attestation.json",
     "attestation_verify": "python3 scripts/attestation-verifier.py --attestation artifacts/<task-id>/attestation.json --trust-policy artifacts/<task-id>/trust-policy.json --expected-task-id <task-id> --expected-scene <scene>",
     "attestation_report": "python3 scripts/attestation-verifier.py --attestation artifacts/<task-id>/attestation.json --trust-policy artifacts/<task-id>/trust-policy.json --expected-task-id <task-id> --expected-scene <scene> --output artifacts/<task-id>/attestation-verifier-report.json",
-    "quality_gate_attestation": "python3 scripts/quality-gate.py --scene <scene> --context <path> --task-dir artifacts/<task-id> --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation",
+    "quality_gate_attestation": "python3 scripts/quality-gate.py --scene <scene> --context <path> --task-dir artifacts/<task-id> --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation --require-asset-provenance",
+    "visual_truth_build": "motionloom visual-truth build --root <project-path> --scene <scene> --baseline <baseline.png> --candidate <candidate.png> --output src/output/<scene>/visual-truth.json",
+    "visual_truth_validate": "motionloom visual-truth validate --root <project-path> --input src/output/<scene>/visual-truth.json --scene <scene> --task-id <task-id>",
+    "remediation_record_outcome": "motionloom remediation-learning record-outcome --history artifacts/remediation-history.jsonl --event-id <id> --issue-id <issue-id> --summary <summary> --result pass|fail|partial|unknown --correction-count <n> --user-confirmed",
+    "remediation_record_benchmark": "motionloom remediation-learning record-benchmark --history artifacts/remediation-history.jsonl --event-id <id> --operation <operation> --task-id <task-id> --scene <scene> --iterations <n> --p95-ms <ms> --threshold-ms <ms>",
+    "remediation_summary": "motionloom remediation-learning summary --history artifacts/remediation-history.jsonl --output artifacts/remediation-summary.json --json",
     "browser_review_prepare": "python3 scripts/review-hook.py prepare --task-dir artifacts/<task-id> --lab-url <internal-lab-url>",
     "browser_review_validate": "python3 scripts/review-hook.py validate --task-dir artifacts/<task-id>",
     "pr_prepare": "node scripts/pr.mjs <scene>"