motionloom 2.1.0 → 2.2.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,32 @@
 
 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 currently tracked.
+
+## [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 +63,6 @@ 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.1.0]: docs/releases/2.1.0.md
 [2.0.0]: docs/releases/2.0.0.md

package/README.md

@@ -138,6 +138,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 |
@@ -162,6 +164,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 +175,8 @@ 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 |
 | `tests/` | Regression, adversarial and deep-stress evaluation harnesses |
 
 ## Documentation map
@@ -184,6 +189,7 @@ 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) |
+| 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,22 @@
 
 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.2.0 release candidate
 
-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 and cross-platform CLI/CI contracts. The package metadata is at `2.2.0`; remote publication remains pending explicit release approval.
 
 ## 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 |
+
+## Working-tree implementation status
+
+The current implementation pass has delivered the contracts behind milestones 2.2, 2.3 and 2.5: 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; and CI replay evidence is rebuilt after generated artifacts. The remaining release work is remote tag/Release creation, npm publication 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.2.0"
   target_frameworks: "lottie,dotlottie,rive,gsap,framer-motion,spine,threejs"
   verified_runtimes: "lottie-json,dotlottie-package,svg-cutout-rig,rive,gsap,framer-motion"
 ---
@@ -28,11 +28,12 @@ Treat every animation request as a production task, not as an isolated asset-gen
 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 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`, 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 +62,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
 
@@ -75,6 +77,8 @@ Only user-confirmed decisions and outcomes may become durable remediation memory
 - 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
@@ -101,6 +105,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,12 @@
 {
   "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.2.0",
+  "description": "Project-aware animation production with durable Project Memory, graph, 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": [
+    "agent.discovery.check",
+    "agent.discovery.source",
+    "agent.discovery.install-matrix",
     "project.analyze",
     "project.memory.init",
     "project.memory.inspect",
@@ -42,6 +45,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",
@@ -63,6 +72,7 @@
     "source-asset"
   ],
   "output_artifacts": [
+    "agent-discovery-report",
     "project-context",
     "motion-spec",
     "runtime-scene",
@@ -86,6 +96,9 @@
     "replay-bundle",
     "semantic-lint-report",
     "semantic-lint-benchmark",
+    "visual-truth",
+    "remediation-history",
+    "remediation-summary",
     "hardening-audit-report",
     "project-memory",
     "continuity-report",
@@ -132,6 +145,9 @@
     }
   ],
   "entrypoints": {
+    "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",
@@ -165,6 +181,11 @@
     "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",
+    "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>"

package/agent-surfaces.json

@@ -0,0 +1,79 @@
+{
+  "schema_version": "1.0",
+  "name": "motionloom",
+  "version": "2.2.0",
+  "canonical": {
+    "skill": "SKILL.md",
+    "agent_card": "agent-card.json",
+    "cli": "bin/motionloom.mjs"
+  },
+  "surfaces": [
+    {
+      "id": "agents-skills",
+      "kind": "agent-skill",
+      "path": ".agents/skills/motionloom/SKILL.md",
+      "canonical": "SKILL.md",
+      "load_mode": "alias",
+      "agents": ["codex", "claude-code", "cursor", "opencode"]
+    },
+    {
+      "id": "claude-code",
+      "kind": "agent-instructions",
+      "path": ".claude/skills/motionloom.md",
+      "canonical": "SKILL.md",
+      "load_mode": "alias",
+      "agents": ["claude-code"]
+    },
+    {
+      "id": "codex",
+      "kind": "agent-instructions",
+      "path": ".codex/skills/motionloom.md",
+      "canonical": "SKILL.md",
+      "load_mode": "alias",
+      "agents": ["codex"]
+    },
+    {
+      "id": "repository-agent-guide",
+      "kind": "repository-guide",
+      "path": "AGENTS.md",
+      "canonical": "SKILL.md",
+      "load_mode": "router",
+      "agents": ["codex", "claude-code", "cursor", "opencode"]
+    }
+  ],
+  "installations": [
+    {
+      "id": "npm-registry",
+      "source_kind": "npm",
+      "command": "npm install --save-dev motionloom",
+      "verification": "motionloom discovery check --root . --json",
+      "provenance": "package-lock-or-pnpm-lock"
+    },
+    {
+      "id": "github-checkout",
+      "source_kind": "git",
+      "command": "git clone https://github.com/lenhonbp/MotionLoom.git",
+      "verification": "node bin/motionloom.mjs discovery check --root . --json",
+      "provenance": "git-commit-and-remote"
+    },
+    {
+      "id": "local-source",
+      "source_kind": "local",
+      "command": "node <motionloom-checkout>/bin/motionloom.mjs discovery check --root <motionloom-checkout> --json",
+      "verification": "python3 scripts/discovery.py check --root . --json",
+      "provenance": "absolute-or-relative-source-path"
+    }
+  ],
+  "compatibility": {
+    "operating_systems": ["ubuntu", "macos", "windows"],
+    "node": ">=18",
+    "python": ">=3.11",
+    "agents": ["codex", "claude-code", "cursor", "opencode"]
+  },
+  "rules": {
+    "canonical_instruction_source": "SKILL.md",
+    "no_surface_copy": true,
+    "no_network_required_for_check": true,
+    "approval_is_never_inferred": true
+  }
+}

package/bin/motionloom.mjs

@@ -34,10 +34,13 @@ const PYTHON_COMMANDS = {
   manifest: "scripts/manifest.py",
   test: "tests/scripts/run_tests.py",
   "deep-audit": "tests/scripts/deep-stress.py",
+  discovery: "scripts/discovery.py",
+  "visual-truth": "scripts/visual-truth.py",
+  "remediation-learning": "scripts/remediation-learning.py",
 };
 
 function printHelp() {
-  console.log(`MotionLoom 2.1.0 — project-aware animation production and evidence contracts
+  console.log(`MotionLoom 2.2.0 — project-aware animation production and evidence contracts
 
 Usage:
   motionloom <command> [args...]
@@ -59,6 +62,9 @@ Commands:
   validate-lottie        Validate a Lottie animation
   manifest               Build or validate a production manifest
   eval-intelligence      Run adversarial Intelligence Core evaluation
+  discovery              Check Agent surfaces, source identity and install matrix
+  visual-truth           Build or validate provenance-bound visual comparisons
+  remediation-learning   Record or summarize user-confirmed remediation and benchmark history
 
 Cross-platform examples:
   motionloom analyze . --init-memory
@@ -66,6 +72,10 @@ Cross-platform examples:
   motionloom memory refresh --project-root . --json
   motionloom memory record-decision --project-root . --id ui-easing \\
     --status accepted --summary "Use ease-out for UI entry" --user-confirmed
+  motionloom discovery check --root . --json
+  motionloom discovery install-matrix --root . --json
+  motionloom visual-truth validate --root . --input src/output/<scene>/visual-truth.json
+  motionloom remediation-learning summary --history artifacts/remediation-history.jsonl --json
 
 The CLI never grants approval or opens a pull request by itself. User review
 and explicit repository side-effect confirmation remain separate gates.

package/docs/AGENT-INTEGRATION.md

@@ -0,0 +1,47 @@
+# Agent interoperability and installation contract
+
+MotionLoom is distributed as one Skill with several **discovery surfaces**, not as several independent Skills. The root `SKILL.md` is canonical. `agent-card.json` is the capability contract. `agent-surfaces.json` records the supported surfaces, installation sources and compatibility policy.
+
+## Install sources
+
+| Source | Typical command | Verification | Provenance to retain |
+|---|---|---|---|
+| npm registry | `npm install --save-dev motionloom` | `motionloom discovery check --root . --json` | lockfile and resolved package version |
+| Git checkout | `git clone https://github.com/lenhonbp/MotionLoom.git` | `node bin/motionloom.mjs discovery check --root . --json` | remote URL and commit SHA |
+| Local source | invoke `<checkout>/bin/motionloom.mjs` | `python3 scripts/discovery.py check --root . --json` | source path and local commit if present |
+
+The check is offline and read-only. Installation, source identity and capability compatibility are separate from network authentication. A passing check means that the package is structurally discoverable; it does not mean that a scene is runtime-verified or approved.
+
+## Agent surfaces
+
+| Surface | Path | Role |
+|---|---|---|
+| Agent Skills | `.agents/skills/motionloom/SKILL.md` | Portable alias for Agent Skills discovery |
+| Claude Code | `.claude/skills/motionloom.md` | Claude-specific router to the canonical Skill |
+| Codex | `.codex/skills/motionloom.md` | Codex-specific router to the canonical Skill |
+| Repository router | `AGENTS.md` | Short first-load instructions for repository-aware Agents |
+
+These files deliberately remain short. They must not become a second instruction source. Every surface points back to `SKILL.md`; drift is a contract failure and is checked by `motionloom discovery check` and the documentation audit.
+
+## Agent compatibility matrix
+
+| Agent | Discovery surface | Expected first action | Review boundary |
+|---|---|---|---|
+| Codex | `.codex/skills/motionloom.md`, `.agents/skills/motionloom/SKILL.md` | Run discovery check, load root Skill and Agent Card | No commit/push/PR without explicit user confirmation |
+| Claude Code | `.claude/skills/motionloom.md`, `.agents/skills/motionloom/SKILL.md` | Run discovery check, load root Skill and Agent Card | Same review-first gate |
+| Cursor | `.agents/skills/motionloom/SKILL.md`, `AGENTS.md` | Load canonical Skill through repository rules | Same review-first gate |
+| OpenCode | `.agents/skills/motionloom/SKILL.md`, `AGENTS.md` | Load canonical Skill and run discovery check | Same review-first gate |
+
+Support here means that the repository exposes a deterministic discovery contract. It does not claim that every Agent version automatically loads every convention. The Agent must report when a surface is unavailable or when it cannot open the internal Dev Lab.
+
+## Required first-run sequence
+
+Run `motionloom discovery check --root <checkout> --json`, inspect `source`, then run project analysis with `motionloom analyze <project> --init-memory`. Load the project context and durable Project Memory before planning. After rendering, prepare a task-bound browser candidate and suggest or trigger the internal Dev Lab. Capture user feedback separately from runtime evidence. A valid signature, quality gate or screenshot is not a user approval.
+
+## Portability policy
+
+The npm entrypoint is the public cross-platform surface. Ubuntu, macOS and Windows must use Node argument arrays, Python `pathlib`, UTF-8 JSON and no required Bash, POSIX `/tmp`, system `zip` or system `unzip`. Bash wrappers may remain convenience scripts for repository contributors, but the discovery and validation commands must work through Node/Python on all supported operating systems.
+
+## Troubleshooting
+
+If discovery fails, do not continue as if the Skill were loaded. Inspect the JSON `errors`, verify that the checkout has not mixed files from different versions, and rerun from the intended root. If the package version and `agent-surfaces.json` disagree, use the same source checkout or reinstall the package. If a runtime dependency is missing, report it as a blocker; do not replace runtime evidence with a static placeholder.

package/docs/CHECKLIST.md

@@ -23,9 +23,10 @@ A scene is only ready for the confirm-into-PR step when every item below passes.
 
 ## Source traceability
 - [ ] Every geometric asset references an authoritative source (`assets/library/` or the host project) — flagged if invented.
-- [ ] `manifest.json` records framework, source path, license note, spec hash, and completed checklist entries.
+- [ ] `manifest.json` records framework, source path, license note, spec hash, visual-truth path, and completed checklist entries.
 
 ## PR readiness
 - [ ] Snapshot PNGs exist for 0/50/100%.
+- [ ] `visual-truth.json` binds real baseline/candidate frames to source, manifest and available runtime/Motion IR hashes; `approval` remains `false`.
 - [ ] `motion-spec.json` is bound to the exact `project-context.json` hash (implements == planned).
 - [ ] Dev Lab URL tested on mobile viewport and desktop.

package/docs/STATUS.md

@@ -4,7 +4,7 @@
 
 ## Current release posture
 
-MotionLoom's repository source and package manifest are at version **2.1.0**. The public npm registry currently serves **2.0.0**; the GitHub repository has no tag or GitHub Release for 2.1.0 until an explicitly approved release is performed. The repository has a cross-platform CLI, durable Project Memory, artifact-first handoff, runtime evidence, signed attestation and a browser-based Dev Lab review contract. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
+MotionLoom's repository source and package manifest are at **2.2.0 release-candidate metadata**. The public npm registry currently serves **2.1.0**, while the latest published GitHub Release/tag remains **v2.1.0**; the 2.2.0 tag, GitHub Release and npm publication are intentionally pending explicit maintainer approval. The repository has a cross-platform CLI, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation and a browser-based Dev Lab review contract. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
 
 The repository is **engineering-ready for continued integration work**, not a universal production certification for every animation framework or every host project. CI status must be read from the latest GitHub Actions run, not inferred from historical audit prose.
 

package/docs/audits/ci-replay-remediation-2026-08-13.md

@@ -0,0 +1,33 @@
+# CI Replay Remediation — 2026-08-13
+
+## Evidence
+
+The `MotionLoom Quality` workflow for commit [`d148f21`](https://github.com/lenhonbp/MotionLoom/commit/d148f2175e47e3fc32f7156fc83af82c749b47ed) completed with failure in run [`31709781319`](https://github.com/lenhonbp/MotionLoom/actions/runs/31709781319). Documentation and Package Hygiene and Security Analysis completed successfully on the same commit.
+
+The failing step was **Enforce context-bound quality gate**. The recorded rejection was:
+
+> `replay bundle has 11 mismatch(es)`
+
+The preceding Intelligence, project graph, Motion IR and provenance checks were valid. The failure therefore represented stale replay hashes, not an approval decision or a request to weaken the verifier.
+
+## Root cause
+
+The Quality workflow treated `replay-bundle.json` as a committed integrity snapshot, but earlier steps intentionally regenerate runtime telemetry, semantic-lint benchmark output, report/manifest output, signed attestation output and rendered runtime evidence for changed scenes. The quality gate then verified the old replay bundle against those newly generated files. A local verification before the generated-artifact phase could pass while the same sequence in CI correctly reported mismatches.
+
+## Remediation
+
+The workflow now runs the canonical command below after runtime snapshot rendering and before the context-bound quality gate:
+
+```text
+python3 scripts/intelligence.py replay capture \
+  --task-dir "artifacts/${scene}-task" --root . \
+  --output "artifacts/${scene}-task/replay-bundle.json"
+```
+
+The change does not remove replay verification, expand exclusions, or turn heuristic evidence into approval. A regression assertion checks that replay capture follows runtime rendering and precedes the quality gate. A temporary task-bundle test also confirms that tampered evidence is rejected, canonical capture rebuilds its hashes, and the rebuilt bundle verifies successfully.
+
+## Local verification
+
+After the remediation, the following checks passed locally: engine regression, docs audit, Skill Doctor, skill-creator validator, runtime adapter smoke, Agent discovery, installation matrix, Visual Truth validation, Remediation Learning validation, quality attestation with Visual Truth required, npm dry-run, Python syntax compilation and `git diff --check`.
+
+This audit records the CI incident and its fix as evidence; it does not change the published `motionloom@2.1.0` version or grant user approval.

package/docs/releases/2.2.0.md

@@ -0,0 +1,35 @@
+# MotionLoom 2.2.0
+
+## Summary
+
+MotionLoom 2.2.0 turns the project-aware animation Skill into a more portable Agent production contract. This release candidate adds canonical discovery surfaces, consumer fixtures, cross-platform installation evidence, provenance-bound Visual Truth, append-only Remediation Learning and a CI replay remediation that fails closed without confusing stale evidence with user approval.
+
+## Added
+
+### Agent interoperability and installation
+
+The package now exposes one canonical `SKILL.md` through `.agents/skills`, `.claude`, `.codex` and `AGENTS.md`. The discovery manifest and schema describe source kind, version, canonical files, compatibility and verification commands. The `motionloom discovery check`, `source` and `install-matrix` commands are cross-platform and do not require network access for local contract checks.
+
+The consumer fixture manifest covers Lottie/dotLottie, Rive, GSAP, Framer Motion, body rigs and multi-scene continuity. Ubuntu, macOS and Windows are represented as explicit installation-matrix targets rather than an unverified portability claim.
+
+### Visual Truth
+
+`visual-truth.json` binds baseline and candidate frame hashes, dimensions, scene/task identity, source and manifest provenance, runtime evidence and Motion IR where available. The validator emits deterministic comparison signals and region-level explanations for review. A changed frame produces `review_required`; it never becomes automatic approval.
+
+### Remediation Learning
+
+The append-only, hash-chained remediation history stores user-confirmed outcomes and deterministic benchmark records. Summaries expose correction count, first-pass acceptance, success rate, issue-class outliers and benchmark pass rate. Unconfirmed outcomes cannot enter acceptance metrics.
+
+## Fixed
+
+The Quality workflow now rebuilds the exact task-bound replay bundle after runtime, report and attestation artifacts are generated and before the context-bound quality gate. Regression coverage exercises tamper rejection and canonical replay rebuild, preventing stale generated hashes from causing a false CI rejection.
+
+## Verified behavior
+
+The release candidate passes the full regression harness, docs audit, Skill Doctor, skill-creator validator, runtime adapter smoke, discovery and installation matrix checks, Visual Truth validation, Remediation Learning validation, quality attestation with Visual Truth required, npm package dry-run, Python syntax compilation and diff hygiene. The mainline commit carrying the replay fix also passed Quality, Documentation and Package Hygiene, and Security workflows on GitHub.
+
+## Trust boundary and remaining scope
+
+This release does not infer approval from visual metrics, heuristics, signatures, attestations or benchmark scores. The user must inspect the Dev Lab review candidate and explicitly approve before PR preparation. Commit, push, tag creation, GitHub Release creation and npm publication remain separate explicit side effects.
+
+The next evidence priority is paired evaluation across additional real animation projects to measure first-pass acceptance, correction count, time-to-fix and rerender avoidance without presenting synthetic scores as human approval.