motionloom 2.0.0 → 2.2.0

package/ROADMAP.md

@@ -0,0 +1,36 @@
+# MotionLoom Roadmap
+
+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.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, 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 | 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 | 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
+
+MotionLoom will remain project-bound, evidence-first and review-first. Heuristics may prioritize risk but cannot become approval. Attestations may prove signer and byte identity but cannot replace a user. Dev Lab remains a post-render handoff in the pipeline rather than a separate Skill with its own authority. Framework support will be promoted only after real adapter evidence and cross-platform checks pass.
+
+## Metrics that matter
+
+The project will track acceptance precision, false-approval rate, provenance completeness, replay success, time-to-fix, correction count, first-pass acceptance and rerender avoidance. Metrics must remain tied to labeled fixtures or user-confirmed review records; synthetic scores will not be presented as human visual approval.
+
+## Explicitly out of scope
+
+MotionLoom will not silently open or push pull requests, claim visual approval from a signature, hide a missing runtime behind a static placeholder, copy memory across projects, or treat a public asset catalog as a license authority. See [SECURITY.md](SECURITY.md), [CONTRIBUTING.md](CONTRIBUTING.md) and the [trust-boundary reference](references/signed-attestation.md) before proposing a roadmap change.
+
+## Proposing a roadmap change
+
+Open a feature request with the problem, affected Agent workflow, proposed contract, evidence needed, failure modes and how user authority is preserved. A roadmap proposal that cannot explain its trust boundary is not ready for implementation.

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Security fixes |
+|---|---|
+| `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 |
+
+## Reporting a vulnerability
+
+Please do not open a public issue for an exploitable vulnerability, credential exposure, path escape, evidence-bypass bug or supply-chain concern. Use [GitHub Private Vulnerability Reporting](https://github.com/lenhonbp/MotionLoom/security/advisories/new) when available. Include the affected version/commit, operating system, minimal reproduction, impact and a proposed mitigation if known. Redact project names, tokens, private assets, private keys and customer data.
+
+If private reporting is unavailable, open a minimal issue titled **Security contact requested** without exploit details and ask the maintainer to enable a private channel. The maintainer will acknowledge a valid report, triage severity, coordinate a fix and publish a release note when disclosure is safe.
+
+## Security boundaries
+
+MotionLoom can read and write files in the host project, invoke runtimes and prepare Git operations. The npm CLI does not silently push, open a PR or turn evidence into approval. Treat project context, artifact bundles, trust policies, private keys and browser sessions as sensitive. Keep managed signing keys outside the repository and never use CI fixture keys as production trust anchors.
+
+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.2.0 release note](docs/releases/2.2.0.md) for the current threat model and limitations.
+
+## CI/CD controls
+
+GitHub Actions workflows default to read-only repository permissions. The publication workflow is manual-only, uses the protected `npm-release` environment, requests OIDC only for the release job, and keeps npm credentials in environment secrets. Dependency updates are proposed by Dependabot as pull requests rather than applied directly to `main`.

package/SKILL.md

@@ -7,30 +7,49 @@ description: >-
   validate, review, or deliver animation inside an existing project.
 license: MIT
 metadata:
-  version: "2.0.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"
 ---
 
 # MotionLoom Skill
 
+> Public repository: [github.com/lenhonbp/MotionLoom](https://github.com/lenhonbp/MotionLoom) · npm: [motionloom](https://www.npmjs.com/package/motionloom) · release navigation: [CHANGELOG.md](CHANGELOG.md) · future work: [ROADMAP.md](ROADMAP.md)
+
 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.
 
 ## Required workflow
 
-1. **Understand** — read the host project manifest and run `bash scripts/analyze.sh <project-path>`. Load `project-context.json` from the audited project. If context is missing or ambiguous, stop at `needs_context`.
+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.
 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.
 4. **Generate** — use the matching template or rig implementation. For body animation, preserve named anatomy, pivot and parent-first hierarchy.
-5. **Render** — run `bash scripts/render.sh <scene>` 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.
+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 `python3 scripts/review-hook.py validate --task-dir artifacts/<task-id>`, `python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/<task-id> --iterations 25 --threshold-ms 500`, `bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>`, the independent attestation verifier, `python3 scripts/report-contract.py --root . --scenes-file <changed-scenes> --require-attestation`, `python3 scripts/quality-gate.py --scene <scene> --context <context-path> --task-dir artifacts/<task-id> --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation`, and `python3 scripts/skill-doctor.py --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 `TASK_DIR=artifacts/<task-id> bash scripts/pr.sh <scene>`. 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
+
+MotionLoom does not treat chat history as durable project memory. At the beginning of an animation task, load `.motionloom/project-memory.json`, validate its project identity and freshness, then recover the current project context. The memory records motion principles, asset/runtime policy, accepted and rejected decisions, user-confirmed remediation outcomes and invalidation metadata. It must remain task/project-bound and must never be copied across projects merely because the files look similar.
+
+Use the cross-platform CLI surface:
+
+```text
+motionloom memory init --project-root <project>
+motionloom memory inspect --project-root <project> --json
+motionloom memory refresh --project-root <project> --json
+motionloom memory recover --project-root <project> --json
+motionloom memory validate --project-root <project> --json
+```
+
+Only user-confirmed decisions and outcomes may become durable remediation memory. A stale or mismatched memory must produce a machine-readable failure/recovery state; it must not silently influence generation or approval. Ubuntu, macOS and Windows are supported through the Node CLI wrapper and Python path APIs. Do not require Bash, fixed `/tmp` paths, POSIX separators or system `zip`/`unzip` in the npm command surface.
 
 ## Progressive disclosure
 
@@ -43,6 +62,7 @@ Treat every animation request as a production task, not as an isolated asset-gen
 - 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
 
@@ -57,6 +77,8 @@ Treat every animation request as a production task, not as an isolated asset-gen
 - 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
@@ -70,12 +92,38 @@ Every production `src/output/<scene>/manifest.json` must include a `source_bindi
 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
-# Package a Lottie JSON scene as a dotLottie v2 archive.
-bash scripts/to-dotlottie.sh <scene> [output.lottie]
+# Package a Lottie JSON scene as a dotLottie v2 archive (Node/fflate; no system zip required).
+node scripts/to-dotlottie.mjs --scene-dir src/output/<scene> --output src/output/<scene>/animation.lottie
+
+# Initialize and recover durable project memory.
+motionloom memory init --project-root <project-path>
+motionloom memory recover --project-root <project-path> --json
 
 # Run the official runtime adapters in a real browser harness.
 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>
@@ -96,7 +144,7 @@ python3 scripts/attestation-verifier.py --attestation artifacts/<task-id>/attest
 
 `runtime-evidence.json` records the runtime package, three scrub points, observed state and generated snapshots. A template alone is never enough to upgrade a framework from `scaffold_only` to `verified`.
 
-For an observability-enabled run, `bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>` regenerates the real-browser evidence and writes telemetry under the task bundle. `scripts/evidence-verifier.py` then checks task/scene/hash/path/age bindings with stable machine-readable output. A verifier pass means the evidence is internally consistent; it does not mean the animation is approved.
+For an observability-enabled run, use the platform-neutral runtime telemetry entrypoint exposed by the package. It regenerates the real-browser evidence and writes telemetry under the task bundle. `scripts/evidence-verifier.py` then checks task/scene/hash/path/age bindings with stable machine-readable output. A verifier pass means the evidence is internally consistent; it does not mean the animation is approved.
 
 ## Output contract
 

package/SUPPORT.md

@@ -0,0 +1,23 @@
+# Support
+
+MotionLoom is a public Agent Skill and npm package. Start with the [README](README.md), [SKILL.md](SKILL.md), [production checklist](docs/CHECKLIST.md), [framework selection guide](docs/FRAMEWORK-SELECTION.md) and [runtime capability reference](references/runtime-capability.md).
+
+## Choose the right channel
+
+| Situation | Use |
+|---|---|
+| A reproducible defect in code, schema, CLI or runtime adapter | [Bug report](https://github.com/lenhonbp/MotionLoom/issues/new?template=bug_report.yml) |
+| A proposed capability or workflow improvement | [Feature request](https://github.com/lenhonbp/MotionLoom/issues/new?template=feature_request.yml) |
+| A security or privacy concern | [SECURITY.md](SECURITY.md), never a public issue with exploit details |
+| A documentation correction | Open a small pull request or use a documentation issue |
+| A usage question | Search the README/docs first, then open an issue with the exact command and environment if no answer exists |
+
+## Troubleshooting order
+
+Run `motionloom doctor --json`, confirm Node/Python versions, inspect the JSON exit code, check that the task bundle and project context belong to the same project, and rerun the smallest relevant contract test. A `needs_context`, `stale`, `invalid` or `blocked` state is an actionable result, not an invitation to bypass the gate.
+
+When asking for help, include sanitized command output, the operating system, package version, runtime/framework, task state and a minimal fixture. Do not upload `.motionloom/project-memory.json`, private project context, private assets, credentials, signing keys or browser session data unless they are synthetic and safe to share.
+
+## Maintainer response
+
+The project is maintained on a best-effort basis. A response may request a reproducible fixture or a contract-level test before implementation. Feature requests are evaluated against the [roadmap](ROADMAP.md), user-control principles and the project's ability to produce verifiable runtime evidence.

package/agent-card.json

@@ -1,10 +1,20 @@
 {
   "card_version": "1.0",
   "name": "motionloom",
-  "version": "2.0.0",
-  "description": "Project-aware animation production with 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",
+    "project.memory.refresh",
+    "project.memory.recover",
+    "project.memory.validate",
+    "project.memory.record-decision",
+    "project.memory.record-outcome",
     "project.graph.build",
     "project.graph.validate",
     "motion.plan",
@@ -35,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",
@@ -56,6 +72,7 @@
     "source-asset"
   ],
   "output_artifacts": [
+    "agent-discovery-report",
     "project-context",
     "motion-spec",
     "runtime-scene",
@@ -79,7 +96,11 @@
     "replay-bundle",
     "semantic-lint-report",
     "semantic-lint-benchmark",
+    "visual-truth",
+    "remediation-history",
+    "remediation-summary",
     "hardening-audit-report",
+    "project-memory",
     "continuity-report",
     "fix-plan",
     "pr-patch"
@@ -124,16 +145,26 @@
     }
   ],
   "entrypoints": {
-    "analyze": "bash scripts/analyze.sh <project-path>",
+    "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",
+    "memory_refresh": "motionloom memory refresh --project-root <project-path> --json",
+    "memory_recover": "motionloom memory recover --project-root <project-path> --json",
+    "memory_validate": "motionloom memory validate --project-root <project-path> --json",
+    "memory_decision": "motionloom memory record-decision --project-root <project-path> --id <id> --status accepted|rejected --summary <summary> --user-confirmed",
+    "memory_outcome": "motionloom memory record-outcome --project-root <project-path> --id <id> --result <result> --user-confirmed",
     "report_init": "python3 scripts/report.py init --task-id <id>",
     "report_collect": "python3 scripts/report.py collect --task-dir <dir>",
     "report_render": "python3 scripts/report.py render --task-dir <dir>",
     "skill_doctor": "python3 scripts/skill-doctor.py --json",
     "quality_gate": "python3 scripts/quality-gate.py --scene <scene> --context <path>",
     "manifest_bind_source": "python3 scripts/manifest.py bind-source --scene <scene> --source <file> --kind <kind> --authority <authority> --license <license>",
-    "dotlottie_package": "bash scripts/to-dotlottie.sh <scene> [output.lottie]",
+    "dotlottie_package": "motionloom manifest package-dotlottie --scene <scene> [--output <output.lottie>]",
     "runtime_adapter_test": "node scripts/runtime-adapters.mjs",
-    "runtime_telemetry": "bash scripts/capture-runtime-telemetry.sh <scene> artifacts/<task-id>",
+    "runtime_telemetry": "node scripts/capture-runtime-telemetry.mjs <scene> artifacts/<task-id>",
     "evidence_verify": "python3 scripts/evidence-verifier.py --scene-dir src/output/<scene> --task-dir artifacts/<task-id> --runtime-evidence runtime-adapters/runtime-evidence.json --max-age-days 1 --output artifacts/<task-id>/evidence-verifier-report.json",
     "intelligence_graph": "python3 scripts/intelligence.py graph build --task-dir artifacts/<task-id>",
     "intelligence_provenance": "python3 scripts/intelligence.py provenance build --task-dir artifacts/<task-id>",
@@ -150,9 +181,14 @@
     "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": "bash scripts/pr.sh <scene>"
+    "pr_prepare": "node scripts/pr.mjs <scene>"
   },
   "report_contract": {
     "required_sections": ["completed", "verified", "not_completed", "problems", "structure_review", "next_agent", "browser_review"],

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

@@ -2,7 +2,7 @@
 /**
  * MotionLoom npm entrypoint.
  * Style: Timeline Desk — terse command routing, explicit evidence verbs and
- * no hidden approval side effects. The CLI delegates to the shipped Python
+ * no hidden approval side effects. The CLI delegates to shipped Python/Node
  * contracts so npm installation and repository execution use one surface.
  */
 import { fileURLToPath } from "node:url";
@@ -13,8 +13,10 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PYTHON = process.env.MOTIONLOOM_PYTHON || (process.platform === "win32" ? "python" : "python3");
 
 const PYTHON_COMMANDS = {
-  analyze: "scripts/analyze.sh",
+  analyze: "scripts/analyze.py",
+  memory: "scripts/project-memory.py",
   attestation: "scripts/attestation.py",
+  "attestation-keygen": "scripts/attestation-keygen.py",
   "verify-attestation": "scripts/attestation-verifier.py",
   doctor: "scripts/skill-doctor.py",
   intelligence: "scripts/intelligence.py",
@@ -24,19 +26,29 @@ const PYTHON_COMMANDS = {
   "report-contract": "scripts/report-contract.py",
   report: "scripts/report.py",
   "review-hook": "scripts/review-hook.py",
+  devlab: "scripts/devlab.py",
+  "runtime-telemetry": "scripts/capture-runtime-telemetry.py",
+  render: "scripts/render.py",
+  pr: "scripts/pr.py",
   "validate-lottie": "scripts/validate-lottie.py",
   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.0.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...]
 
 Commands:
   doctor                 Validate the installed Skill package
-  analyze                Run project analysis (delegates to scripts/analyze.sh)
+  analyze                Run project analysis and refresh Project Memory
+  memory                 Initialize, inspect, refresh, recover or validate memory
   intelligence           Build or validate Intelligence Core artifacts
   attestation            Build/validate canonical signed-attestation artifacts
   verify-attestation     Verify an attestation against a trust policy
@@ -44,10 +56,26 @@ Commands:
   quality-gate           Run the strict scene acceptance gate
   report-contract        Validate task bundle completeness
   review-hook            Prepare or validate browser review handoff
+  devlab                 Prepare or serve the internal Dev Lab cross-platform
+  runtime-telemetry      Capture and externally verify runtime telemetry
   report                 Read or update task review reports
   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
+  motionloom memory recover --project-root .
+  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.
@@ -67,7 +95,7 @@ if (!script) {
   process.exit(2);
 }
 
-const executable = script.endsWith(".sh") ? "bash" : PYTHON;
+const executable = script.endsWith(".mjs") ? process.execPath : PYTHON;
 const result = spawnSync(executable, [resolve(ROOT, script), ...args], {
   cwd: ROOT,
   stdio: "inherit",

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

@@ -0,0 +1,33 @@
+# MotionLoom Current Status
+
+> **Authority:** This document describes the current repository contract. Historical audit snapshots and benchmark reports remain valuable evidence, but they must not be read as claims about the latest checkout.
+
+## Current release posture
+
+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.
+
+## Evidence levels
+
+| Capability | Current evidence level | What is actually proven | What is not implied |
+|---|---|---|---|
+| Lottie JSON and SVG cutout rig | End-to-end contract evidence | Context binding, source binding, runtime snapshots, Dev Lab review, quality gate and PR preflight have deterministic fixtures | Visual quality for every brand, asset or device |
+| Rive, GSAP and Framer Motion | Adapter and fixture evidence | Framework-specific runtime adapters and smoke checks can render representative scenes through browser/runtime paths | Equivalent coverage to the Lottie path across arbitrary projects |
+| Project Memory | Contract and relocation evidence | Stable project identity, atomic persistence, integrity guard, freshness states and path rebinding after relocation | Automatic correctness of an Agent's inferred decision |
+| Semantic intelligence | Deterministic evaluation evidence | Project graph, provenance, Motion IR, continuity, fix-plan and adversarial/deep-stress contracts; bounded analyzer reports scan budgets and truncation | Human-level design judgment, external-project product-value evidence or guaranteed first-pass acceptance |
+| Dev Lab | Review infrastructure evidence | Identity-bound candidate loading, deterministic scrub/snapshot, user checklist and review export | A visual editor, automatic approval or PR authorization |
+
+## Normative sources
+
+Use the following order when sources disagree:
+
+1. The active schemas, validators and executable tests define machine-enforced behavior.
+2. `SKILL.md`, `agent-card.json` and the current README define the Agent-facing contract.
+3. This status document defines current capability posture and evidence boundaries.
+4. Versioned release notes and focused audit reports explain a release or milestone at the time it was produced.
+5. Root-level historical audit snapshots are context only and must be labeled historical.
+
+## 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.