motionloom 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -4,7 +4,30 @@ All notable MotionLoom changes are documented here. The project follows semantic
 
 ## [Unreleased]
 
-- No unreleased changes are currently tracked.
+No unreleased changes are recorded.
+
+## [2.3.0] - 2026-08-14
+
+### Added
+
+- AI-first, human-governed asset provenance contract with explicit authority/origin tiers, readiness states, generator/derivation metadata, per-file SHA-256, license/source records, runtime evidence and human-review boundaries.
+- Cross-platform `motionloom asset-provenance` commands for validation, classification, reporting and runtime/production checks, plus a transparent AI-generated pilot fixture.
+- One-command `npx --yes motionloom setup` onboarding for real projects, with package-manager detection, local devDependency installation, project-bound context and durable Project Memory bootstrap.
+- Read-only `motionloom status`, safe `motionloom repair`, dry-run JSON output and an idempotent managed `AGENTS.md` router for Agent integration.
+- Canonical `npx` installation recipe in Agent discovery plus Ubuntu/macOS/Windows onboarding regressions and package/docs guards.
+
+### Fixed
+
+- Production quality and PR preflight now fail closed when an asset is unknown, self-asserted as artist-authored, not production-eligible or missing a manifest-bound provenance record; `production_approved` remains human-only.
+- Setup JSON output no longer mixes package-manager logs with machine-readable results, and repair/status routing does not trigger an unintended full setup.
+
+### Verified
+
+- Full regression, onboarding and installation-matrix tests, discovery contract, docs audit, Skill Doctor, skill-creator validation, quality validation, npm tarball dry-run and diff hygiene pass.
+
+### Boundary
+
+- Setup never commits, pushes, opens a PR, grants approval or promotes asset provenance. User review remains required before any PR handoff.
 
 ## [2.2.0] - 2026-08-13
 
@@ -64,5 +87,6 @@ See the [2.0.0 release note](docs/releases/2.0.0.md).
 The 1.5.0–1.9.0 milestones established runtime evidence, browser review, Intelligence Core, semantic lint, continuity, telemetry and trust-boundary hardening. Their detailed notes are available in [`docs/releases/`](docs/releases/).
 
 [2.2.0]: docs/releases/2.2.0.md
+[2.3.0]: docs/releases/2.3.0.md
 [2.1.0]: docs/releases/2.1.0.md
 [2.0.0]: docs/releases/2.0.0.md

package/README.md

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

package/ROADMAP.md

@@ -2,9 +2,9 @@
 
 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
+## Current baseline: 2.3.0 release target
 
-The current repository baseline includes project-aware analysis, durable Project Memory, context-bound Motion Spec, source binding, real runtime adapters for Lottie/dotLottie/SVG cutout/Rive/GSAP/Framer Motion, Dev Lab browser review, Intelligence Core, semantic and continuity feedback, runtime telemetry, external evidence verification, signed attestation, 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.
+The current repository baseline includes project-aware analysis, durable Project Memory, context-bound Motion Spec, source binding, real runtime adapters for Lottie/dotLottie/SVG cutout/Rive/GSAP/Framer Motion, Dev Lab browser review, Intelligence Core, semantic and continuity feedback, runtime telemetry, external evidence verification, signed attestation, Agent interoperability surfaces, Visual Truth, Remediation Learning, AI-first asset provenance and cross-platform CLI/CI contracts. The `2.3.0` release target adds one-command project onboarding without weakening review or Git side-effect boundaries.
 
 ## Next milestones
 
@@ -14,10 +14,12 @@ The current repository baseline includes project-aware analysis, durable Project
 | **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 |
+| **2.6** | Agent-created Asset Provenance | Explicit origin/authority/readiness tiers; runtime ingest without automatic production approval; fail-closed production gate | Included in 2.3.0 release target |
+| **2.7** | One-command Onboarding | Project-bound setup/status/repair, Agent router merge, durable memory bootstrap and cross-platform installation recipe | Included in 2.3.0 release target |
 
 ## Working-tree implementation status
 
-The current implementation pass has delivered the contracts behind milestones 2.2, 2.3 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.
+The current implementation pass has delivered the contracts behind milestones 2.2, 2.3, 2.5, 2.6 and 2.7: canonical Agent discovery/install surfaces, consumer fixtures and a Ubuntu/macOS/Windows matrix; Visual Truth is bound into scene manifests, Dev Lab handoff and the review-first quality gate; Remediation Learning records hash-chained benchmark/outcome history; CI replay evidence is rebuilt after generated artifacts; asset provenance remains production fail-closed; and `npx --yes motionloom setup` bootstraps a project without overwriting its Agent guidance. The remaining work is maintainer release verification and paired evaluation on additional real projects.
 
 ## Product principles
 

package/SKILL.md

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

package/agent-card.json

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

package/agent-surfaces.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "1.0",
   "name": "motionloom",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "canonical": {
     "skill": "SKILL.md",
     "agent_card": "agent-card.json",
@@ -42,6 +42,13 @@
     }
   ],
   "installations": [
+    {
+      "id": "npx-onboarding",
+      "source_kind": "npx",
+      "command": "npx --yes motionloom setup",
+      "verification": "npx --no-install motionloom status --json",
+      "provenance": "npm-registry-resolution-and-project-lockfile"
+    },
     {
       "id": "npm-registry",
       "source_kind": "npm",

package/bin/motionloom.mjs

@@ -37,6 +37,13 @@ const PYTHON_COMMANDS = {
   discovery: "scripts/discovery.py",
   "visual-truth": "scripts/visual-truth.py",
   "remediation-learning": "scripts/remediation-learning.py",
+  "asset-provenance": "scripts/asset-provenance.py",
+};
+
+const NODE_COMMANDS = {
+  setup: "scripts/setup.mjs",
+  status: "scripts/setup.mjs",
+  repair: "scripts/setup.mjs",
 };
 
 function printHelp() {
@@ -65,6 +72,10 @@ Commands:
   discovery              Check Agent surfaces, source identity and install matrix
   visual-truth           Build or validate provenance-bound visual comparisons
   remediation-learning   Record or summarize user-confirmed remediation and benchmark history
+  asset-provenance       Validate, classify or report asset origin and production readiness
+  setup                  Install and bootstrap MotionLoom in the current project
+  status                 Read-only project readiness report
+  repair                 Re-apply safe missing setup pieces
 
 Cross-platform examples:
   motionloom analyze . --init-memory
@@ -76,6 +87,7 @@ Cross-platform examples:
   motionloom discovery install-matrix --root . --json
   motionloom visual-truth validate --root . --input src/output/<scene>/visual-truth.json
   motionloom remediation-learning summary --history artifacts/remediation-history.jsonl --json
+  motionloom asset-provenance check --input <asset-provenance.json> --root <scene-dir> --mode runtime --json
 
 The CLI never grants approval or opens a pull request by itself. User review
 and explicit repository side-effect confirmation remain separate gates.
@@ -88,7 +100,7 @@ if (!command || command === "help" || command === "--help" || command === "-h")
   process.exit(0);
 }
 
-const script = PYTHON_COMMANDS[command];
+const script = NODE_COMMANDS[command] || PYTHON_COMMANDS[command];
 if (!script) {
   console.error(`Unknown MotionLoom command: ${command}`);
   printHelp();
@@ -96,7 +108,8 @@ if (!script) {
 }
 
 const executable = script.endsWith(".mjs") ? process.execPath : PYTHON;
-const result = spawnSync(executable, [resolve(ROOT, script), ...args], {
+const delegatedArgs = NODE_COMMANDS[command] && command !== "setup" ? [command, ...args] : args;
+const result = spawnSync(executable, [resolve(ROOT, script), ...delegatedArgs], {
   cwd: ROOT,
   stdio: "inherit",
   env: process.env,

package/docs/AGENT-INTEGRATION.md

@@ -6,11 +6,12 @@ MotionLoom is distributed as one Skill with several **discovery surfaces**, not
 
 | Source | Typical command | Verification | Provenance to retain |
 |---|---|---|---|
+| One-command onboarding | `npx --yes motionloom setup` | `npx --no-install motionloom status --json` | project lockfile, setup JSON and generated project identity |
 | npm registry | `npm install --save-dev motionloom` | `motionloom discovery check --root . --json` | lockfile and resolved package version |
 | Git checkout | `git clone https://github.com/lenhonbp/MotionLoom.git` | `node bin/motionloom.mjs discovery check --root . --json` | remote URL and commit SHA |
 | Local source | invoke `<checkout>/bin/motionloom.mjs` | `python3 scripts/discovery.py check --root . --json` | source path and local commit if present |
 
-The check is offline and read-only. Installation, source identity and capability compatibility are separate from network authentication. A passing check means that the package is structurally discoverable; it does not mean that a scene is runtime-verified or approved.
+The check is offline and read-only. Installation, source identity and capability compatibility are separate from network authentication. A passing check means that the package is structurally discoverable; it does not mean that a scene is runtime-verified or approved. For a new host project, prefer `npx --yes motionloom setup`; use `--dry-run --json` to preview and `status --json` to inspect without mutation. `repair --yes` only restores missing managed pieces.
 
 ## Agent surfaces
 
@@ -36,7 +37,19 @@ Support here means that the repository exposes a deterministic discovery contrac
 
 ## 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.
+For a new host project, run `npx --yes motionloom setup --json`, inspect the returned `status`, then use `npx --no-install motionloom status --json` before planning. Setup performs project analysis, discovery and durable-memory bootstrap without copying artifacts from the MotionLoom checkout. For an existing installation, run `motionloom discovery check --root <checkout> --json`, then refresh with `motionloom analyze <project> --init-memory` when needed. Load the project context and durable Project Memory before planning. After selecting or generating an asset, create `asset-provenance.json` and run the runtime-mode check before ingest. An AI-generated pilot may proceed to the real runtime and Dev Lab, but it must remain non-production-eligible. After rendering, prepare a task-bound browser candidate and suggest or trigger the internal Dev Lab. Capture user feedback separately from runtime evidence. A valid signature, quality gate or screenshot is not a user approval.
+
+## AI-first asset workflow
+
+The Agent must distinguish these transitions rather than collapsing them into one `approved` flag:
+
+| Transition | Allowed actor | Required evidence |
+|---|---|---|
+| `blocked` → `runtime_ready` | Agent or runtime validator | Safe paths, valid schema, license/source, file hashes and real runtime evidence |
+| `runtime_ready` → `production_eligible` | Contract gate plus human review where the authority tier requires it | Full quality/visual/runtime gate and valid authority record |
+| `production_eligible` → `production_approved` | User or designated human reviewer only | Explicit review decision persisted outside the Agent's self-assertion |
+
+Never rewrite `ai_generated` as `artist_authored`, never infer human review from a signature, and never set `production_approved` from `quality-gate`. Use `motionloom asset-provenance report` to show the boundary in a handoff.
 
 ## Portability policy
 

package/docs/CHECKLIST.md

@@ -24,9 +24,14 @@ 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, visual-truth path, and completed checklist entries.
+- [ ] `asset-provenance.json` records origin/authority, generator or derivation chain, license/source, per-file SHA-256 and runtime evidence.
+- [ ] `ai_generated` assets may be runtime-ready but are not production-eligible; `unknown` assets are blocked.
+- [ ] `artist_authored` is backed by a verifiable human/artist record and is not merely an Agent-authored field.
 
 ## PR readiness
 - [ ] Snapshot PNGs exist for 0/50/100%.
 - [ ] `visual-truth.json` binds real baseline/candidate frames to source, manifest and available runtime/Motion IR hashes; `approval` remains `false`.
 - [ ] `motion-spec.json` is bound to the exact `project-context.json` hash (implements == planned).
 - [ ] Dev Lab URL tested on mobile viewport and desktop.
+- [ ] The production provenance check passes with `--mode production` and reports `production_eligible: true`.
+- [ ] `production_approved` and browser-review approval are recorded only from the user's explicit review; attestation approval remains `false`.

package/docs/STATUS.md

@@ -4,7 +4,7 @@
 
 ## Current release posture
 
-MotionLoom's repository source and package manifest are at **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.
+MotionLoom's repository source and package manifest are prepared for **2.3.0 release metadata**. The publication state of the npm registry and GitHub Release/tag must be verified against the latest release workflow rather than inferred from this document. The repository has a cross-platform CLI, one-command project onboarding, durable Project Memory, Agent interoperability surfaces, artifact-first handoff, runtime evidence, Visual Truth, Remediation Learning, signed attestation, AI-first asset provenance and a browser-based Dev Lab review contract. The protected manual release workflow verifies package/changelog/release-note alignment before publication.
 
 The repository is **engineering-ready for continued integration work**, not a universal production certification for every animation framework or every host project. CI status must be read from the latest GitHub Actions run, not inferred from historical audit prose.
 
@@ -30,4 +30,4 @@ Use the following order when sources disagree:
 
 ## Known next work
 
-The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The highest-value remaining evidence work is paired product evaluation across more real projects, then closing version–tag–GitHub Release–npm provenance traceability through an approved manual release. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.
+The bounded analyzer has now been exercised against a labeled external corpus; see the [dated evidence note](audits/external-project-corpus-2026-08-13.md). The highest-value remaining evidence work is paired product evaluation across more real projects and verification of the 2.3.0 version–tag–GitHub Release–npm provenance chain. Missing external projects are reported as `insufficient_evidence`, never as a pass. None of these items should weaken the user-review gate or convert heuristic warnings into approval.

package/docs/releases/2.3.0.md

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

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

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

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

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