motionloom 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable MotionLoom changes are documented here. The project follows semantic
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-08-17
+
+### Added
+
+- Read-only `motionloom capability card --format json` discovery surface. It exports the evidence-validated runtime registry for an Agent, including runtime status, adapter/version, compatibility, verification timestamp, inputs/outputs, evidence references, limitations, fallback, risk and side-effect metadata.
+- `pnpm intelligence:card` shortcut and `agent-card.json` command/capability declarations for machine-readable discovery without a parallel capability policy.
+- `capability-registry.json` is included in the npm package allowlist, so the default card command has its verified registry after a normal package installation.
+- Benchmark research ledger comparing public agent workflow, model-serving and AI/video repositories; the release applies the low-risk capability-card lesson and records deferred generation-profile and hash-bound workflow-template work with explicit gates.
+- Native `apps/apple/` alpha in the GitHub source release: shared Swift packages for contracts, review state, macOS bridge, review UI and local-first CloudKit metadata sync, plus unsigned macOS Studio and iOS/iPadOS Review build targets and Apple CI.
+
+### Verified
+
+- Capability-card export validates registry evidence before output and fails closed for missing, altered or out-of-repository evidence. It does not select a runtime or infer review/production approval.
+- The repository release target passes the full regression suite, Skill/doctor and documentation gates, package artifact inspection, and GitHub Quality, Security, Documentation and Apple CI checks.
+
+### Boundary
+
+- The Apple deliverable is an alpha source release. It has no Apple Developer signing, CloudKit production container, TestFlight distribution or iOS Simulator UI-smoke claim.
+- Capability discovery is not execution authority. Runtime selection still validates current evidence, and attestation/production approval remain non-derived human decisions.
+
 ## [2.4.0] - 2026-08-15
 
 ### Added
@@ -109,6 +129,7 @@ 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.5.0]: docs/releases/2.5.0.md
 [2.4.0]: docs/releases/2.4.0.md
 [2.3.0]: docs/releases/2.3.0.md
 [2.1.0]: docs/releases/2.1.0.md

package/README.md

@@ -6,6 +6,7 @@
 [![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/)
+[![Apple](https://github.com/lenhonbp/MotionLoom/actions/workflows/apple.yml/badge.svg)](https://github.com/lenhonbp/MotionLoom/actions/workflows/apple.yml)
 [![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.**
@@ -14,7 +15,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:** `motionloom@2.4.0` is the next release target. It adds a truthful `code_authored` runtime-first lane, a Framer Motion end-to-end reference candidate, identity-bound Dev Lab review evidence and task-bundle discovery that binds by declared scene identity rather than an inferred directory name. Verify npm/GitHub publication metadata separately; passing evidence never implies user approval.
+> **Release posture:** MotionLoom 2.5.0 adds an evidence-bound Agent capability card, benchmark-informed runtime discovery, and the native macOS/iOS review alpha in the GitHub source release under `apps/apple/`. The npm package remains the cross-platform Node/Python Skill and documentation surface; it does not distribute or sign the Xcode app. Verify npm/GitHub publication metadata separately; passing evidence never implies user approval.
 
 ## Why MotionLoom
 
@@ -154,6 +155,14 @@ Read the [Project Memory schema](schemas/project-memory.schema.json), [2.1.0 rel
 
 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.
 
+An Agent can inspect the read-only capability card before choosing a renderer:
+
+```bash
+motionloom capability card --format json
+```
+
+The card exposes declared compatibility, evidence references, limitations and fallback paths. It does **not** select a runtime, refresh evidence, infer production approval or replace the verification step; use `motionloom intelligence capabilities select --registry capability-registry.json --capability runtime.<id>` immediately before execution.
+
 ## Evidence, trust and review
 
 MotionLoom keeps distinct layers distinct:
@@ -257,6 +266,14 @@ The public integration surfaces are intentionally small and inspectable:
 
 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.
 
+## Native companion apps (alpha)
+
+`apps/apple/` contains the native-first Apple companion surface. **MotionLoom Studio for macOS** opens a scoped project, exposes the evidence and timeline inspection surface, and can request only allow-listed local checks. **MotionLoom Review for iPhone and iPad** reads a hash-bound review launch descriptor, scrubs evidence, records annotations, and exports a human review decision.
+
+These apps do not replace the Agent, the npm CLI or Dev Lab. They make a project’s artifact state and human review decision visible between Agent sessions. They cannot grant `production_approved`, set `OPEN_PR=1`, push Git changes, publish npm packages, or turn an AI-generated asset into artist-authored material.
+
+Read [the Apple workspace guide](apps/apple/README.md), [the contract boundary](docs/architecture/apple/contracts.md), and [the TestFlight preparation guide](docs/apple-distribution.md) before building locally.
+
 ## Repository map
 
 | Path | Purpose |
@@ -273,6 +290,7 @@ The Skill can trigger or suggest an internal browser-capable Agent to open the D
 | `references/` | Progressive-disclosure implementation references |
 | `docs/` | Framework selection, checklists, audits and release notes |
 | `dev-lab/` | Self-contained browser review workbench and harness |
+| `apps/apple/` | macOS Studio and iOS/iPadOS Review companion sources, Swift packages, Xcode project and local build guide |
 | `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 |
@@ -297,6 +315,7 @@ The Skill can trigger or suggest an internal browser-capable Agent to open the D
 | Check control-to-runtime and rig compatibility | `motionloom runtime-candidate`, `motionloom rig-compatibility`, and [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) |
+| Build the native review companions | [Apple workspace guide](apps/apple/README.md), [Studio architecture](docs/architecture/apple/studio.md), and [distribution preparation](docs/apple-distribution.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/) |

package/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   validate, review, or deliver animation inside an existing project.
 license: MIT
 metadata:
-  version: "2.4.0"
+  version: "2.5.0"
   target_frameworks: "lottie,dotlottie,rive,gsap,framer-motion,spine,threejs"
   verified_runtimes: "lottie-json,dotlottie-package,svg-cutout-rig,rive,gsap,framer-motion"
 ---

package/agent-card.json

@@ -1,7 +1,7 @@
 {
   "card_version": "1.0",
   "name": "motionloom",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Project-aware animation production with durable Project Memory, provider-neutral Artifact Intake, hash-bound control-to-runtime candidates, tiered asset provenance, framework-neutral motion IR, rig compatibility, runtime verification and telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, internal browser review, trust-boundary hardening and deterministic Agent handoff.",
   "capabilities": [
     "project.setup",
@@ -41,6 +41,7 @@
     "provenance.emit",
     "provenance.verify",
     "capability.discover",
+    "capability.card",
     "capability.select",
     "replay.capture",
     "replay.verify",
@@ -121,6 +122,7 @@
     "project-graph",
     "provenance-attestation",
     "capability-registry",
+    "capability-card",
     "motion-ir",
     "replay-bundle",
     "semantic-lint-report",
@@ -203,6 +205,7 @@
     "intelligence_graph": "python3 scripts/intelligence.py graph build --task-dir artifacts/<task-id>",
     "intelligence_provenance": "python3 scripts/intelligence.py provenance build --task-dir artifacts/<task-id>",
     "intelligence_capabilities": "python3 scripts/intelligence.py capabilities build --output capability-registry.json",
+    "intelligence_capability_card": "motionloom capability card --format json",
     "intelligence_motion_ir": "python3 scripts/intelligence.py motion-ir build --task-dir artifacts/<task-id>",
     "intelligence_replay": "python3 scripts/intelligence.py replay capture --task-dir artifacts/<task-id>",
     "semantic_lint": "python3 scripts/intelligence.py semantic-lint build --task-dir artifacts/<task-id>",

package/agent-surfaces.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "1.0",
   "name": "motionloom",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "canonical": {
     "skill": "SKILL.md",
     "agent_card": "agent-card.json",

package/bin/motionloom.mjs

@@ -54,6 +54,10 @@ const NODE_COMMANDS = {
   repair: "scripts/setup.mjs",
 };
 
+const COMMAND_ALIASES = {
+  capability: { script: "scripts/intelligence.py", args: ["capabilities"] },
+};
+
 function printHelp() {
   console.log(`MotionLoom 2.4.0 — project-aware animation production and evidence contracts
 
@@ -69,6 +73,7 @@ Use when an animation task needs it:
   analyze                Run project analysis and refresh Project Memory
   memory                 Initialize, inspect, refresh, recover or validate memory
   intelligence           Build or validate Intelligence Core artifacts
+  capability             Export or select evidence-bound runtime capabilities
   attestation            Build/validate canonical signed-attestation artifacts
   verify-attestation     Verify an attestation against a trust policy
   evidence-verify        Verify runtime evidence externally
@@ -103,6 +108,7 @@ Cross-platform examples:
     --status accepted --summary "Use ease-out for UI entry" --user-confirmed
   motionloom discovery check --root . --json
   motionloom discovery install-matrix --root . --json
+  motionloom capability card --format 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
@@ -124,7 +130,8 @@ if (!command || command === "help" || command === "--help" || command === "-h")
   process.exit(0);
 }
 
-const script = NODE_COMMANDS[command] || PYTHON_COMMANDS[command];
+const alias = COMMAND_ALIASES[command];
+const script = alias?.script || NODE_COMMANDS[command] || PYTHON_COMMANDS[command];
 if (!script) {
   console.error(`Unknown MotionLoom command: ${command}`);
   printHelp();
@@ -132,7 +139,13 @@ if (!script) {
 }
 
 const executable = script.endsWith(".mjs") ? process.execPath : PYTHON;
-  const delegatedArgs = NODE_COMMANDS[command] && !["setup", "init"].includes(command) ? [command, ...args] : command === "init" ? ["init", ...args] : args;
+const delegatedArgs = alias
+  ? [...alias.args, ...args]
+  : NODE_COMMANDS[command] && !["setup", "init"].includes(command)
+    ? [command, ...args]
+    : command === "init"
+      ? ["init", ...args]
+      : args;
 const result = spawnSync(executable, [resolve(ROOT, script), ...delegatedArgs], {
   cwd: ROOT,
   stdio: "inherit",

package/capability-registry.json

@@ -0,0 +1,308 @@
+{
+  "schema_version": "0.1",
+  "registry_id": "registry-motionloom-2.5.0",
+  "generated_at": "2026-08-17T05:39:24Z",
+  "selection_policy": {
+    "require_verified": true,
+    "allow_scaffold_only": false,
+    "max_evidence_age_seconds": 604800
+  },
+  "capabilities": [
+    {
+      "id": "runtime.lottie-json",
+      "kind": "renderer",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.dotlottie-package",
+      "kind": "packager",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.svg-cutout-rig",
+      "kind": "renderer",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.rive",
+      "kind": "runtime-adapter",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.gsap",
+      "kind": "runtime-adapter",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.framer-motion",
+      "kind": "runtime-adapter",
+      "status": "verified",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Capability evidence is refreshed by runtime:test."
+      ],
+      "fallback": "",
+      "risk_level": "low",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.spine",
+      "kind": "renderer",
+      "status": "scaffold_only",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Scaffold only; do not use for production acceptance."
+      ],
+      "fallback": "runtime.lottie-json",
+      "risk_level": "high",
+      "side_effect_level": "local_write"
+    },
+    {
+      "id": "runtime.threejs",
+      "kind": "renderer",
+      "status": "scaffold_only",
+      "adapter_version": "2.5.0",
+      "inputs": [
+        "project-context",
+        "motion-spec",
+        "source-binding"
+      ],
+      "outputs": [
+        "runtime-evidence"
+      ],
+      "compatibility": {
+        "browsers": [
+          "chromium"
+        ],
+        "os": [
+          "linux"
+        ],
+        "node": ">=22"
+      },
+      "last_verified_at": "2026-08-17T05:39:24Z",
+      "evidence": [
+        {
+          "path": "scripts/runtime-adapters.mjs",
+          "sha256": "711a64c07b4d82f646d066c7b0d91deaefc5c9c0fb701358706bf31d558b4d89",
+          "kind": "ci"
+        }
+      ],
+      "limitations": [
+        "Scaffold only; do not use for production acceptance."
+      ],
+      "fallback": "runtime.lottie-json",
+      "risk_level": "high",
+      "side_effect_level": "local_write"
+    }
+  ]
+}

package/docs/apple-distribution.md

@@ -0,0 +1,24 @@
+# Apple distribution boundary
+
+The current `MotionLoomStudio` build is an unsigned local alpha. GitHub CI builds packages and checks iOS Simulator compatibility; it does not sign, upload, submit or distribute an application.
+
+| Channel | Required external inputs | Current state |
+| --- | --- | --- |
+| Local macOS alpha | Xcode and a user-selected project folder | Implemented and manually launchable. |
+| iOS Simulator review UI | Xcode simulator runtime and an Xcode app target that embeds `MotionLoomReviewUI` | Library cross-compilation is verified; the signed target remains intentionally uncreated. |
+| TestFlight | Apple Developer Program membership, bundle identifier, signing, App Store Connect app record and a user approval to upload | Not initiated. |
+| Mac App Store / iOS App Store | The TestFlight requirements plus app metadata, privacy details and an explicit human submission decision | Not initiated. |
+
+TestFlight distribution is handled through App Store Connect and requires the app owner to control signing and submission; MotionLoom’s CI must stay read-only until an owner explicitly decides to introduce that workflow.[1]
+
+## Before a TestFlight decision
+
+1. Create a final bundle identifier and an Apple-owned iCloud container; do not reuse development identifiers accidentally.
+2. Create the iOS/macOS Xcode app targets and add `MotionLoomContracts`, `MotionLoomReview`, `MotionLoomReviewUI` and, on macOS, `MotionLoomMacBridge` as local packages.
+3. Complete privacy labels and explain that CloudKit is limited to review metadata if sync is enabled.
+4. Test review JSON handoff with a real candidate on a physical iPhone/iPad and macOS.
+5. Make a separate explicit decision before uploading any build, inviting testers or submitting for review.
+
+## References
+
+[1]: https://developer.apple.com/testflight/ "Apple Developer — TestFlight"

package/docs/architecture/apple/cloudkit.md

@@ -0,0 +1,18 @@
+# CloudKit review metadata boundary
+
+`MotionLoomReviewSync` is intentionally **local-first**. A review is written to a local outbox before it can be uploaded. The CloudKit adapter uploads only a metadata projection after `MotionLoomContractDecoder.verify` confirms that task ID, candidate ID and both evidence digests match the review launch descriptor.
+
+| Data class | Local outbox | Private CloudKit database | Explicitly excluded |
+| --- | --- | --- | --- |
+| Human review decision and annotations | Yes | Metadata projection only | No production approval field exists. |
+| Task/candidate IDs and evidence hashes | Yes | Yes | No raw runtime artifact bytes. |
+| Source asset, texture, `.riv`, `.lottie`, project repository or secrets | No | No | Never synchronized by this adapter. |
+| GitHub/PR/npm/App Store operations | No | No | Must remain an explicit human-controlled workflow outside CloudKit. |
+
+The default database is the user’s private CloudKit database. Before enabling a production container, the app project needs a user-owned container identifier, the iCloud capability entitlement, an App ID and an explicit privacy review. The source package does **not** supply a container identifier, entitlement, Apple team ID, signing profile or server token.
+
+Apple describes CloudKit as a framework for storing and syncing app data through the user’s iCloud account; this design deliberately narrows that scope to review metadata and does not treat CloudKit as the source of truth for source assets or repository state.[1]
+
+## References
+
+[1]: https://developer.apple.com/icloud/cloudkit/ "Apple Developer — CloudKit"

package/docs/architecture/apple/contracts.md

@@ -0,0 +1,9 @@
+# Apple contract boundary
+
+The Apple application is an inspection and human-review surface. It reads canonical MotionLoom artifacts and writes only a human review decision bound to the selected task, candidate and evidence digests. It does not duplicate Python validator policy, create provenance, grant `production_approved`, set `OPEN_PR=1`, open a pull request or publish a package.
+
+`contracts/apple/review-launch-descriptor.schema.json` defines the minimum identity-bound information a macOS or iOS review surface may accept. A descriptor is rejected when its schema version is unsupported, it has unknown fields, identifiers are invalid, an artifact root is missing, or runtime/candidate evidence digests are absent.
+
+`contracts/apple/review-decision.schema.json` defines a record made only after explicit human action. The only allowed decisions are `request_changes`, `reviewed_no_decision` and `approve_for_next_human_step`. None is production approval. A later policy-controlled workflow may consume a record only after independently verifying the same task, candidate and evidence identity.
+
+The initial fixtures bind to `runtime-pilot-001`. They are decoder and identity fixtures, not an approval fixture and not a claim that the candidate is production eligible.

package/docs/architecture/apple/implementation-status-2026-08-16.md

@@ -0,0 +1,55 @@
+# MotionLoom Apple alpha — implementation status
+
+**Ngày kiểm tra:** 16-08-2026  
+**Phạm vi:** macOS Studio alpha, iOS/iPadOS Review companion, review contracts, local-first sync foundation và native CI.  
+**Trạng thái source:** hoàn thành và đã kiểm thử local; chưa commit, push, ký hoặc phát hành.
+
+## Kết luận
+
+MotionLoom hiện có một lớp app Apple native-first bám đúng mô hình **artifact-first, runtime-evidence và human-governed** của repository. Lớp mới không thay thế CLI Node/Python, runtime adapters hoặc Dev Lab; nó biến evidence đã có thành Project Inspector, Timeline Desk và review surface native cho macOS/iOS.
+
+> App không có khả năng cấp `production_approved`, tự chạy shell tùy ý, tự tạo PR, push Git, publish npm hay submit App Store. Các hành động này tiếp tục nằm ngoài native surface và phải qua cơ chế review/quyền hiện hữu.
+
+| Thành phần | Đầu ra đã tạo | Trạng thái |
+| --- | --- | --- |
+| Canonical contracts | `contracts/apple/review-launch-descriptor.schema.json`, `review-decision.schema.json` và fixture hash-bound runtime-pilot | Đã hoàn thành; reject unknown fields và không biểu diễn production approval. |
+| Contract runtime | `apps/apple/Packages/MotionLoomContracts` | Đã hoàn thành; Swift decoder fail-closed, migration version và identity binding. |
+| Review core | `apps/apple/Packages/MotionLoomReview` | Đã hoàn thành; timeline, annotation, ba human review decisions và export review JSON deterministic. |
+| Project bridge | `apps/apple/Packages/MotionLoomMacBridge` | Đã hoàn thành; security-scoped folder access, allow-list inspection commands, chặn path/URL không tin cậy. |
+| macOS Studio | `apps/apple/MotionLoomStudio` và target `MotionLoomStudio` | Đã build và launch unsigned; có Project Inspector, Timeline Desk và native web surface mở Dev Lab review URL. |
+| iOS/iPadOS companion | `apps/apple/MotionLoomReviewApp`, `MotionLoomReviewUI` và target `MotionLoomReview` | Đã build unsigned cho iPhone Simulator SDK; chỉ đọc evidence, scrub timeline, annotate và tạo review decision. |
+| Đồng bộ review | `apps/apple/Packages/MotionLoomReviewSync` | Đã hoàn thành local-first outbox; chỉ đưa metadata review identity-bound vào sync adapter. |
+| CI và hướng dẫn | `.github/workflows/apple.yml`, `apps/apple/scripts/emit-ios-simulator-destination.sh`, các tài liệu Apple | Đã hoàn thành; CI không ký, không publish và dùng dynamic simulator SDK destination. |
+
+## Trust boundary giữ nguyên
+
+Các package Swift dùng canonical contract và fixture từ repository thay vì sao chép policy validator sang Swift. `MotionLoomContracts` giới hạn review decision ở các trạng thái review của con người; `MotionLoomReview` chỉ export review record; `MotionLoomMacBridge` chỉ có lệnh inspection trong allow-list. CloudKit adapter cũng chỉ nhận review metadata đã identity-bound, không nhận source asset, repository, secret, production authority hoặc capability nâng quyền.
+
+Mac app có thể mở project folder và xuất handoff review; iOS app có thể đọc candidate/evidence và ghi note theo timeline. Cả hai app không làm thay nhiệm vụ của Agent: Agent tiếp tục tạo/sửa artifact, chạy validator và render runtime thật; người dùng review trên native app rồi tạo data để Agent tiếp tục xử lý.
+
+## Kiểm thử đã chạy trên Mac
+
+| Kiểm tra | Kết quả |
+| --- | --- |
+| `pnpm test` từ repository root | **PASS** — toàn bộ regression suite, gồm Apple contract và signed attestation. |
+| `pnpm run docs:check` | **PASS**. |
+| `swift test` cho Contracts, Review, MacBridge, ReviewUI và ReviewSync | **PASS**. |
+| `xcodebuild` unsigned target `MotionLoomStudio` với SDK macOS | **PASS**; Studio đã launch local. |
+| `xcodebuild` unsigned target `MotionLoomReview` với SDK iPhone Simulator | **PASS**. |
+| `git diff --check` | **PASS**. |
+
+Trong quá trình acceptance trên macOS, regression cũ phát hiện giả định path không phù hợp với alias hệ thống `/var -> /private/var`. Các chỉnh sửa giới hạn trong `scripts/evidence-verifier.py`, `scripts/intelligence.py` và `scripts/attestation.py`: chỉ parent alias hệ thống này được xử lý đúng trên macOS; symlink tại hoặc bên trong scene, task, evidence, repository và replay roots vẫn bị reject. Toàn bộ regression suite đã pass sau thay đổi này.
+
+## Blocker còn lại ngoài source code
+
+| Hạng mục | Lý do chưa thực hiện | Điều kiện để hoàn thành |
+| --- | --- | --- |
+| iOS UI smoke trên simulator | Xcode đang có iPhone Simulator SDK để compile nhưng chưa có device runtime khả dụng để boot. | Cài một iOS Simulator runtime trong Xcode Settings, sau đó boot device và chạy UI smoke. |
+| CloudKit sync live | Cần container thuộc Apple Developer account và entitlement có quyền của chủ sở hữu. | Chủ sở hữu tạo/chọn CloudKit container, quyết định retention/privacy và bật entitlement trong Xcode. |
+| Ký/TestFlight/App Store | Cần Apple Developer Team, App IDs, bundle identifiers, signing và quyết định submit của chủ sở hữu. | Cấu hình signing, tạo archive, rồi chủ sở hữu duyệt upload TestFlight. |
+
+Các blocker trên không làm source alpha bị lỗi; chúng là quyền tài khoản và hạ tầng bên ngoài mà MotionLoom không tự tạo hoặc tự chấp nhận thay người dùng.
+
+## Bước tiếp theo sau khi commit/push được duyệt
+
+Sau khi source được commit và push riêng, công việc hợp lý tiếp theo là cài iOS Simulator runtime, chạy UI smoke của Review companion, thiết kế CloudKit container review-only và chỉ sau đó mới cân nhắc beta TestFlight. Không nên thêm production approval, Git push hay asset upload capability vào app trước khi vòng review iOS đã được kiểm chứng trên device/simulator.

package/docs/architecture/apple/studio.md

@@ -0,0 +1,35 @@
+# MotionLoom Studio alpha
+
+MotionLoom Studio is a **native macOS inspection and review surface**, not a replacement for the cross-platform MotionLoom CLI, its Python validators, runtime adapters or Dev Lab. The Studio presents verified task/candidate/evidence identity and helps a human create a review handoff.
+
+| Surface | Responsibility | Prohibited actions |
+| --- | --- | --- |
+| Project Inspector | User selects a scoped project folder, then launches a small allow-list of local inspections. | Arbitrary shell, `git push`, `OPEN_PR=1`, npm publish and PR creation. |
+| Timeline Desk | Scrub review timecodes, open the existing Dev Lab candidate and collect annotations. | Treating a preview or heuristic as approval. |
+| Evidence | Shows task/candidate identity and SHA-256 digests before review. | Loading a candidate whose identity binding is not valid. |
+| Export Human Review | Writes a deterministic review JSON for an Agent or maintainer to act on later. | Writing `production_approved` or modifying a repository. |
+
+The app uses `ProjectAccessScope` to confine read/write operations to an explicitly selected project root. It invokes the CLI through an argument vector and a closed command enum, never a shell string. macOS security-scoped bookmarks are supported for a later sandboxed/notarized build, but the alpha remains unsigned and local.
+
+## Local verification
+
+```bash
+cd apps/apple/Packages/MotionLoomContracts && swift test
+cd ../MotionLoomReview && swift test
+cd ../MotionLoomMacBridge && swift test
+cd ../MotionLoomReviewUI && swift test
+cd ../MotionLoomReviewSync && swift test
+cd ../../MotionLoomStudio && swift build
+swift run MotionLoomStudio
+```
+
+To verify the companion library against the installed iOS Simulator SDK without signing an app bundle:
+
+```bash
+destination="$(mktemp)"
+apps/apple/scripts/emit-ios-simulator-destination.sh "$destination"
+(cd apps/apple/Packages/MotionLoomReviewUI && swift build --destination "$destination")
+rm -f "$destination"
+```
+
+> A successful native build, attestation or quality gate is **not** human approval. The only review records emitted by the app are `request_changes`, `reviewed_no_decision`, and `approve_for_next_human_step`.

package/docs/releases/2.5.0.md

@@ -0,0 +1,31 @@
+# MotionLoom 2.5.0
+
+## Summary
+
+MotionLoom 2.5.0 makes the runtime capability boundary directly discoverable by an Agent while keeping execution, evidence verification and human review separate. It also publishes the repository's native Apple review alpha in the GitHub source release, with explicit limits around signing and distribution.
+
+## Added
+
+### Evidence-bound capability card
+
+`motionloom capability card --format json` exports a read-only card from the already validated capability registry. The card reports runtime status, compatibility, adapter version, verification time, inputs/outputs, evidence references, limitations, fallback and risk metadata. It fails closed if the registry evidence is missing, altered or points outside the repository.
+
+The card is discovery metadata only. It does not select or execute a runtime, refresh evidence, grant an attestation approval, set `production_approved`, open a pull request or publish an artifact. An Agent must still call capability selection immediately before execution.
+
+### Benchmark-informed discovery
+
+The research ledger records transferable patterns from public agent workflow, model-serving and AI/video repositories. This release applies only the low-risk capability-card pattern. Generation-profile metadata and hash-bound workflow/template recipes remain deferred until their own schemas, validators, provenance bindings and regression suites exist.
+
+### Native Apple review alpha
+
+The GitHub source release contains `apps/apple/`: shared Swift packages for fail-closed review contracts, timeline/review state, macOS sandbox bridge, shared macOS/iOS review UI and local-first CloudKit review metadata sync. It also includes unsigned macOS Studio and iOS/iPadOS Review targets plus Apple CI.
+
+The npm tarball intentionally remains the portable Node/Python Skill and documentation package. It does not package the Xcode source tree, sign an application, create a CloudKit production container, install an iOS Simulator runtime or submit a TestFlight build.
+
+## Verified behavior
+
+Before publication, the release target is checked with the full regression harness, documentation audit, Skill Doctor, discovery check, package dry-run/artifact inspection and GitHub Quality, Security Analysis, Documentation & Package Hygiene and MotionLoom Apple workflows.
+
+## Trust boundary
+
+Runtime capability information is not a release or approval mechanism. Capability selection still requires fresh evidence. A passing test, an intact registry, an attestation or an Apple build does not replace user review, grant `production_approved`, create a pull request or authorize a production deployment.

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.4.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.5.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.4.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.5.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
 
@@ -60,15 +60,15 @@ npm publish --access public
 
 Do not add `--provenance` unless the local npm client and its CI/provider integration explicitly support automatic npm provenance. Some workstation setups report `Automatic provenance generation not supported for provider: null`; in that case the package itself is still valid, and the supported fallback for this release is the command above without `--provenance`. Never retry by changing the version or by bypassing the package verification steps.
 
-The version `2.4.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.5.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.4.0` and a tarball URL:
+Run the following commands and confirm that they return `2.5.0` and a tarball URL:
 
 ```bash
 npm view motionloom version --registry=https://registry.npmjs.org/
-npm view motionloom@2.4.0 name version license dist.tarball dist.shasum --json \
+npm view motionloom@2.5.0 name version license dist.tarball dist.shasum --json \
   --registry=https://registry.npmjs.org/
 ```
 
@@ -78,7 +78,7 @@ Then test installation in a clean temporary directory:
 TMP_DIR="$(mktemp -d)"
 cd "$TMP_DIR"
 npm init --yes
-npm install motionloom@2.4.0
+npm install motionloom@2.5.0
 motionloom --help
 motionloom doctor
 ```

package/docs/research/ai-repository-benchmark-2026-08-16.md

@@ -0,0 +1,75 @@
+# AI Repository Benchmark — research ledger
+
+**Ngày bắt đầu:** 2026-08-16
+**Phạm vi:** Các repository/tool AI công khai có bài học workflow, packaging hoặc runtime verification có thể đánh giá cho MotionLoom. Đây không phải là danh sách khuyến nghị tích hợp dependency.
+
+## Phương pháp
+
+Mỗi candidate được kiểm tra qua nguồn chính thức, README/license, yêu cầu triển khai, bề mặt security và mức độ phù hợp với invariant MotionLoom. Star count chỉ là tín hiệu phụ; không dùng làm bằng chứng chất lượng hay an toàn. Không thực thi code bên thứ ba trong đợt nghiên cứu này.
+
+## Phát hiện ban đầu
+
+| Candidate | Nhóm | Điều nguồn chính thức xác nhận | Bài học tiềm năng cho MotionLoom | Rủi ro/không sao chép |
+|---|---|---|---|---|
+| [Coze Studio](https://github.com/coze-dev/coze-studio) | Agent workflow | Công cụ phát triển agent all-in-one với prompt, RAG, plugin, workflow; có templates, low/no-code canvas, API/SDK và self-host qua Docker Compose. README cảnh báo rõ public deployment có bề mặt registration, Python workflow execution, SSRF và API privilege risks. License Apache-2.0. | Progressive disclosure: quick setup, sau đó mới model/plugin/workflow configuration. Hiển thị explicit security posture bên cạnh workflow launch. | Không áp dụng visual canvas như authority; MotionLoom phải giữ artifact identity, runtime evidence và user review là nguồn truth. Không gọi code execution node tùy ý từ app/Dev Lab. |
+| [Dify](https://github.com/langgenius/dify) | Agent workflow | Nền tảng app LLM có workflow, RAG, agents, model management, observability và APIs; quick start rõ ràng qua Docker Compose; mô tả environment/config separation. License là Dify Open Source License dựa trên Apache-2.0 với điều kiện bổ sung. | Onboarding theo tầng: cài nhanh, dashboard init, cấu hình môi trường rõ; observability là bề mặt sản phẩm chứ không phải log ẩn. | Không sao chép license/model hosting approach; không dùng dashboard telemetry làm bằng chứng production approval. Không mở mơ hồ các provider credential vào repository. |
+| [ComfyUI](https://github.com/Comfy-Org/ComfyUI) và [workflow templates](https://github.com/Comfy-Org/workflow_templates) | Visual workflow | Node graph cho image/video/audio/3D/text; JSON save/load workflows, reusable subgraphs, templates, local API, App Mode và khả năng recover workflow/seed từ media được hỗ trợ. Repo template dùng manifest regenerated với SHA-256 mismatch gate; production chỉ deploy workflow có `status: approved`, preview có thể hiển thị trạng thái khác. | Đưa `approved/rejected/deprecated` vào index workflow/template, bắt buộc manifest hash và expose một review surface giản lược cho end user thay vì tất cả graph controls. | Không xem JSON graph/seed là provenance hoặc runtime evidence. Không nhận custom-node metadata như source tin cậy; mọi external template phải qua intake và identity binding của MotionLoom. |
+| [Wan2.1](https://github.com/Wan-Video/Wan2.1) | Video generation | Model suite hỗ trợ T2V, I2V, FLF2V, editing/VACE; README công bố rõ task/resolution/model và links checkpoint. Có integration Diffusers/ComfyUI và nêu ràng buộc VRAM, resolution stability, model-specific prompt guidance. | `generation-profile` phải tách task/model/resolution/frames/provider; lấy capability, hardware expectation và model/checkpoint identity thành evidence thay vì claim chung chung “AI video generated”. | Không tích hợp model runtime vào MotionLoom core và không suy diễn quality từ model name. Kết quả video/pose từ bất kỳ provider nào vẫn là `ai_generated`, cần geometry/consistency/runtime review. |
+| [HunyuanVideo](https://github.com/Tencent-Hunyuan/HunyuanVideo) | Video/human animation | Cung cấp inference/weights, I2V, Avatar, custom generation, benchmark và các integration. README ghi rõ dependency CUDA/Linux, memory requirement cao và phạm vi environment đã test. | Cần consumer-facing capability card: platform, runtime, GPU/memory, tested environment, source model/version và failure mode trước khi Agent đề xuất một generation route. | Không hứa “one-click” nếu phần cứng/OS không đáp ứng. Không dùng self-reported benchmark để thay runtime verification hay human approval. |
+| [Xinference](https://github.com/xorbitsai/inference) | Local model serving | Model server self-hosted cho language, speech và multimodal; có OpenAI-compatible REST, RPC, CLI, WebUI, Docker/Kubernetes examples và thể hiện rõ CPU/Metal/GPU/distributed capabilities. README có migration notes cho breaking change. | Đăng ký **capability card** và compatibility/migration note theo adapter version; Agent chỉ đề xuất provider/runtime đã thỏa platform, hardware, credential và health-check profile. | MotionLoom không trở thành model server, không mở endpoint model nội bộ ra artifact/Dev Lab, không tự chạy Docker/model download từ brief người dùng. |
+| [ModelScope](https://github.com/modelscope/modelscope) | Model registry / MaaS | Unified abstraction cho inference, training, evaluation, export, deployment; model/dataset hub, version/cache management, modular task pipeline và Docker images theo CPU/GPU. README cũng nêu dependency/OS incompatibilities của một số model. | Tách **identity** (provider/model/checkpoint/version/license) khỏi **capability** (task, input constraints, platform, hardware, known limitations), và fail closed khi metadata tối thiểu thiếu. | Không coi registry listing là license/provenance đã xác minh, không nhận “few lines to run” là bằng chứng reproducibility hoặc cross-platform support. |
+| [CogVideo](https://github.com/zai-org/CogVideo) | Video generation | README công bố task T2V/I2V/continuation, model task matrix, resolution/frame divisibility, precision, VRAM/timing benchmark, requirement Python và model-specific license notes. Nó cũng nêu prompt optimization và external model dependence. | Mở rộng `generation-profile` thành matrix bắt buộc: task, model/checkpoint, resolution, frame formula, precision, expected VRAM/time, prompt-transform provider và source URLs. | Không chuyển benchmark tự công bố thành SLA; không biến prompt enhancement bởi external LLM thành `artist_authored` hoặc ẩn provider ở provenance. |
+
+## Metadata GitHub tại thời điểm khảo sát
+
+Snapshot dưới đây được lấy bằng GitHub CLI lúc **2026-08-16**. Nó chỉ là tín hiệu maintenance/community, không phải chứng nhận security, chất lượng hay tính phù hợp để tích hợp.
+
+| Repository | Stars / forks | License GitHub nhận diện | Cập nhật gần nhất lúc khảo sát | Kết luận sàng lọc |
+|---|---:|---|---|---|
+| `coze-dev/coze-studio` | 21,453 / 3,117 | Apache-2.0 | 2026-08-16 | Mature reference cho progressive onboarding và self-host security posture. Không là dependency candidate. |
+| `langgenius/dify` | 152,585 / 24,091 | Other (Dify Open Source License) | 2026-08-16 | Reference tốt cho product observability; cần tránh mọi code/license reuse. |
+| `Comfy-Org/ComfyUI` | 127,883 / 15,057 | GPL-3.0 | 2026-08-16 | Reference tốt cho workflow packaging/manifest; không phù hợp để import code vào package MotionLoom. |
+| `Wan-Video/Wan2.1` | 16,833 / 3,364 | Apache-2.0 | 2026-08-16 | Reference cho generation task/capability matrix và điều kiện runtime. |
+| `Tencent-Hunyuan/HunyuanVideo` | 12,429 / 1,312 | Other | 2026-08-16 | Reference cho disclosure GPU/environment; license và model terms cần review theo từng checkpoint. |
+| `zai-org/CogVideo` | 12,956 / 1,326 | Apache-2.0 | 2026-08-16 | Reference cho matrix resolution/frames/precision/VRAM; không coi benchmark là SLA. |
+| `xorbitsai/inference` | 9,500 / 858 | Apache-2.0 | 2026-08-16 | Reference cho adapter capability/health-check/migration policy; không biến MotionLoom thành model server. |
+| `modelscope/modelscope` | 9,091 / 961 | Apache-2.0 | 2026-08-16 | Reference cho tách model identity khỏi capability; registry listing không thay provenance. |
+
+## Decision log sơ bộ
+
+| Pattern | Quyết định | Lý do và guardrail MotionLoom |
+|---|---|---|
+| Quick start theo tầng, chỉ mở gate chuyên sâu khi cần | **Áp dụng ngay** | Phù hợp onboarding một-lệnh hiện có; deep gates vẫn fail-closed và không bị ẩn khỏi artifact. |
+| Runtime capability card có adapter/platform/constraint/evidence | **Đã triển khai** | `motionloom capability card --format json` xuất projection chỉ đọc từ registry đã validate; không làm thay provenance, runtime evidence hoặc selection. |
+| Generation profile có model/checkpoint/platform/hardware/constraint | **Hoãn có gate** | Bổ sung thông tin quyết định cho Agent trước khi gọi provider chỉ sau khi có schema, validator, provenance binding và regression; không mở provider credential trong core. |
+| Hash-bound workflow/template manifest và trạng thái `approved/rejected/deprecated` | **Thí nghiệm có gate** | Chỉ áp dụng cho profile/template nội bộ sau khi có schema, validator và regression; không đồng nhất template approval với `production_approved`. |
+| Visual node canvas hoặc dashboard như execution authority | **Từ chối** | Làm mờ artifact identity và mở khả năng thực thi node tùy ý, trái mô hình deterministic review-first. |
+| Nhúng model server, tự tải model, hoặc provider credential vào MotionLoom core | **Từ chối** | Tăng bề mặt attack, chi phí vận hành và rủi ro secret; chỉ dùng adapter capability/card và explicit user setup. |
+| Tuyên bố generated asset “artist-authored” vì prompt/model tốt | **Từ chối** | Vi phạm provider-truthful provenance và human-governed production boundary. |
+
+## Cải tiến đã áp dụng
+
+Capability card được triển khai như một **projection chỉ đọc** trên `capability-registry.json`, không phải registry hay policy thứ hai. Lệnh `motionloom capability card --format json` xác thực hash evidence trước khi xuất `id`, declared status, adapter version, compatibility, thời điểm kiểm chứng, inputs/outputs, evidence reference, limitations, fallback, risk và side-effect level. Card luôn nhắc Agent gọi selection trước execution; selection mới áp dụng evidence freshness/integrity.
+
+| Hạng mục | Trạng thái | Cách kiểm chứng | Guardrail giữ nguyên |
+|---|---|---|---|
+| `motionloom capability card --format json` | Hoàn thành | Thử bằng registry repository thật và npm shortcut `pnpm intelligence:card` | Không chọn runtime, không refresh evidence, không tạo commit/PR. |
+| Validation registry trước export | Hoàn thành | Regression cố ý sửa SHA-256 evidence; card trả lỗi non-zero | Fail-closed khi evidence thiếu, sai hash hoặc thoát repository. |
+| Agent-facing CLI/help, npm script, agent-card, README | Hoàn thành | `pnpm docs:check`, CLI help và regression alias | Chỉ công bố discovery; không nâng `scaffold_only` thành `verified`. |
+| Generation profile model/checkpoint/hardware | Chưa triển khai | Chưa có schema hay validator | Không suy diễn provider/model identity; tiếp tục dùng provenance/intake hiện hữu. |
+| Hash-bound workflow/template recipe | Chưa triển khai | Cần schema riêng, approval-state vocabulary và test | Không đồng nhất template approval với `production_approved`. |
+
+Kết quả regression: `pnpm test` pass toàn bộ suite, bao gồm export card, alias CLI và rejection với evidence bị sửa. `pnpm docs:check` và `git diff --check` cũng pass. Không có dependency hay code bên thứ ba nào được thêm từ các repository khảo sát.
+
+## Nguồn
+
+1. [Coze Studio README và self-host/security guidance](https://github.com/coze-dev/coze-studio)
+2. [Dify README, self-hosting, observability và license notice](https://github.com/langgenius/dify)
+3. [Dify Cloud product overview](https://dify.ai/)
+4. [ComfyUI README: workflow JSON, API, App Mode và offline posture](https://github.com/Comfy-Org/ComfyUI)
+5. [ComfyUI workflow templates: manifest, SHA-256 validation và release filtering](https://github.com/Comfy-Org/workflow_templates)
+6. [Wan2.1 README: task matrix, integration và inference requirements](https://github.com/Wan-Video/Wan2.1)
+7. [HunyuanVideo README: model scope, hardware requirements và test environment](https://github.com/Tencent-Hunyuan/HunyuanVideo)
+8. [Xinference README: local serving, APIs, deployment và migration](https://github.com/xorbitsai/inference)
+9. [ModelScope README: MaaS abstraction, registry, pipeline và platform constraints](https://github.com/modelscope/modelscope)
+10. [CogVideo README: video task/memory matrix, precision, model scope và prompt guidance](https://github.com/zai-org/CogVideo)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motionloom",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "type": "module",
   "packageManager": "pnpm@11.20.0",
   "description": "MotionLoom: project-aware animation Skill with Agent interoperability, graph, provenance, Motion IR, runtime telemetry, Visual Truth, Remediation Learning, DSSE-compatible signed attestation, external evidence verification and Dev Lab review.",
@@ -19,6 +19,7 @@
     "SKILL.md",
     "LICENSE",
     "agent-card.json",
+    "capability-registry.json",
     "bin",
     "scripts",
     "src",
@@ -142,6 +143,7 @@
     "intelligence": "node bin/motionloom.mjs intelligence",
     "intelligence:registry": "node bin/motionloom.mjs intelligence capabilities build --output capability-registry.json",
     "intelligence:registry:check": "node bin/motionloom.mjs intelligence capabilities validate --path capability-registry.json",
+    "intelligence:card": "node bin/motionloom.mjs capability card --format json",
     "intelligence:p1": "node bin/motionloom.mjs intelligence",
     "quality:p1": "node bin/motionloom.mjs quality-gate --require-intelligence --require-p1 --require-benchmark",
     "eval:intelligence": "node bin/motionloom.mjs eval-intelligence",

package/scripts/attestation.py

@@ -41,6 +41,11 @@ def dsse_pae(payload_type: str, body: bytes) -> bytes:
     return b"DSSEv1 " + str(len(payload_type_bytes)).encode("ascii") + b" " + payload_type_bytes + b" " + str(len(body)).encode("ascii") + b" " + body
 
 
+def is_macos_var_alias(path: Path) -> bool:
+    """Allow only macOS's documented lexical alias `/var` -> `/private/var`."""
+    return path == Path("/var") and path.is_symlink() and path.resolve() == Path("/private/var")
+
+
 def reject_symlink_components(path: Path) -> None:
     current = Path(path.anchor) if path.anchor else Path(".")
     for part in path.parts:
@@ -48,6 +53,9 @@ def reject_symlink_components(path: Path) -> None:
             continue
         current = current / part
         if current.is_symlink():
+            if is_macos_var_alias(current):
+                current = current.resolve()
+                continue
             raise ValueError(f"symlink path component is not allowed: {path}")
 
 

package/scripts/evidence-verifier.py

@@ -34,14 +34,21 @@ def parse_json(path: Path) -> object:
     return json.loads(path.read_text(encoding="utf-8"))
 
 
-def reject_symlink_components(path: Path) -> None:
-    current = Path(path.anchor) if path.anchor else Path(".")
-    for part in path.parts:
-        if part in (path.anchor, ""):
-            continue
+def reject_symlink_within_root(root: Path, relative: Path, label: str) -> None:
+    """Reject links inside an untrusted root, not symlinked system parents.
+
+    macOS exposes /var as a symlink to /private/var. A fixture rooted in mktemp
+    must be valid when the root itself is a real directory, while an evidence
+    path must never traverse a symlink at or below that root.
+    """
+    root = root.absolute()
+    if root.is_symlink():
+        raise ValueError(f"symlink root is not allowed: {label}")
+    current = root
+    for part in relative.parts:
         current = current / part
         if current.is_symlink():
-            raise ValueError(f"symlink path component is not allowed: {path}")
+            raise ValueError(f"symlink path component is not allowed: {label}")
 
 
 def safe_relative_file(root: Path, relative: object, label: str) -> Path:
@@ -53,7 +60,7 @@ def safe_relative_file(root: Path, relative: object, label: str) -> Path:
     if any(part in ("", ".", "..") for part in candidate.parts):
         raise ValueError(f"{label} contains unsafe path components")
     joined = root / candidate
-    reject_symlink_components(joined)
+    reject_symlink_within_root(root, candidate, label)
     resolved_root = root.resolve()
     resolved = joined.resolve(strict=False)
     if resolved != resolved_root and resolved_root not in resolved.parents:
@@ -81,8 +88,10 @@ def verify(scene_dir: Path, task_dir: Path, runtime_evidence_name: str, max_age_
             raise ValueError("scene directory name is unsafe")
         if not SAFE_NAME.fullmatch(task_dir.name):
             raise ValueError("task directory name is unsafe")
-        reject_symlink_components(scene_dir)
-        reject_symlink_components(task_dir)
+        if scene_dir.is_symlink():
+            raise ValueError("scene directory symlink is not allowed")
+        if task_dir.is_symlink():
+            raise ValueError("task directory symlink is not allowed")
         manifest_path = safe_relative_file(scene_dir, "manifest.json", "manifest.json")
         source_manifest = parse_json(manifest_path)
         if not isinstance(source_manifest, dict):

package/scripts/intelligence.py

@@ -82,14 +82,22 @@ def safe_relative(value: str) -> Path:
     return path
 
 
-def has_symlink_component(path: Path) -> bool:
-    current = path
-    while True:
+def has_symlink_component(path: Path, root: Path) -> bool:
+    """Reject symlinks at or below a trusted root, not system parent aliases."""
+    root = root.absolute()
+    path = path.absolute()
+    try:
+        relative = path.relative_to(root)
+    except ValueError:
+        return True
+    if root.is_symlink():
+        return True
+    current = root
+    for component in relative.parts:
+        current = current / component
         if current.is_symlink():
             return True
-        if current.parent == current:
-            return False
-        current = current.parent
+    return False
 
 
 def within(root: Path, candidate: Path) -> bool:
@@ -104,7 +112,7 @@ def task_artifact(task_dir: Path, relative: str) -> dict[str, Any]:
     safe = safe_relative(relative)
     raw_path = task_dir / safe
     path = raw_path.resolve()
-    if has_symlink_component(raw_path) or not within(task_dir, path) or not path.is_file():
+    if has_symlink_component(raw_path, task_dir) or not within(task_dir, path) or not path.is_file():
         raise ValueError(f"artifact is missing or outside task bundle: {relative}")
     return {
         "id": relative.replace("/", ":"),
@@ -179,7 +187,7 @@ def graph_build(args: argparse.Namespace) -> int:
 
     task_files = []
     for path in sorted(task_dir.rglob("*")):
-        if has_symlink_component(path):
+        if has_symlink_component(path, task_dir):
             raise ValueError(f"task bundle cannot contain symlinked artifact: {path.relative_to(task_dir)}")
         if not path.is_file():
             continue
@@ -363,7 +371,7 @@ def provenance_validate(args: argparse.Namespace) -> int:
     if not isinstance(attestation, dict) or not isinstance(attestation.get("steps"), list):
         raise ValueError("provenance attestation must contain steps")
     task_dir = task_dir_from(args.task_dir)
-    if has_symlink_component(raw_path) or not within(task_dir, path):
+    if has_symlink_component(path, task_dir) or not within(task_dir, path):
         raise ValueError("provenance attestation must be a non-symlink file inside task bundle")
     if attestation.get("task_id") != read_json(task_dir / "task.json").get("task_id"):
         raise ValueError("provenance task_id does not match task.json")
@@ -400,13 +408,13 @@ def capability_build(args: argparse.Namespace) -> int:
     if not isinstance(card, dict):
         raise ValueError("agent-card must be an object")
     raw_evidence_path = Path(args.evidence).expanduser() if args.evidence else ROOT / "scripts" / "runtime-adapters.mjs"
-    if has_symlink_component(raw_evidence_path):
-        raise ValueError("capability evidence cannot traverse symlinks")
     evidence_path = raw_evidence_path.resolve()
     if not evidence_path.is_file():
         raise ValueError(f"capability evidence path does not exist: {evidence_path}")
     if not within(ROOT, evidence_path):
         raise ValueError("capability evidence must be inside the repository")
+    if has_symlink_component(raw_evidence_path, ROOT):
+        raise ValueError("capability evidence cannot traverse symlinks")
     evidence_ref = evidence_path.relative_to(ROOT).as_posix()
     evidence_kind = args.evidence_kind
     entries = []
@@ -445,6 +453,13 @@ def capability_build(args: argparse.Namespace) -> int:
 def capability_validate(args: argparse.Namespace) -> int:
     registry_path = Path(args.path).expanduser().resolve()
     registry = read_json(registry_path)
+    capability_registry_validate(registry)
+    ids = [entry.get("id") for entry in registry["capabilities"]]
+    print(json.dumps({"status": "valid", "kind": "capability-registry", "capability_count": len(ids)}, ensure_ascii=False))
+    return 0
+
+
+def capability_registry_validate(registry: Any) -> None:
     if not isinstance(registry, dict) or not isinstance(registry.get("capabilities"), list):
         raise ValueError("capability registry must contain capabilities")
     ids = [entry.get("id") for entry in registry["capabilities"]]
@@ -453,13 +468,61 @@ def capability_validate(args: argparse.Namespace) -> int:
     for entry in registry["capabilities"]:
         for evidence in entry.get("evidence", []):
             evidence_path = ROOT / safe_relative(str(evidence.get("path", "")))
-            if has_symlink_component(evidence_path) or not within(ROOT, evidence_path):
+            if has_symlink_component(evidence_path, ROOT) or not within(ROOT, evidence_path):
                 raise ValueError(f"capability evidence escapes repository: {evidence.get('path')}")
             if not evidence_path.is_file():
                 raise ValueError(f"capability evidence missing: {evidence.get('path')}")
             if digest_file(evidence_path) != evidence.get("sha256"):
                 raise ValueError(f"capability evidence hash mismatch: {evidence.get('path')}")
-    print(json.dumps({"status": "valid", "kind": "capability-registry", "capability_count": len(ids)}, ensure_ascii=False))
+
+
+def capability_card(args: argparse.Namespace) -> int:
+    """Export a read-only, evidence-bound capability projection for Agents.
+
+    The card deliberately exposes declared registry state only. It does not
+    select a runtime, refresh evidence, grant approval, or change policy.
+    Callers must run ``capabilities select`` before execution.
+    """
+    registry = read_json(Path(args.registry).expanduser().resolve())
+    capability_registry_validate(registry)
+    capabilities = []
+    for entry in registry["capabilities"]:
+        capabilities.append({
+            "id": entry.get("id"),
+            "kind": entry.get("kind"),
+            "declared_status": entry.get("status"),
+            "adapter_version": entry.get("adapter_version"),
+            "last_verified_at": entry.get("last_verified_at"),
+            "inputs": entry.get("inputs", []),
+            "outputs": entry.get("outputs", []),
+            "compatibility": entry.get("compatibility", {}),
+            "evidence": entry.get("evidence", []),
+            "limitations": entry.get("limitations", []),
+            "fallback": entry.get("fallback", ""),
+            "risk_level": entry.get("risk_level"),
+            "side_effect_level": entry.get("side_effect_level"),
+        })
+    card = {
+        "schema_version": "0.1",
+        "kind": "motionloom-capability-card",
+        "registry": {
+            "registry_id": registry.get("registry_id"),
+            "schema_version": registry.get("schema_version"),
+            "generated_at": registry.get("generated_at"),
+            "selection_policy": registry.get("selection_policy", {}),
+        },
+        "capabilities": capabilities,
+        "selection": {
+            "required": True,
+            "command": "motionloom capability select --registry <capability-registry.json> --capability <runtime.id>",
+            "note": "This card is discovery metadata. Select validates evidence freshness and integrity before a runtime may be used.",
+        },
+        "review": {
+            "production_approval": "not_derived",
+            "attestation_approval": "not_derived",
+        },
+    }
+    print(json.dumps(card, ensure_ascii=False))
     return 0
 
 
@@ -488,7 +551,7 @@ def capability_select(args: argparse.Namespace) -> int:
         for evidence in entry.get("evidence", []):
             try:
                 evidence_path = ROOT / safe_relative(str(evidence.get("path", "")))
-                if has_symlink_component(evidence_path) or not within(ROOT, evidence_path) or not evidence_path.is_file() or digest_file(evidence_path) != evidence.get("sha256"):
+                if has_symlink_component(evidence_path, ROOT) or not within(ROOT, evidence_path) or not evidence_path.is_file() or digest_file(evidence_path) != evidence.get("sha256"):
                     evidence_ok = False
                     break
             except (OSError, ValueError):
@@ -1383,7 +1446,7 @@ def replay_capture(args: argparse.Namespace) -> int:
     task_rel = task_dir.relative_to(root).as_posix()
     records = []
     for path in sorted(task_dir.rglob("*")):
-        if has_symlink_component(path):
+        if has_symlink_component(path, task_dir):
             raise ValueError(f"task bundle cannot contain symlinked artifact: {path.relative_to(task_dir)}")
         if not path.is_file():
             continue
@@ -1417,7 +1480,7 @@ def replay_verify(args: argparse.Namespace) -> int:
         task_rel = safe_relative(str(bundle.get("task_dir", "")))
         task_dir = (root / task_rel).resolve()
         task = read_json(task_dir / "task.json")
-        if has_symlink_component(root / task_rel) or not within(root, task_dir) or not task_dir.is_dir():
+        if has_symlink_component(root / task_rel, root) or not within(root, task_dir) or not task_dir.is_dir():
             mismatches.append({"path": str(task_rel), "reason": "task_dir_invalid"})
         else:
             if bundle.get("task_id") != task.get("task_id"):
@@ -1430,7 +1493,7 @@ def replay_verify(args: argparse.Namespace) -> int:
         safe = safe_relative(str(record.get("path", "")))
         raw_path = root / safe
         path = raw_path.resolve()
-        if has_symlink_component(raw_path) or not within(root, path) or "task_dir" in locals() and not within(task_dir, path) or not path.is_file():
+        if has_symlink_component(raw_path, root) or not within(root, path) or "task_dir" in locals() and not within(task_dir, path) or not path.is_file():
             mismatches.append({"path": str(safe), "reason": "missing"})
             continue
         actual = digest_file(path)
@@ -1449,7 +1512,7 @@ def replay_mismatches(bundle: dict[str, Any], root: Path) -> list[dict[str, Any]
         safe = safe_relative(str(record.get("path", "")))
         raw_path = root / safe
         path = raw_path.resolve()
-        if has_symlink_component(raw_path) or not within(root, path) or not path.is_file():
+        if has_symlink_component(raw_path, root) or not within(root, path) or not path.is_file():
             mismatches.append({"path": str(safe), "reason": "missing"})
             continue
         actual = digest_file(path)
@@ -1563,6 +1626,10 @@ def add_subcommands(parser: argparse.ArgumentParser) -> None:
     capabilities_select_parser.add_argument("--status", default="verified")
     capabilities_select_parser.add_argument("--allow-scaffold-only", action="store_true")
     capabilities_select_parser.set_defaults(func=capability_select)
+    capabilities_card_parser = capabilities_sub.add_parser("card", help="export a read-only capability card for Agent discovery")
+    capabilities_card_parser.add_argument("--registry", default=str(ROOT / "capability-registry.json"))
+    capabilities_card_parser.add_argument("--format", choices=["json"], default="json")
+    capabilities_card_parser.set_defaults(func=capability_card)
 
     replay = sub.add_parser("replay", help="capture or verify clean-root integrity replay bundle")
     replay_sub = replay.add_subparsers(dest="action", required=True)

package/tests/scripts/run_tests.py

@@ -554,6 +554,35 @@ def test_intelligence_core_contracts():
             "--registry", str(registry), "--capability", "runtime.rive",
         ], capture_output=True, text=True)
         check("intelligence selects verified runtime", selected.returncode == 0 and '"status": "verified"' in selected.stdout)
+
+        capability_card = subprocess.run([
+            sys.executable, str(intelligence), "capabilities", "card",
+            "--registry", str(registry), "--format", "json",
+        ], capture_output=True, text=True)
+        capability_card_data = json.loads(capability_card.stdout) if capability_card.returncode == 0 else {}
+        rive_card = next((entry for entry in capability_card_data.get("capabilities", []) if entry.get("id") == "runtime.rive"), {})
+        check(
+            "intelligence exports read-only capability card",
+            capability_card.returncode == 0
+            and capability_card_data.get("kind") == "motionloom-capability-card"
+            and capability_card_data.get("selection", {}).get("required") is True
+            and capability_card_data.get("review", {}).get("production_approval") == "not_derived"
+            and rive_card.get("declared_status") == "verified"
+            and rive_card.get("last_verified_at"),
+            capability_card.stderr.strip(),
+        )
+
+        capability_alias = subprocess.run([
+            "node", str(ROOT / "bin/motionloom.mjs"), "capability", "card",
+            "--registry", str(registry), "--format", "json",
+        ], capture_output=True, text=True)
+        capability_alias_data = json.loads(capability_alias.stdout) if capability_alias.returncode == 0 else {}
+        check(
+            "motionloom capability alias exports card",
+            capability_alias.returncode == 0 and capability_alias_data.get("kind") == "motionloom-capability-card",
+            capability_alias.stderr.strip(),
+        )
+
         scaffold = subprocess.run([
             sys.executable, str(intelligence), "capabilities", "select",
             "--registry", str(registry), "--capability", "runtime.spine",
@@ -582,6 +611,11 @@ def test_intelligence_core_contracts():
             "--registry", str(tampered_path), "--capability", "runtime.rive",
         ], capture_output=True, text=True)
         check("intelligence blocks tampered capability evidence", tampered_select.returncode != 0)
+        tampered_card = subprocess.run([
+            sys.executable, str(intelligence), "capabilities", "card",
+            "--registry", str(tampered_path), "--format", "json",
+        ], capture_output=True, text=True)
+        check("intelligence blocks capability card with tampered evidence", tampered_card.returncode != 0)
 
         replay = subprocess.run([
             sys.executable, str(intelligence), "replay", "capture",
@@ -952,6 +986,16 @@ def test_quality_workflow_rebuilds_replay_after_generated_artifacts():
         setup_tests.returncode == 0 and "setup onboarding tests: PASS" in setup_tests.stdout,
         setup_tests.stdout.strip() or setup_tests.stderr.strip(),
     )
+    apple_contract_tests = subprocess.run(
+        [sys.executable, str(ROOT / "tests/scripts/test_apple_contracts.py")],
+        capture_output=True,
+        text=True,
+    )
+    check(
+        "Apple review contracts preserve hash binding and human-governed boundaries",
+        apple_contract_tests.returncode == 0 and "apple contract tests: PASS" in apple_contract_tests.stdout,
+        apple_contract_tests.stdout.strip() or apple_contract_tests.stderr.strip(),
+    )
     visual_tests = subprocess.run(
         [sys.executable, str(ROOT / "tests/scripts/test_visual_truth.py")],
         capture_output=True,