motionloom 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+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/).
+
+## [2.1.0] - 2026-08-13
+
+### Added
+
+- Durable, relocatable Project Memory with schema validation, atomic writes, canonical integrity and stable lifecycle exit codes.
+- Cross-platform npm CLI routing for Ubuntu, macOS and Windows without Bash-only user commands or system `zip`/`unzip` dependencies.
+- Memory loader integration for project analysis, reports, review hooks, handoff and downstream Agent continuity.
+- Ubuntu/macOS/Windows CI matrix for Project Memory recovery, CLI routing and npm tarball inspection.
+- Public repository governance documents, contribution workflow, security policy, support guide, roadmap, issue forms and pull-request template.
+
+### Fixed
+
+- Rebinding a relocated checkout no longer invalidates integrity merely because `project.root_path` changed.
+- Recovery atomically refreshes runtime path, repository and package metadata while preserving the durable project identity contract.
+
+### Verified
+
+- Full regression, Intelligence Core evaluation, Skill Doctor, strict quality gate, npm package dry-run and Dev Lab production build pass.
+- Relocation coverage includes Git remote identity, Unicode paths, spaces in paths, stale context and user-confirmed outcome invariants.
+
+See the [2.1.0 release note](docs/releases/2.1.0.md) for scope, trust boundaries and remaining work.
+
+## [2.0.0] - 2026-08-12
+
+### Added
+
+- DSSE-compatible Ed25519 signed attestation and fail-closed trust policy verification.
+- External verifier, attestation report contract and Dev Lab attestation rail.
+
+See the [2.0.0 release note](docs/releases/2.0.0.md).
+
+## Earlier releases
+
+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.1.0]: docs/releases/2.1.0.md
+[2.0.0]: docs/releases/2.0.0.md

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Code of Conduct
+
+## Our commitment
+
+We want MotionLoom to be a respectful, technically rigorous and welcoming project for people working on animation, developer tooling and Agent interoperability. Contributors are expected to participate constructively, assume good faith while examining evidence, and make room for different levels of experience.
+
+## Expected behavior
+
+Use clear and respectful language. Focus criticism on code, contracts, evidence and decisions rather than people. Explain disagreement with reproducible reasoning. Protect private project data, credentials and source assets. Give credit to upstream runtimes, asset authors and contributors.
+
+## Unacceptable behavior
+
+Harassment, discrimination, personal attacks, threats, doxxing, sexualized conduct, deliberate exposure of private data, spam, bad-faith manipulation of review evidence or attempts to bypass user authorization are not acceptable.
+
+## Enforcement
+
+Report a conduct concern privately through the repository's maintainer contact or a GitHub private vulnerability report when the concern involves safety or security. Do not include sensitive details in a public issue. Maintainers may remove content, request corrections, restrict participation or close contributions when necessary to protect the community.
+
+This code of conduct is adapted for MotionLoom from the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to MotionLoom
+
+Thank you for helping make animation workflows more reliable for coding agents. Contributions are welcome in code, schemas, tests, runtime adapters, documentation, fixtures and reproducible bug reports. Please read the [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md) before contributing.
+
+## Before opening an issue or pull request
+
+Search existing issues and documentation first. For a bug, include the operating system, Node/Python versions, exact command, minimal fixture or artifact bundle, expected behavior and observed output. Never attach private project context, credentials, private source assets or trust-policy private keys.
+
+For a feature, explain which Agent failure mode it addresses, which contract or schema changes, what evidence would demonstrate correctness, and how the change preserves explicit user approval. A template without a runtime or validation path is not sufficient for a production capability.
+
+## Local setup
+
+```bash
+git clone https://github.com/lenhonbp/MotionLoom.git
+cd MotionLoom
+npm install
+python3 -m pip install --requirement requirements.txt
+python3 scripts/skill-doctor.py --json
+```
+
+Node.js 18+ and Python 3.11+ are required. On Windows, use `python` if `python3` is not available or set `MOTIONLOOM_PYTHON` for the npm wrapper. Runtime adapter tests may require the Playwright browser installation described by the CI workflow.
+
+## Validation commands
+
+Run the smallest relevant checks while iterating, then run the complete suite before opening a pull request:
+
+```bash
+python3 -m py_compile scripts/*.py tests/scripts/*.py
+python3 tests/scripts/test_project_memory.py
+python3 tests/scripts/run_tests.py
+python3 scripts/eval-intelligence.py
+python3 scripts/skill-doctor.py --json
+npm run runtime:test
+npm publish --dry-run --access public
+```
+
+For changes to a scene or evidence contract, also run the appropriate report contract, browser-review validation, quality gate and `npm run audit:deep`. Keep generated local runtime state and temporary project memory out of the commit.
+
+## GitHub Actions and release environments
+
+Every pull request should pass the quality and documentation workflows. Security analysis may be skipped for an untrusted fork when GitHub cannot grant security-event permissions; the maintainer must review the resulting status before merge. Dev Lab changes produce a retained build artifact for inspection.
+
+The `release.yml` workflow is deliberately `workflow_dispatch`-only. Maintainers must configure the protected `npm-release` environment and its required reviewers before using it. The workflow accepts either an `NPM_TOKEN` environment secret or npm trusted publishing through GitHub OIDC (`id-token: write`). Never put an npm token in repository variables, source files or pull-request logs. Creating a GitHub release is an explicit dispatch input.
+
+## Pull request expectations
+
+Use a focused branch and a conventional commit-style title such as `feat(memory): ...`, `fix(runtime): ...` or `docs: ...`. A pull request should explain the user-visible change, list changed contracts, identify platform coverage, link tests and state limitations or remaining warnings. Schema changes must include fixtures and backward/forward compatibility notes where relevant.
+
+Do not claim a runtime is verified unless real adapter evidence exists. Do not convert a heuristic, benchmark, valid signature or successful build into an approval statement. Do not change `approval` to `true` in fixtures or bypass the user-review gate to make a test pass.
+
+## Review and merge policy
+
+CI must pass before merge. Changes that affect `SKILL.md`, `agent-card.json`, schemas, quality gates, evidence verification, attestations, runtime adapters or Git side effects require explicit contract review. Maintainers may request a focused adversarial fixture when a change can affect stale evidence, cross-task contamination, path safety or approval invariants.
+
+The repository's PR template is a checklist, not a substitute for evidence. Maintainers merge only after the behavior, documentation and trust boundary are clear.
+
+## Release process
+
+1. Update `CHANGELOG.md` and a dedicated `docs/releases/<version>.md` note.
+2. Update `package.json`, `SKILL.md`, `agent-card.json` and relevant schema/reference versions.
+3. Run the full validation suite and `npm publish --dry-run --access public`.
+4. Create a local commit and obtain explicit maintainer confirmation before pushing.
+5. Publish from the authenticated maintainer workstation, then verify the npm version and GitHub release state.
+
+See [ROADMAP.md](ROADMAP.md) for future work and [SUPPORT.md](SUPPORT.md) for help with setup or usage.

package/README.md

@@ -1,179 +1,232 @@
 # MotionLoom
 
-A coding-agent skill for professional animation development: motion, character body rigs and assets. It does not guess — it **understands the host project, plans from a signed motion spec, generates from vetted source assets, renders everything in the Dev Lab for live testing, and only then confirms into a pull request**.
+[![CI](https://github.com/lenhonbp/MotionLoom/actions/workflows/quality.yml/badge.svg)](https://github.com/lenhonbp/MotionLoom/actions/workflows/quality.yml)
+[![npm version](https://img.shields.io/npm/v/motionloom?logo=npm&logoColor=white)](https://www.npmjs.com/package/motionloom)
+[![npm downloads](https://img.shields.io/npm/dm/motionloom?logo=npm&logoColor=white)](https://www.npmjs.com/package/motionloom)
+[![License](https://img.shields.io/github/license/lenhonbp/MotionLoom)](LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skill-compatible-5B5BD6)](https://agentskills.io/specification)
+
+**Project-aware animation production and runtime verification for coding agents.**
+
+MotionLoom is an independent open-source Agent Skill for building UI motion, Lottie and dotLottie scenes, Rive/GSAP/Framer Motion experiences, character body rigs and traceable animation assets inside an existing project. It does not treat animation as an isolated prompt: it binds the work to the host project's context, records decisions and provenance, renders through a real runtime, hands the exact candidate to an internal Dev Lab, and stops before Git side effects until the user approves.
+
+> **MotionLoom is not an auto-approval layer.** A valid signature, a passing heuristic, or a successful render proves only the contract it checks. Visual quality, intent, accessibility and PR authorization remain reviewable human decisions.
+
+> **Release posture:** the repository source and `package.json` are at **2.1.0**. The public npm registry currently serves **2.0.0** and no GitHub tag/Release for 2.1.0 exists yet; a maintainer must perform the protected manual release before the registry and GitHub release state change.
+
+## Why MotionLoom
+
+Most animation helpers optimize for generating one asset quickly. That breaks down when an Agent has to work in a real product: it can lose the project's motion language, select an untraceable asset, render a placeholder instead of the target runtime, mix evidence from another task, or open a PR before the user has inspected the result.
+
+MotionLoom turns that fragile sequence into a bounded production system. Its durable Project Memory survives long gaps between animation tasks and project relocation; its Intelligence Core keeps context, provenance, capability selection and Motion IR connected; its runtime adapters produce evidence instead of prose claims; and its Dev Lab is a mandatory review handoff rather than a separate Agent or a static demo catalog.
+
+## What it provides
+
+| Capability | What the Agent gets | What MotionLoom refuses to do |
+|---|---|---|
+| **Project binding** | Project context, package/design-token discovery and durable `.motionloom/project-memory.json` | Reuse memory across projects or silently continue through missing context |
+| **Motion planning** | Framework-aware Motion Spec, timing/easing/accessibility budgets and framework selection | Present a template as a project-integrated result |
+| **Asset provenance** | Required `source_binding`, authority, license and SHA-256 traceability | Promote unknown, unlicensed or placeholder production assets |
+| **Runtime truth** | Lottie/dotLottie, SVG cutout rig, Rive, GSAP and Framer Motion evidence from real runtime paths | Call scaffold, static validation or a heuristic score visual approval |
+| **Agent intelligence** | Project graph, provenance, Motion IR, replay, semantic lint, continuity and fix plan | Convert confidence, benchmark output or warnings into approval |
+| **Human review** | Exact candidate URL, frame checkpoints, checklist, review artifact and handoff report in Dev Lab | Confirm, push or open a PR without explicit user authorization |
+
+## The production contract
+
+```mermaid
+flowchart LR
+    A[Host project] --> B[Analyze + Project Memory]
+    B --> C[Context-bound Motion Spec]
+    C --> D[Source binding + asset provenance]
+    D --> E[Generate / rig / adapt]
+    E --> F[Real runtime render]
+    F --> G[Intelligence Core + evidence]
+    G --> H[Dev Lab browser review]
+    H --> I{User approved?}
+    I -- changes requested --> D
+    I -- no --> J[Report blocked / needs fix]
+    I -- yes --> K[Quality gate + attestation]
+    K --> L[PR preflight; side effects still explicit]
+```
+
+Every handoff is machine-readable. The typical bundle under `artifacts/<task-id>/` includes the task ledger, context hash, motion spec, manifest, runtime snapshots, telemetry, project graph, provenance, lint and continuity reports, fix plan, browser-review candidate, review decision, execution report and next-Agent handoff.
 
-## Install from npm
+## Quick start
 
-MotionLoom is distributed as the `motionloom` npm package. The package ships the installable Skill contract, framework adapters, Intelligence Core schemas, evidence verifiers and a small CLI wrapper around the canonical Python scripts.
+### Install the public CLI
 
 ```bash
 npm install --global motionloom
-motionloom doctor
+motionloom doctor --json
 motionloom --help
 ```
 
-The CLI requires **Node.js 18+** and **Python 3.11+**. Installation does not grant approval, commit changes or open a pull request; browser review and explicit repository-side-effect confirmation remain mandatory.
+MotionLoom supports **Node.js 18+** and **Python 3.11+** on Ubuntu, macOS and Windows. The npm wrapper is the cross-platform surface: it discovers the platform Python executable and delegates to the same canonical contracts used by a repository checkout.
 
-## Quick start
+### Start from a real project
+
+Run the first commands from the project that owns the animation. Do not copy the example context into production; generate a fresh context from the host project.
 
 ```bash
-# 1. Understand the project
-bash scripts/analyze.sh /path/to/your/project
-
-# 1b. Start a transparent task ledger for Agent/human handoff
-python3 scripts/report.py init --task-id onboarding-wave \
-  --scene my-scene --intent "Character wave in onboarding" \
-  --project-name your-project
-
-# 2. Plan & sign a spec (example: a loading animation)
-python3 src/core/spec.py generate loading --context /path/to/your/project/project-context.json \
-  --output motion-spec.json --loop
-
-# 3. Generate a body rig, then pose it
-python3 src/rig/cutout_rig.py build \
-  --input assets/library/avatar-base.svg --output rigged.svg
-python3 src/rig/cutout_rig.py pose rigged.svg --pose walk \
-  --duration 1.2 --fps 30 --out walk.json
-
-# 3b. Bind the scene source to an authoritative provenance record
-python3 scripts/manifest.py bind-source --scene my-scene \
-  --source animation.json --kind project \
-  --authority "host project manifest" --license MIT
-
-# 4. Render runtime verification snapshots (0/50/100%; placeholders fail)
-bash scripts/render.sh my-scene
-
-# 4b. Package the Lottie source as a dotLottie v2 archive when required
-bash scripts/to-dotlottie.sh my-scene
-
-# 4c. Verify Rive, GSAP and Framer Motion through the real browser harness
-node scripts/runtime-adapters.mjs
-
-# 4d. Capture runtime telemetry and verify evidence bindings externally
-bash scripts/capture-runtime-telemetry.sh my-scene artifacts/onboarding-wave
-
-# 4e. Derive and verify a signed task-bound statement against a managed trust policy
-python3 scripts/attestation.py statement --scene-dir src/output/my-scene \
-  --task-dir artifacts/onboarding-wave --context /path/to/your/project/project-context.json \
-  --output artifacts/onboarding-wave/attestation-statement.json
-python3 scripts/attestation.py build --statement artifacts/onboarding-wave/attestation-statement.json \
-  --private-key <managed-ed25519-key> --key-id <key-id> \
-  --output artifacts/onboarding-wave/attestation.json
-python3 scripts/attestation-verifier.py --attestation artifacts/onboarding-wave/attestation.json \
-  --trust-policy artifacts/onboarding-wave/trust-policy.json \
-  --expected-task-id onboarding-wave --expected-scene my-scene
-
-# 5. Boot the Dev Lab to test & fix interactively
-bash scripts/devlab.sh my-scene
-
-# 6. Run the acceptance gate, then confirm and ship
-python3 scripts/quality-gate.py --scene my-scene \
-  --context /path/to/your/project/project-context.json \
-  --task-dir artifacts/onboarding-wave --require-telemetry --require-attestation
-
-# 6. Collect evidence and render the user-facing report
-python3 scripts/report.py collect --task-dir artifacts/onboarding-wave
-python3 scripts/report.py render --task-dir artifacts/onboarding-wave
-
-# 7. Confirm and ship only after review
-bash scripts/pr.sh my-scene
-```
+cd /path/to/your/project
 
-The kit is intended to run from a Git clone. Copy `project-context.example.json` only as a schema reference; always generate the real context with `scripts/analyze.sh` against the host project. Do not commit a context containing a temporary path or another project's brand tokens.
+# Understand the project and bootstrap/recover durable memory.
+motionloom analyze . --init-memory
+motionloom memory inspect --project-root . --json
 
-For a reproducible review fixture, keep `project-context.json`, `quality-report.json`, `review.json`, `execution-report.json`, `handoff.json` and `artifact-manifest.json` under the repository's `artifacts/<task-id>/` directory. `scripts/pr.sh` rejects task bundles outside the repository, requires the task scene to match the requested scene, runs the semantic report check, and stages the evidence bundle together with the scene. This prevents a gate from consuming evidence that is omitted from the resulting commit.
+# Bound traversal when the host project is large; truncation is reported, never hidden.
+motionloom analyze . --max-files 2500 --max-bytes 25000000 --max-seconds 10
 
-Runtime adapter evidence can be bound to a scene and its exact source/manifest bytes:
+# Plan and generate the scene using the selected framework.
+python3 /path/to/MotionLoom/src/core/spec.py generate loading \
+  --context project-context.json --output motion-spec.json --loop
 
-```bash
-RUNTIME_SCENE=my-scene \
-RUNTIME_SOURCE_PATH=src/output/my-scene/animation.json \
-RUNTIME_MANIFEST_PATH=src/output/my-scene/manifest.json \
-node scripts/runtime-adapters.mjs
+# Render real runtime evidence and prepare the Dev Lab review handoff.
+motionloom render loading
+motionloom devlab loading
+
+# Validate the exact task bundle before any Git side effect.
+motionloom quality-gate --scene loading \
+  --context project-context.json \
+  --task-dir artifacts/loading-task \
+  --require-browser-review --require-intelligence --require-p1 \
+  --require-benchmark --require-telemetry --require-attestation
+
+# Local-only by default. A user must review and explicitly authorize side effects.
+motionloom pr loading --task-dir artifacts/loading-task
 ```
 
-When these variables are supplied, `runtime-evidence.json` records `scene`, `source_sha256` and `manifest_sha256`; the quality gate rejects evidence copied from another scene or generated against an older manifest.
+For a source checkout, use `git clone https://github.com/lenhonbp/MotionLoom.git`, run `npm install`, and replace the global command with `node bin/motionloom.mjs` or the corresponding Python/Node script shown in the [development guide](CONTRIBUTING.md).
 
-### Intelligence Core v0.1 + P1 feedback intelligence + trust-boundary hardening + evidence interoperability + signed attestation
+## Durable Project Memory
 
-After render and before strict acceptance, build the task-bound Intelligence Core artifacts. They give an Agent a single relationship graph, step-level provenance, framework-neutral Motion IR, capability selection policy and deterministic replay inventory instead of requiring it to infer relationships from prose and unrelated files:
+Project Memory is the continuity layer for Agents that return to animation after many unrelated tasks or a new context window. It stores project identity, motion principles, asset and runtime policy, accepted/rejected decisions, user-confirmed outcomes and freshness/invalidation state in `.motionloom/project-memory.json`.
 
 ```bash
-python3 scripts/intelligence.py motion-ir build --task-dir artifacts/onboarding-wave
-python3 scripts/intelligence.py graph build --task-dir artifacts/onboarding-wave
-python3 scripts/intelligence.py provenance build --task-dir artifacts/onboarding-wave
-python3 scripts/intelligence.py replay capture --root . --task-dir artifacts/onboarding-wave
-python3 scripts/intelligence.py semantic-lint build --task-dir artifacts/onboarding-wave
-python3 scripts/intelligence.py semantic-lint benchmark --task-dir artifacts/onboarding-wave \
-  --iterations 25 --threshold-ms 500
-bash scripts/capture-runtime-telemetry.sh my-scene artifacts/onboarding-wave
-python3 scripts/intelligence.py continuity build --task-dirs artifacts/onboarding-wave
-python3 scripts/intelligence.py fix-plan build --task-dir artifacts/onboarding-wave \
-  --reports semantic-lint-report.json continuity-report.json
-python3 scripts/quality-gate.py --scene my-scene \
-  --context /path/to/your/project/project-context.json \
-  --task-dir artifacts/onboarding-wave \
-  --require-browser-review --require-intelligence --require-p1 --require-benchmark --require-telemetry --require-attestation
-python3 scripts/eval-intelligence.py
+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
 ```
 
-Semantic lint reports intent, timing, easing, accessibility and performance findings with severity, confidence and evidence. The benchmark records rule coverage and p95 execution time against a 500 ms default threshold; it does not claim to measure human visual quality. Continuity analysis checks context and transition drift across an ordered scene set. `fix-plan.json` converts findings into root cause, affected artifacts, selective rerun scope and verification commands; it does not auto-approve a scene. The 1.8.0 hardening layer rejects symlinked or cross-task Intelligence artifacts, binds replay to task identity, chooses one deterministic passing report bundle per scene, and makes the Dev Lab reject cross-origin or mismatched task/candidate evidence. The 1.9.0 evidence layer captures scrub-point, RAF timing, runtime-state and source/manifest/Motion IR hash bindings, then lets a read-only external verifier reject stale, tampered, cross-task or path-escaped evidence. The 2.0.0 attestation layer signs canonical task-bound hashes with a DSSE-compatible Ed25519 envelope and checks signer lifecycle through fail-closed trust policy. A verifier pass still means integrity only: runtime assertions, Dev Lab review and user consent remain mandatory; `approval` is always `false`. See [Intelligence Core](references/intelligence-core.md), [signed attestation reference](references/signed-attestation.md), the [1.9.0 threat model](docs/audits/1.9.0-evidence-interoperability-threat-model.md) and the [2.0.0 release note](docs/releases/2.0.0.md).
+The memory integrity hash excludes only the mutable checkout path; Git remote or package identity remains the project binding. Direct edits to durable content fail closed. A stale, invalid, missing or cross-project memory produces a machine-readable recovery state and cannot silently influence generation or approval. Durable decisions and outcomes require `--user-confirmed`.
 
-## Pipeline
+Read the [Project Memory schema](schemas/project-memory.schema.json), [2.1.0 release note](docs/releases/2.1.0.md) and [Skill instructions](SKILL.md) for the full lifecycle.
 
-| Step | Module | What it does |
-|------|--------|--------------|
-| 01 · Understand | `src/core/analyzer.py` | Reads package.json, design tokens and existing motion language; emits `project-context.json` inside the target project |
-| 02 · Plan | `src/core/spec.py` | Generates & validates the motion spec against the framework matrix, easing canon and performance budget |
-| 03 · Source | `assets/library/` | Vetted, traceable source assets with an attribution table — the authoritative geometry |
-| 04 · Generate | `src/rig/cutout_rig.py`, `templates/` | Canonical templates per framework; 20-bone cutout body rigs with parent-first order |
-| 05 · Dev Lab | `dev-lab/` | Self-contained static workbench: preview rendered evidence, scrub, quality checklist, fix notes, review export |
-| 06 · Confirm → PR | `scripts/pr.sh` | Commits scene + spec + snapshots, opens the PR with an evidence body |
+## Verified runtime matrix
 
-## Repository layout
+| Runtime or format | Capability level | Evidence path |
+|---|---:|---|
+| Lottie JSON | Contract verified | Runtime snapshot renderer and manifest validation in repository fixtures |
+| dotLottie v2 | Contract verified | Node/`fflate` packaging, manifest entry and checksum validation |
+| SVG cutout body rig | Contract verified | Parent-first hierarchy, named anatomy and pose evidence in repository fixtures |
+| Rive Canvas | Fixture verified | Browser adapter, state-machine/input binding and representative snapshots |
+| GSAP | Fixture verified | Browser adapter, deterministic timeline scrub and representative snapshots |
+| Framer Motion | Fixture verified | Browser adapter, reduced-motion checks and representative snapshots |
+| Spine | Scaffold only | Requires a framework-specific runtime adapter and evidence |
+| Three.js | Scaffold only | Requires a framework-specific runtime adapter and evidence |
 
-| Path | Purpose |
-|------|---------|
-| `SKILL.md` | The agent-skill definition (installable into any coding agent) |
-| `src/core/` | Analyzer, spec validator, snapshot renderer |
-| `src/rig/` | Cutout character body rig engine |
-| `templates/` | Canonical Lottie / Rive / GSAP / Framer Motion templates |
-| `assets/library/` | Vetted source assets + attribution, including the MIT Rive adapter fixture |
-| `scripts/` | Pipeline CLI plus Intelligence Core (`analyze`, `render`, `devlab`, `pr`, `quality-gate`, `validate-lottie`, `to-dotlottie`, `runtime-adapters`, `capture-runtime-telemetry`, `evidence-verifier`, `attestation`, `attestation-verifier`, `attestation-keygen`, `skill-doctor`, `report`, `report-contract`, `intelligence`, `eval-intelligence`) |
-| `dev-lab/` | Self-contained static Dev Lab + Playwright snapshot harness |
-| `agent-card.json` | Capability discovery, runtime levels and side-effect policy for other Agents |
-| `schemas/` | Task, report, artifact-manifest, scene-manifest, handoff, Intelligence Core, signed-attestation and trust-policy JSON Schemas |
-| `references/` | Progressive-disclosure contracts for reporting, runtime capability, dotLottie packaging and Intelligence Core |
-| `artifacts/<task-id>/` | Per-task ledger, evidence, review, issue register and handoff bundle |
-| `tests/` | Deterministic engine tests |
-| `.github/workflows/quality.yml` | CI that re-runs the quality gate on every PR |
+Capability selection uses `agent-card.json` and the capability registry. A runtime is not promoted from `scaffold_only` to `verified` because a template exists; its adapter evidence and CI contract must pass.
+
+## Evidence, trust and review
+
+MotionLoom keeps distinct layers distinct:
 
-## The quality gate
+| 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 |
+| 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 |
+| Dev Lab review | The user saw the exact candidate and recorded a decision | A future candidate is automatically approved |
 
-A scene is only "ready" when, together, the Dev Lab checklist passes, runtime snapshot frames exist at 0/50/100%, the context-bound JSON spec matches the implementation, brand tokens come from the target project's `project-context.json`, the required `source_binding` traces `manifest.file` to an authoritative source with a matching checksum, the P1 reports have been validated and the semantic-lint benchmark is below threshold. For strict observability runs, runtime telemetry and the external verifier report must also pass their identity, freshness and hash checks; for production trust runs, the signed attestation must verify against an active trust-policy key and bind the same task/scene/material hashes. A warning or valid signature may require human review and a selective fix; neither is silently converted into approval. CI reproduces these checks on every PR — see [CHECKLIST.md](docs/CHECKLIST.md).
+`approval` remains `false` in attestation and verifier artifacts. The default PR mode is local-only (`OPEN_PR=0`); commit, push and pull-request operations remain explicit side effects.
 
-## Transparent task reporting
+## How an Agent uses the Skill
 
-The Skill does not end with a prose claim that an animation is complete. Each task can be represented by `artifacts/<task-id>/`, which records the lifecycle state, decisions, changed artifacts, checksums, quality result, review decision, open problems and the next Agent handoff. Generate the report with `python3 scripts/report.py render --task-dir artifacts/<task-id>`.
+The public integration surfaces are intentionally small and inspectable:
 
-The report must distinguish **completed**, **verified**, **not completed**, **blocked/failed**, **structure problems** and **recommended next Agent/Skill**. A scaffold-only runtime must be reported as `scaffold`; it cannot be described as `runtime-verified` until its adapter test has produced evidence.
+1. `SKILL.md` gives the Agent the imperative workflow, progressive-disclosure references and non-negotiable contracts.
+2. `agent-card.json` advertises inputs, outputs, verified capabilities, recommended integrations and side-effect policy.
+3. `motionloom` exposes a cross-platform command surface for analysis, memory, rendering, Dev Lab, evidence, quality and PR preflight.
+4. `artifacts/<task-id>/` provides a durable, machine-readable handoff instead of requiring another Agent to infer state from chat.
 
-Run `python3 scripts/skill-doctor.py --json` when changing the Skill package. It checks the frontmatter, required directories, schemas, Agent Card and references. CI also requires a task report/handoff bundle for changed scenes, so a future Agent cannot silently modify a scene without leaving a reviewable trail.
+The Skill can trigger or suggest an internal browser-capable Agent to open the Dev Lab after rendering. Dev Lab is post-render review infrastructure, not a competing Skill. The user can request changes, receive a structured fix plan and rerender selectively, or explicitly confirm the PR path.
 
-## Agent interoperability and public skills
+## Repository map
+
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Installable Agent Skill contract |
+| `agent-card.json` | Capability discovery and side-effect policy |
+| `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 |
+| `templates/` | Lottie, Rive, GSAP and Framer Motion templates |
+| `scripts/` | Analysis, rendering, evidence, memory, intelligence, reports and PR preflight |
+| `schemas/` | Versioned machine-readable contracts |
+| `references/` | Progressive-disclosure implementation references |
+| `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 |
+| `tests/` | Regression, adversarial and deep-stress evaluation harnesses |
+
+## Documentation map
+
+| Need | Start here |
+|---|---|
+| Install or understand the full lifecycle | [SKILL.md](SKILL.md) |
+| Choose a runtime | [Framework selection](docs/FRAMEWORK-SELECTION.md) and [runtime capability reference](references/runtime-capability.md) |
+| Run a review-ready scene | [Production checklist](docs/CHECKLIST.md) and [browser review contract](references/browser-review-contract.md) |
+| 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) |
+| 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) |
+| See version history | [CHANGELOG.md](CHANGELOG.md) and [release notes](docs/releases/) |
+
+## Development and release checks
 
-`agent-card.json` is the discovery surface. It declares inputs, outputs, verified versus scaffold-only runtimes and Git side effects. Use official or public skills as focused references and adapters rather than copying their prompts into this repository: [LottieFiles dotLottie Web](https://github.com/LottieFiles/dotlottie-web/blob/main/SKILL.md) for runtime APIs, [Diffusion Studio text-to-lottie](https://github.com/diffusionstudio/lottie) for optional scene scaffolding, [Claude Lottie Skill](https://github.com/b1rdmania/claude-lottie-skill/blob/main/SKILL.md) for optional brand-aware asset discovery, and the [Agent Skills specification](https://agentskills.io/specification) plus [GitHub Agent Skills documentation](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) for packaging and portability.
+```bash
+npm install
+python3 scripts/skill-doctor.py --json
+python3 tests/scripts/run_tests.py
+python3 scripts/eval-intelligence.py
+python3 scripts/eval-projects.py --allow-insufficient
+npm run release:verify
+npm run runtime:test
+npm run audit:deep
+npm publish --dry-run --access public
+```
 
-The project-specific value remains in context binding, Motion Spec, asset provenance, runtime evidence, quality policy, review memory and handoff artifacts. The runtime adapter harness delegates rendering to the official packages; it does not reimplement Lottie/Rive runtimes, MCP transport or GitHub authentication inside this Skill.
+The GitHub Actions workflow is designed to run the Project Memory and CLI contract on Ubuntu, macOS and Windows, then run the full evidence-aware quality suite on Ubuntu. Read the latest GitHub Actions run rather than treating this README or a historical audit as proof that the current checkout is green. A package dry-run is part of release preparation. See [CONTRIBUTING.md](CONTRIBUTING.md) for the clean-checkout procedure and [CHANGELOG.md](CHANGELOG.md) for release discipline.
 
-### Important trust boundary
+## Automated CI/CD
 
-`ALLOW_PLACEHOLDER=1 bash scripts/render.sh <scene>` is diagnostic only. It creates visibly marked placeholder frames and the quality gate rejects them. A PR cannot be confirmed until the official runtime or the Dev Lab browser renderer has produced `snapshot/.render-meta.json` with `mode: runtime`.
+MotionLoom separates verification from publication. Pull requests and pushes to `main` trigger the quality, documentation, security and relevant Dev Lab workflows when their path filters match. A weekly Dependabot job proposes dependency updates for the root package, Dev Lab and GitHub Actions. The npm release workflow is manual only, protected by the `npm-release` environment, and requires the maintainer to choose the distribution tag; GitHub release creation is an explicit input rather than an automatic side effect.
 
-## Standards basis
+| Workflow | Trigger | Responsibility |
+|---|---|---|
+| `quality.yml` | Pull request, `main`, manual | Cross-platform memory/CLI matrix and full evidence-aware quality suite |
+| `docs.yml` | Documentation/package changes, `main`, manual | Internal links, metadata, workflow safety, Skill Doctor and npm tarball inspection |
+| `security.yml` | Pull request, `main`, weekly schedule, manual | Dependency review and CodeQL for JavaScript/Python |
+| `devlab.yml` | `dev-lab/**` changes, `main`, manual | Build and retain the browser review workbench artifact |
+| `release.yml` | Manual dispatch only | Regression, npm publish with provenance and optional GitHub release |
 
-The audit and templates are grounded in first-party references: [LottieFiles runtimes](https://docs.lottiefiles.com/en/runtimes), the [dotLottie v2 specification](https://dotlottie.io/spec/2.0/), [Rive Web runtime](https://rive.app/docs/runtimes/web/web-js), [Rive state machines](https://rive.app/docs/runtimes/state-machines), and [GSAP accessibility guidance](https://gsap.com/resources/a11y/). End-to-end adapter evidence currently covers **Lottie JSON, dotLottie packaging, SVG cutout rigs, Rive, GSAP and Framer Motion**. Spine and Three.js remain scaffold-only until framework-specific runtime adapters are implemented.
+To enable npm publication, configure a protected GitHub environment named `npm-release` and either add the `NPM_TOKEN` environment secret or configure npm trusted publishing for this repository. Each manual run must provide `release_version`; the workflow verifies package/changelog/release-note alignment before publishing. The workflow never runs on a pull request and never changes MotionLoom's user-review or approval contract.
 
 ## License
 
-MIT
+MotionLoom is released under the [MIT License](LICENSE). Third-party runtime packages and source assets retain their own licenses and attribution requirements.
+
+## References
+
+[1]: https://agentskills.io/specification "Agent Skills specification"
+[2]: https://docs.lottiefiles.com/en/runtimes "LottieFiles runtimes"
+[3]: https://dotlottie.io/spec/2.0/ "dotLottie v2 specification"
+[4]: https://rive.app/docs/runtimes/web/web-js "Rive Web runtime"
+[5]: https://gsap.com/resources/a11y/ "GSAP accessibility guidance"

package/ROADMAP.md

@@ -0,0 +1,32 @@
+# 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.1.0
+
+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.
+
+## 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.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 |
+
+## 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,27 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Security fixes |
+|---|---|
+| `2.1.x` | Supported |
+| `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.1.0 release note](docs/releases/2.1.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`.