feat(zcode-remotion): add reliable Remotion video workflow

[AIwork4me]

User problem

AI agents can generate Remotion code, but generated code is not the same as a reliable video deliverable. Developers still have to connect official skill installation, environment checks, task routing, visual QA before an expensive render, and final output verification.

zcode-remotion packages that reliability layer for ZCode while keeping Remotion's official Agent Skills as the domain-knowledge source.

What the plugin provides

• remotion skill — triggers on Remotion / video / animation requests in English or Chinese; bootstraps the official Remotion skills, preflights the environment, routes to the relevant official skill, and uses a representative-still → Agent visual-QA → final-render → output-verification loop.
• remotion-setup command — installs or repairs the official remotion-dev/skills set and verifies the same requested project/user scope on disk.
• remotion-doctor command — reports Node, package manager, official-skill integrity/version, Remotion project consistency, browser readiness and license awareness without conflating unrelated version sources.
• remotion-update command — follows the official Remotion upgrade path, refreshes the recorded official-skill set, and verifies package/skill consistency.
• Compatibility state — records the last verified Remotion / official-skills / Mediabunny baseline. It is explicitly a verified baseline, not a claim that newer releases are incompatible.

The plugin does not vendor Remotion's official Agent Skills.

Why the Marketplace ID is zcode-remotion

The source integration historically uses a local plugin name of remotion, but the official Marketplace ID here is deliberately zcode-remotion:

• it makes the third-party ZCode integration identity explicit;
• it avoids taking the bare Remotion product name or colliding with a future Remotion-maintained plugin;
• the bundled auto-trigger skill remains named remotion, so natural Remotion/video requests still route cleanly.

Display name: Remotion for ZCode.

Why this is distinct from existing video plugins

This is a programmatic-video creation/reliability workflow for Remotion + React. It does not duplicate video-agent-kit (video editing/tooling) or video2code (web UI replication): its focus is creating and verifying Remotion compositions through an Agent workflow using Remotion's official skills.

Marketplace registration and provenance

• Plugin: zcode-remotion v0.2.5
• Category: productivity
• Source project: https://github.com/AIwork4me/zcode-remotion
• Source commit used as the functional baseline: 2a9903c2cfc167f11cbec3009a2d7b2161b03492
• English + Chinese user documentation included.

This is the first zcode-remotion artifact in this Marketplace. plugins/zcode-remotion/UPSTREAM.md explicitly records that this package is a curated Marketplace distribution adaptation, not a byte-for-byte source mirror.

Marketplace-specific adaptations include required bilingual manifest metadata, Marketplace-focused docs, installed-plugin-root-safe helper resolution, tighter Agent instructions, and exclusion of source-repository-only CI/demo/release-governance assets.

Runtime-path safety

Marketplace users run the Agent from their own projects, not from the source repository. The packaged workflows therefore resolve ZCode's ZCODE_PLUGIN_ROOT before invoking bundled helper scripts; they never assume ./scripts/... exists in the user's workspace.

A focused repository test locks this contract and rejects a regression back to workspace-relative helper paths.

Dependencies, network access, permissions and side effects

Requirements

• Node.js >=18.
• A writable project directory.
• Network access when packages, official Remotion skills, docs/releases, or Remotion's browser runtime must be downloaded.

Network access

Depending on the requested workflow, the Agent may contact:

• npm registry;
• remotion-dev/skills on GitHub;
• Remotion documentation / releases; and
• Remotion browser-download endpoints.

Local execution

The workflows may run:

• node / npx;
• the project's detected package manager (npm, pnpm, yarn, or bun);
• official Remotion CLI commands;
• the official skills installer; and
• optional ffprobe for media metadata verification.

File writes

• Remotion source/dependency/output files in the user's selected project.
• Official Remotion skill files in user scope (~/.zcode/skills/ / ~/.agents/skills/) or explicitly requested project scope (.zcode/skills/).

Not used

• no credentials / API keys;
• no Hooks;
• no MCP servers;
• no background daemon or local service;
• no bundled prebuilt binaries.

These behaviors are documented in both plugin READMEs.

Licensing / third-party provenance

• The ZCode integration layer is original work under MIT (plugins/zcode-remotion/LICENSE).
• Remotion Agent Skills are not redistributed; the user's machine fetches them from the official remotion-dev/skills source.
• NOTICE.md links to Remotion's current upstream licensing information.
• UPSTREAM.md records the source repository/commit and exact distribution adaptations.

Test coverage included in this PR

tests/test_zcode_remotion_plugin.py is a zero-network contract test covering:

• manifest / marketplace name, version and description_i18n alignment;
• canonical 12-skill topology and proof that official skills are not vendored;
• routing coverage for every recorded official skill;
• router metadata version sync;
• ZCODE_PLUGIN_ROOT helper-path safety;
• command frontmatter descriptions; and
• bilingual network / command / write / licensing disclosure.

Verification status

Source-project E2E/CI is useful background evidence only; this Marketplace
package earns its own runtime evidence.

• upstream repository validate.py passes for this exact PR
• upstream repository build_dist.py passes for this exact PR
• upstream repository unit tests pass, including test_zcode_remotion_plugin.py
• exact PR artifact exercised in ZCode 0.16.5: plugin/skill/commands discovered,
  official Remotion Skills bootstrapped to 12/12 COMPLETE, and one prompt
  completed representative-still visual QA → verified MP4

Runtime acceptance evidence:
#6 (comment)

Supported desktop Settings → Plugins Marketplace installation and
Settings → Skills → Refresh UI flows were not exercised in this pre-merge
test; that limitation is explicitly documented in the acceptance evidence.

Contribution checklist

• unique kebab-case plugin ID (zcode-remotion)
• .zcode-plugin/plugin.json included
• manifest / marketplace name, version, and localized descriptions aligned
• supported category (productivity)
• equivalent README.md and README_CN.md
• at least one discoverable component (1 skill + 3 commands)
• network access, commands, file writes, dependencies and side effects documented
• licensing / provenance documented
• no secrets, private endpoints, customer data or machine-specific absolute paths
• focused tests added for the packaged runtime contract
• official upstream CI green
• live current-ZCode Marketplace install exercised

[AIwork4me]

Current ZCode runtime acceptance — PASS

I ran an acceptance test against the exact PR head 9c7b9c0eabdcaf15cf78e54ceccc547506961659 on Windows 11 with ZCode 0.16.5 / Node 24.

The acceptance evidence is isolated on a separate branch whose first evidence commit is a direct child of the PR head. The PR branch itself was not modified.

Evidence branch:
https://github.com/AIwork4me/zcode-plugins/tree/acceptance/pr6-marketplace-e2e

Full report:
https://github.com/AIwork4me/zcode-plugins/blob/acceptance/pr6-marketplace-e2e/acceptance/2026-09-02-pr6/REPORT.md

Final MP4:
https://github.com/AIwork4me/zcode-plugins/blob/acceptance/pr6-marketplace-e2e/acceptance/2026-09-02-pr6/run2-definitive/promo/out/ZCode-Remotion-Plugin-Promo.mp4

Results

• ZCode engine discovery: PASS — zcode-remotion v0.2.5 enabled; bundled remotion skill and all 3 commands discovered by fresh engine processes.
• Official Remotion Skills bootstrap: PASS — starting state absent; /remotion-setup invoked the official remotion-dev/skills installer and verified 12/12 COMPLETE.
• Initial video prompts: 1
• Follow-up workflow inputs / approval checkpoints: 0
• Official Remotion skills consulted during the run: PASS
• Representative stills: PASS — 7 QA frames across scenes and transitions.
• Agent visual QA: PASS — the agent actually read the rendered images, identified frame 100 as a transition-state frame rather than a layout defect, rendered stable comparison frames, and re-inspected them before the full render.
• Full render: PASS — 300/300 frames.
• Final output verification: PASS — independently confirmed with ffprobe.

Final artifact:

• duration: 10.048 s
• resolution: 1920×1080
• video: H.264, 30 fps
• size: 3,493,835 bytes

No plugin source files were modified during the acceptance run.

Important evidence boundary

The supported desktop Marketplace UI install flow was NOT TESTED.

The root marketplace id is zcode-plugins-official, which ZCode reserves for the official source, so a fork checkout cannot be added as a second local marketplace under that same id. For this pre-merge acceptance run, the tester backed up and re-pointed ZCode's local official-marketplace persistence to the PR checkout, then verified discovery and behavior using fresh real ZCode engine processes.

Therefore this evidence establishes:

exact PR plugin artifact → ZCode engine discovery → official Skills bootstrap → one prompt → real still visual QA → verified MP4

It does not claim that the desktop Settings → Plugins install flow or Settings → Skills → Refresh UI was exercised.

Run 1 also exposed a harness-only limitation: a text-only default model could not inspect attached stills. The definitive run used a vision-capable model and repeated the journey from a fresh empty workspace; that run is the basis of this PASS verdict.

Runtime acceptance verdict: PASS.

The remaining repository CI checks are currently awaiting maintainer approval to run on this fork PR; action_required is an approval gate, not a validation failure.