motionloom 2.1.0 → 2.3.0

package/agent-surfaces.json

@@ -0,0 +1,86 @@
+{
+  "schema_version": "1.0",
+  "name": "motionloom",
+  "version": "2.3.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": "npx-onboarding",
+      "source_kind": "npx",
+      "command": "npx --yes motionloom setup",
+      "verification": "npx --no-install motionloom status --json",
+      "provenance": "npm-registry-resolution-and-project-lockfile"
+    },
+    {
+      "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,20 @@ 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",
+  "asset-provenance": "scripts/asset-provenance.py",
+};
+
+const NODE_COMMANDS = {
+  setup: "scripts/setup.mjs",
+  status: "scripts/setup.mjs",
+  repair: "scripts/setup.mjs",
 };
 
 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 +69,13 @@ 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
+  asset-provenance       Validate, classify or report asset origin and production readiness
+  setup                  Install and bootstrap MotionLoom in the current project
+  status                 Read-only project readiness report
+  repair                 Re-apply safe missing setup pieces
 
 Cross-platform examples:
   motionloom analyze . --init-memory
@@ -66,6 +83,11 @@ 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
+  motionloom asset-provenance check --input <asset-provenance.json> --root <scene-dir> --mode runtime --json
 
 The CLI never grants approval or opens a pull request by itself. User review
 and explicit repository side-effect confirmation remain separate gates.
@@ -78,7 +100,7 @@ if (!command || command === "help" || command === "--help" || command === "-h")
   process.exit(0);
 }
 
-const script = PYTHON_COMMANDS[command];
+const script = NODE_COMMANDS[command] || PYTHON_COMMANDS[command];
 if (!script) {
   console.error(`Unknown MotionLoom command: ${command}`);
   printHelp();
@@ -86,7 +108,8 @@ if (!script) {
 }
 
 const executable = script.endsWith(".mjs") ? process.execPath : PYTHON;
-const result = spawnSync(executable, [resolve(ROOT, script), ...args], {
+const delegatedArgs = NODE_COMMANDS[command] && command !== "setup" ? [command, ...args] : args;
+const result = spawnSync(executable, [resolve(ROOT, script), ...delegatedArgs], {
   cwd: ROOT,
   stdio: "inherit",
   env: process.env,

package/docs/AGENT-INTEGRATION.md

@@ -0,0 +1,60 @@
+# 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 |
+|---|---|---|---|
+| One-command onboarding | `npx --yes motionloom setup` | `npx --no-install motionloom status --json` | project lockfile, setup JSON and generated project identity |
+| 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. For a new host project, prefer `npx --yes motionloom setup`; use `--dry-run --json` to preview and `status --json` to inspect without mutation. `repair --yes` only restores missing managed pieces.
+
+## 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
+
+For a new host project, run `npx --yes motionloom setup --json`, inspect the returned `status`, then use `npx --no-install motionloom status --json` before planning. Setup performs project analysis, discovery and durable-memory bootstrap without copying artifacts from the MotionLoom checkout. For an existing installation, run `motionloom discovery check --root <checkout> --json`, then refresh with `motionloom analyze <project> --init-memory` when needed. Load the project context and durable Project Memory before planning. After selecting or generating an asset, create `asset-provenance.json` and run the runtime-mode check before ingest. An AI-generated pilot may proceed to the real runtime and Dev Lab, but it must remain non-production-eligible. 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.
+
+## AI-first asset workflow
+
+The Agent must distinguish these transitions rather than collapsing them into one `approved` flag:
+
+| Transition | Allowed actor | Required evidence |
+|---|---|---|
+| `blocked` → `runtime_ready` | Agent or runtime validator | Safe paths, valid schema, license/source, file hashes and real runtime evidence |
+| `runtime_ready` → `production_eligible` | Contract gate plus human review where the authority tier requires it | Full quality/visual/runtime gate and valid authority record |
+| `production_eligible` → `production_approved` | User or designated human reviewer only | Explicit review decision persisted outside the Agent's self-assertion |
+
+Never rewrite `ai_generated` as `artist_authored`, never infer human review from a signature, and never set `production_approved` from `quality-gate`. Use `motionloom asset-provenance report` to show the boundary in a handoff.
+
+## 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,15 @@ 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.
+- [ ] `asset-provenance.json` records origin/authority, generator or derivation chain, license/source, per-file SHA-256 and runtime evidence.
+- [ ] `ai_generated` assets may be runtime-ready but are not production-eligible; `unknown` assets are blocked.
+- [ ] `artist_authored` is backed by a verifiable human/artist record and is not merely an Agent-authored field.
 
 ## 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.
+- [ ] The production provenance check passes with `--mode production` and reports `production_eligible: true`.
+- [ ] `production_approved` and browser-review approval are recorded only from the user's explicit review; attestation approval remains `false`.

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 prepared for **2.3.0 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance 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.
 
@@ -30,4 +30,4 @@ Use the following order when sources disagree:
 
 ## Known next work
 
-The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The highest-value remaining evidence work is paired product evaluation across more real projects, then closing version–tag–GitHub Release–npm provenance traceability through an approved manual release. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.
+The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The highest-value remaining evidence work is paired product evaluation across more real projects and verification of the 2.3.0 version–tag–GitHub Release–npm provenance chain. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.

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.

package/docs/releases/2.3.0.md

@@ -0,0 +1,33 @@
+# MotionLoom 2.3.0
+
+## Summary
+
+MotionLoom 2.3.0 makes the project-aware animation Skill easier to install and resume in a real project. It introduces a canonical one-command onboarding path while preserving the evidence-first, review-first and local-only safety boundaries established by the previous releases.
+
+## Added
+
+### One-command project onboarding
+
+`npx --yes motionloom setup` detects the host project, selects npm/pnpm/yarn from the project contract, installs MotionLoom as a local development dependency, merges a marked router block into `AGENTS.md`, runs discovery and bootstraps project-bound context plus durable Project Memory. The operation is idempotent and never overwrites unmarked project guidance.
+
+Read-only and repair surfaces are available through `npx --no-install motionloom status --json` and `npx --no-install motionloom repair --yes`. `--dry-run --json` exposes the planned changes before mutation, which gives Agents and CI a machine-readable preview.
+
+### Agent interoperability
+
+The discovery manifest now advertises the `npx` recipe as the preferred onboarding path, while npm, Git checkout and local checkout remain available for contributors and controlled environments. The installation matrix explicitly covers setup, status and repair commands across Ubuntu, macOS and Windows.
+
+### Asset provenance
+
+The AI-first human-governed asset provenance contract from the 2.2.0 working tree is included in this release. Agents may create assets for runtime ingest and testing, but `ai_generated` does not become production-eligible; `production_approved` remains human-only.
+
+## Fixed
+
+Machine-readable setup output no longer mixes package-manager installation logs with JSON. Dispatcher routing keeps `status` read-only and prevents `repair` from accidentally becoming an unrestricted full setup. Managed router repair remains idempotent and package-manager agnostic.
+
+## Verified behavior
+
+The release target passes the full regression harness, onboarding and installation-matrix tests, discovery contract, docs audit, Skill Doctor, skill-creator validation, quality validation, npm tarball dry-run and diff hygiene.
+
+## Trust boundary
+
+Setup does not commit, push, open a PR, grant user approval or promote asset provenance. Runtime evidence, quality gates, attestations and heuristics remain evidence only. The user must inspect the Dev Lab candidate and explicitly authorize any Git side effect.

package/docs/releases/npm-publish-from-workstation.md

@@ -1,6 +1,6 @@
 # Publish MotionLoom to npm from your workstation
 
-This guide publishes the prepared `motionloom@2.1.0` package from your own computer. The npm password, authenticator code and access token must stay on your computer; never paste them into chat, GitHub issues or repository files.
+This guide publishes the prepared `motionloom@2.3.0` package from your own computer. The npm password, authenticator code and access token must stay on your computer; never paste them into chat, GitHub issues or repository files.
 
 ## 1. Install prerequisites
 
@@ -48,7 +48,7 @@ npm pack --dry-run --json --ignore-scripts
 npm publish --dry-run --access public
 ```
 
-The dry-run should report `motionloom@2.1.0`, public access, and the current package file list. Do not hard-code a historical file count: inspect the JSON output and compare it with the checked-in package allowlist. The prepack hook removes generated Python bytecode before packaging. Do not publish if the dry-run shows private keys, `.env` files, `artifacts/`, `dev-lab/` or `__pycache__/` entries.
+The dry-run should report `motionloom@2.3.0`, public access, and the current package file list. Do not hard-code a historical file count: inspect the JSON output and compare it with the checked-in package allowlist. The prepack hook removes generated Python bytecode before packaging. Do not publish if the dry-run shows private keys, `.env` files, `artifacts/`, `dev-lab/` or `__pycache__/` entries.
 
 ## 5. Publish the package
 
@@ -58,15 +58,15 @@ When the dry-run is correct and `npm whoami` shows the intended account, publish
 npm publish --access public
 ```
 
-The version `2.1.0` becomes immutable on npm after a successful publish. If npm reports that the version already exists, stop and verify the registry instead of trying to overwrite it.
+The version `2.3.0` becomes immutable on npm after a successful publish. If npm reports that the version already exists, stop and verify the registry instead of trying to overwrite it.
 
 ## 6. Verify the registry publication
 
-Run the following commands and confirm that they return `2.1.0` and a tarball URL:
+Run the following commands and confirm that they return `2.3.0` and a tarball URL:
 
 ```bash
 npm view motionloom version --registry=https://registry.npmjs.org/
-npm view motionloom@2.1.0 name version license dist.tarball dist.shasum --json \
+npm view motionloom@2.3.0 name version license dist.tarball dist.shasum --json \
   --registry=https://registry.npmjs.org/
 ```
 
@@ -76,7 +76,7 @@ Then test installation in a clean temporary directory:
 TMP_DIR="$(mktemp -d)"
 cd "$TMP_DIR"
 npm init --yes
-npm install motionloom@2.1.0
+npm install motionloom@2.3.0
 motionloom --help
 motionloom doctor
 ```

package/examples/agent-consumer/README.md

@@ -0,0 +1,18 @@
+# Agent consumer fixtures
+
+This example set is a small, machine-readable map of how an Agent should consume MotionLoom. It is intentionally not a fake demo application and it does not claim user approval. Each case points to a repository artifact or a real runtime harness and states its evidence level.
+
+Run the offline contract checks first:
+
+```text
+motionloom discovery check --root . --json
+python3 tests/scripts/test_consumer_fixtures.py
+```
+
+For the browser-backed runtime cases, install the repository dependencies and run:
+
+```text
+npm run runtime:test
+```
+
+The real runtime harness emits deterministic scrub points at 0/50/100% for Rive, GSAP and Framer Motion. The Lottie and dotLottie cases are asset/package contracts; they must not be described as runtime-verified unless corresponding runtime evidence exists in the task bundle. The body-rig and continuity cases exercise structure and cross-scene semantics.

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

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

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

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

package/examples/agent-consumer/fixture-manifest.json

@@ -0,0 +1,82 @@
+{
+  "schema_version": "1.0",
+  "fixture_set": "agent-consumer-smoke",
+  "purpose": "Show Agents how to select an animation capability, locate evidence and preserve review boundaries.",
+  "repository_root": "..",
+  "cases": [
+    {
+      "id": "lottie-json-source-bound",
+      "framework": "lottie",
+      "category": "asset-runtime",
+      "source": "src/output/browser-review-smoke/animation.json",
+      "manifest": "src/output/browser-review-smoke/manifest.json",
+      "verification": "python3 scripts/validate-lottie.py src/output/browser-review-smoke/animation.json",
+      "evidence_level": "asset-contract",
+      "expected": "source_binding and Lottie structural validation; runtime acceptance still requires runtime evidence"
+    },
+    {
+      "id": "dotlottie-package",
+      "framework": "dotlottie",
+      "category": "asset-package",
+      "source": "src/output/browser-review-smoke/animation.json",
+      "manifest": "src/output/browser-review-smoke/manifest.json",
+      "verification": "node scripts/to-dotlottie.mjs --scene-dir src/output/browser-review-smoke --output <temporary-output>/animation.lottie",
+      "evidence_level": "package-contract",
+      "expected": "manifest.json selects the initial animation and the archive validates without system zip"
+    },
+    {
+      "id": "rive-runtime",
+      "framework": "rive",
+      "category": "browser-runtime",
+      "source": "tests/runtime-harness/main.jsx",
+      "evidence": "artifacts/runtime-adapters/rive/runtime-evidence.json",
+      "verification": "RUNTIME_FRAMEWORKS=rive npm run runtime:test",
+      "evidence_level": "runtime-verified-fixture",
+      "expected": "real browser adapter, ready=true, runtime state and 0/50/100 snapshots"
+    },
+    {
+      "id": "gsap-runtime",
+      "framework": "gsap",
+      "category": "browser-runtime",
+      "source": "tests/runtime-harness/main.jsx",
+      "evidence": "artifacts/runtime-adapters/gsap/runtime-evidence.json",
+      "verification": "RUNTIME_FRAMEWORKS=gsap npm run runtime:test",
+      "evidence_level": "runtime-verified-fixture",
+      "expected": "real browser adapter, ready=true, runtime state and 0/50/100 snapshots"
+    },
+    {
+      "id": "framer-motion-runtime",
+      "framework": "framer-motion",
+      "category": "browser-runtime",
+      "source": "tests/runtime-harness/main.jsx",
+      "evidence": "artifacts/runtime-adapters/framer-motion/runtime-evidence.json",
+      "verification": "RUNTIME_FRAMEWORKS=framer-motion npm run runtime:test",
+      "evidence_level": "runtime-verified-fixture",
+      "expected": "real browser adapter, ready=true, runtime state and 0/50/100 snapshots"
+    },
+    {
+      "id": "body-rig",
+      "framework": "svg-cutout-rig",
+      "category": "body-animation",
+      "source": "assets/library/avatar-base.svg",
+      "verification": "python3 src/rig/cutout_rig.py build --input assets/library/avatar-base.svg --output <temporary-output>/rigged.svg",
+      "evidence_level": "structure-verified-fixture",
+      "expected": "named anatomy, pivot markers and parent-first hierarchy remain inspectable"
+    },
+    {
+      "id": "continuity-multiscene",
+      "framework": "framework-neutral",
+      "category": "continuity",
+      "source": "tests/fixtures/continuity-multiscene",
+      "evidence": "tests/fixtures/continuity-multiscene/continuity-report.json",
+      "verification": "python3 scripts/intelligence.py continuity validate --report tests/fixtures/continuity-multiscene/continuity-report.json",
+      "evidence_level": "semantic-structure-fixture",
+      "expected": "scene-01 and scene-02 share continuity while scene-02-drift remains an explicit negative case"
+    }
+  ],
+  "review_boundary": {
+    "approval": false,
+    "user_review_required": true,
+    "pr_side_effects": "explicit-confirmation"
+  }
+}