Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

docs: prepare OpenMotion main cutover with approved integration cover

joeylee12629-star4d50b9dd7c9a
diff --git a/docs/motion-release-activation.md b/docs/motion-release-activation.md
index ff65b747..87b56fee 100644
--- a/docs/motion-release-activation.md
+++ b/docs/motion-release-activation.md
@@ -1,39 +1,29 @@
-# Motion release controls on the legacy default branch
+# OpenMotion repository and release activation
-This branch retains the legacy HTML Anything application. The Motion application still lives at the root of `feature/motion`. Registration PR #222 is merged into `main`. The follow-up controls below must be merged together with their matching Motion source changes before using the DEV candidate route. These additions do not replace the application, change package/workspace metadata, merge Motion into main, or publish anything on a push/merge.
+OpenMotion is the application on `main` in `nexu-io/html-anything`. Daily integration and manual release operations continue on `feature/motion`; the default branch remains `main`. The former HTML Anything application remains available on [legacy](https://github.com/nexu-io/html-anything/tree/legacy).
-## Scope and provenance
+The default-branch cutover carries the integrated Motion workflows, helpers, templates and tests. It replaces the older registration-only copies on main. A push or merge runs validation; it does not publish a package, advance npm tags or write release storage.
-The three manual workflows, their runtime helpers, installation/acceptance templates and deterministic tests were initially copied without modification from reviewed PR [#214](https://github.com/nexu-io/html-anything/pull/214), source commit `de45dadea282214762c7b3123cea7e6b1044f26f`. The test-channel follow-up copies the same 18 shared control files byte-for-byte from Motion commit `94d15d656eb085f98067867502418bb99c7de0e9` and updates this control set to require DEV candidates and defer npm test promotion until native checks pass. No application business logic or private Git history is imported; shared runtime helpers and tests are included as control dependencies. The extra `Motion release controls` CI job runs only syntax checks and simulated-service tests with read-only permissions; the legacy CI commands and permissions are preserved. Its runner is pinned to Ubuntu 24.04 because the locked Playwright cannot install browsers on the Ubuntu 26.04 image now selected by ubuntu-latest.
+## Repository and release identity
-The branch-selection/automatic-numbering follow-up copies the same shared control set from Motion commit `b0dd9ddd4af148deda90d42aab0732ba0ab8fe60`. This includes the already integrated #231 shared asset helper and install-guide updates; the candidate gate also runs its native-preparation regression. Empty versions derive from that candidate's frozen Motion source, never from the legacy main package version. Source manifests are not bumped by a build. Both matching PRs must be integrated before accepting feature/motion-produced candidates for publication.
+The repository remains `nexu-io/html-anything`. Repository guards, installation URLs and generated package links retain that address. Repository renaming is a separate administrator action.
-GitHub requires a manual workflow to exist on the default branch before its Run workflow entry is available. All three Motion manual entries now require **Use workflow from: feature/motion**. Selecting `main` fails before checkout or release work instead of silently fetching Motion from another branch. Main still registers the entries for GitHub to display them. The candidate source defaults to the selected dispatch SHA; an explicit reviewed source SHA must be integrated into `feature/motion`. Older valid main-produced candidates remain readable. See [GitHub manual workflows](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow).
+Before the next npm publication, a package maintainer must verify the trusted publisher for `@openmotion/app` in npm:
-## Activation order
+| Setting | Value |
+| --- | --- |
+| Organization | `nexu-io` |
+| Repository | `html-anything` |
+| Workflow | `motion-publish-test.yml` |
+| Environment | Blank |
+| Permissions | npm publish and npm dist-tag |
-1. PR #214 is integrated into `feature/motion`, and #222 registered the original entries on `main`.
-2. Integrate the matching DEV packaging fix into `feature/motion`, then this control-only follow-up into `main`. Recompare the shared control files before using the new route. Neither merge runs a candidate build or publication; normal credential-free CI still runs.
-3. An npm package maintainer separately configures the GitHub trusted publisher for `@openmotion/app`: owner `nexu-io`, repository `html-anything`, workflow filename `motion-publish-test.yml`, Environment blank, and both **npm publish** and **Allow npm dist-tag** permissions. The promotion job requires the separate dist-tag permission; publish permission alone is insufficient. Credentialed jobs pin npm 11.21.2, which supports OIDC dist-tag operations. No stored npm token or independent approval environment is required. See [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/).
-4. Reuse the existing R2 Secrets `CLOUDFLARE_R2_RELEASES_AK` and `CLOUDFLARE_R2_RELEASES_SK`, and Variables `CLOUDFLARE_R2_RELEASES_BUCKET`, `CLOUDFLARE_R2_RELEASES_URL` and `CLOUDFLARE_R2_RELEASES_PUBLIC_ORIGIN`. Do not add secret values to source. Only the final storage step receives R2 credentials.
+The main-branch cutover does not change npm trust, published packages or tags. If the repository is renamed later, update its source URLs, release guards and npm trusted-publisher setting together before the next publication.
-These are separate actions. Preparing or merging the registration does not authorize a package publication, repository rename or product-main cutover.
+Existing R2 secrets and variables stay with the same GitHub repository; never copy their values into source. Only the authorized publication/storage jobs receive publication credentials.
-## Daily operation
+## Manual operations
-1. **Build:** Actions → Motion candidate build → Run workflow → select `feature/motion`. Leave version empty to generate the next Motion source patch plus short `-test.N`, e.g. `0.6.4-test.7` from source `0.6.3`. The candidate workflow run number plus 5 continues after historical `test.6`; run #2 gives `test.7`, run #3 gives `test.8`, and a rerun adds `.2`, `.3`, etc. Failed builds and manual overrides consume numbers, so gaps are normal. Keep the workflow file/counter and offset stable; full run IDs remain in candidate records. An an explicit new test-version override remains available. Output metadata is stamped without changing source manifests. Read the resolved version from the successful summary; normally leave `source_sha` empty to freeze the selected `feature/motion` dispatch commit, including while queued. A supplied full SHA must already be integrated into that branch. The build checks/scans source and archives, and retains the exact candidate for 30 days without npm OIDC or R2 credentials.
-2. **Download and accept:** Download `motion-candidate-<version>` from the successful run, extract it and give its directory to the Agent: “Follow candidate-install.md, verify candidate.json and the local tgz hash, install the exact local package with an isolated host profile, application home, data and Skills directories, complete prepare, and record actual results in a private copy of acceptance.md. Mark unrun checks NOT RUN. Do not publish.” Keep actual host loading, template/edit/export checks, real Agent creation and human playback separate. New public test software defaults to DEV templates; existing prod test versions retain their original defaults. The package exposes DEV routing configuration without private catalog snapshots or credentials. DEV network access/authentication is still required.
-3. **Publish:** Only after acceptance, Actions → Motion test publication → Run workflow → select `feature/motion`. Enter the exact accepted version from the build summary and confirm `accepted`; publication never generates or renames a version. If only a long-numbered candidate exists, build and accept a new short version first; typing a different publication version cannot rename it. This is the publication authorization, with no later independent approval dialog. Candidate provenance/hashes and scans are checked again; only the accepted tgz is published under npm `candidate`, then anonymously checked on Mac/Windows. A separate npm-OIDC-only job verifies both reports, their exact identity and installed DEV defaults, advances `test`, and reads the tag back. Only then does the credential-isolated R2 job archive snapshots and advance the default guide.
+Use the [release workflow manual](release-workflows.md) for candidate building, exact-byte publication, native installation checks and snapshot recovery. Select `feature/motion` in **Run workflow**. Keep candidate validation, target-machine installation, real Agent creation and human audiovisual acceptance separate.
-Before npm publication, use the candidate's **local** `candidate-install.md`, not the sibling registry `install.md`. After publication, the moving test guide is `https://releases.open-design.ai/open-motion/dev/install.md`; the immutable guide is `/open-motion/dev/<version>/install.md`. Stable publication, npm `latest` promotion and Skills platform/marketplace upload are not implemented by these controls. Five Skills are bundled and installed locally; that is not platform publication.
-
-## Risk and recovery boundaries
-
-- Registration is a capability change: users who can dispatch the trusted publication workflow can confirm and start a public release. There is no independent approval gate at this stage. Protect workflow edits and restrict operational access; the operator confirmation records intent, not proof of private testing.
-- Candidate workflows and control changes on `feature/motion` and the registration on `main` require review. The producer branch/SHA is recorded and verified against GitHub run metadata; an arbitrary branch is rejected. Builds do not publish. The publication form defaults acceptance to false and rejects missing, expired, ambiguous or untrusted candidates, changed bytes and unintegrated source. Do not rebuild a published version or guess among duplicate candidate artifacts.
-- npm publication cannot be rolled back atomically with later checks. The exact candidate and `candidate` tag are public before native verification. If either native check fails, `test` and the default guide remain unchanged. R2 failure after successful native/tag checks may leave `test` on the verified new version and the default guide on the prior one; this is not an atomic npm/R2 transaction. Inspect `test-promotion.json` and retained attempt records. Never use npm dist-tag as a dry-run against the real registry. Inspect retained records before using Re-run failed jobs; those retries reuse successful producer artifact IDs and never rebuild the candidate.
-- Motion snapshot recovery also selects `feature/motion` and writes versioned R2 snapshots for an already published identical npm package; it does not build, publish npm, move tags or access the default guide. Channel rollback and client/data recovery require separate decisions.
-- A single publication concurrency group and version/ETag checks protect channel promotion. Operate one release at a time; GitHub does not provide a durable FIFO queue.
-- Disabling/removing these workflow registrations later does not undo a published npm version, restore user projects or revoke npm trust. Those are separate operations.
-
-The current [implementation manual](https://github.com/nexu-io/html-anything/blob/feature/motion/docs/release-workflows.md) is maintained with the Motion source; the original #214 snapshot above records registration provenance. For later control fixes, submit paired Motion/main PRs and compare all shared workflow/helper/template/test bytes before release. The maintainer of the control change owns both updates; a main-only registration fix does not update the executable feature/motion controls. Record both PRs and exact commits in the release review. Keep the full acceptance record internal. Real hosted workflow dispatch, npm OIDC, registry-native acceptance and R2/CDN writes need a separately authorized rehearsal; passing these control tests does not establish that those external integrations are active.
+Main and repository-name changes do not authorize npm publication or storage writes. Historical registration began with [PR #222](https://github.com/nexu-io/html-anything/pull/222); the current integrated source and workflow manual supersede those registration-only instructions.
diff --git a/docs/product/architecture.md b/docs/product/architecture.md
index 4fc3eddc..f2fff394 100644
--- a/docs/product/architecture.md
+++ b/docs/product/architecture.md
@@ -33,7 +33,7 @@ Model Gateway remains a shared media-generation backend for MCP, using local Cod
## 对外主张与 Motion.md 方向
-产品对外名称统一为 **OpenMotion**(O 和 M 大写),README 顶部居中展示 Logo,正文简介前使用纯文本一级标题 OpenMotion,首图和页尾横幅沿用同一标识;现有仓库路径、`motion` 插件标识与环境变量保留兼容。公开介绍以“参考 → 理解与重建 → 品牌改编 → 多模态生成 → 剪辑与渲染”为主线,强调 HTML 视频源码、BYOA / BYOK、真人故事、可编辑作品和 Motion.md 社区。英文、简体中文、日文 README 共用案例、媒体与稳定章节锚点;README 语言与 Studio 界面语言分别维护;Studio 当前支持十一种界面语言。
+The public product name is **OpenMotion**. README pages place the centered logo above the cover and retain a plain-text OpenMotion heading before the introduction. The cover and footer share the same identity. OpenMotion is on `main` in `nexu-io/html-anything`, with daily integration on `feature/motion`; the `motion` plugin identifier and environment variables remain compatible. The public workflow is reference → analysis and reconstruction → brand adaptation → multimodal generation → editing and rendering. It emphasizes editable HTML video, BYOA / BYOK, presenter stories, editable projects and the Motion.md community. English, Simplified Chinese and Japanese READMEs share examples, media and stable section anchors. README localization is maintained independently of the Studio interface, which currently supports eleven languages.
“任何视频”是工作流的创作范围表述,不保证任意输入的获取、解析、还原度或传播结果。参考获取与媒体分析依赖宿主工具和用户材料,生成效果依赖模型配置,成片需按参考、简报与实际视听结果审阅。README 的发布部分明确区分当前 MP4 手动交接与规划中的平台连接、排期和反馈。外部产品来源和比较统一放在 README 最后的 Acknowledgements,技术依赖与具体出处仍保留在专题和源文件中。
@@ -174,7 +174,7 @@ Preview/export preflight and the bundled OpenMotion lint command use the pinned
| Editor interface language | `studio/src/i18n/`、`web/i18n.ts` | Eleven languages, Chinese by default; editor and embedded dialog labels update without remounting. Authored project content and existing instructions retain their source language; newly generated template-copy prompts use the current UI locale, and guide/download URLs come from that locale’s catalog; native-speaker review remains separate. |
| 多 Agent 薄适配器 | `scripts/export-adapters.ts`、`shared/integration.ts` | Codex、Claude、DSH、WorkBuddy Connector 共用外置运行时;本机生成,WorkBuddy 桌面待验收,详见 [适配器](../agent-adapters.md) |
| MCP 接入与指引 | `mcp.ts`、`mcp-tools.ts`、`shared/integration.ts`、`web/connect.*` | 本机 stdio;macOS 业务由共享后台执行,ChatGPT 云端远程 MCP 尚未提供 |
-| Codex 安装 | `install.sh`、`scripts/install-motion.command` | 远端源码下载、依赖安装与编辑器构建、本地插件注册和 MCP 握手;需预装 Git、Node/npm 与支持插件的 Codex CLI,保留安装目录,遇到已有目录停止;远端一行入口待发布到 main |
+| Codex 安装 | `install.sh`、`scripts/install-motion.command` | 远端源码下载、依赖安装与编辑器构建、本地插件注册和 MCP 握手;需预装 Git、Node/npm 与支持插件的 Codex CLI,保留安装目录,遇到已有目录停止;the source installation entry is available on main |
| 模板发现与复刻入口 | `prism-templates.ts`、`shared/catalog.ts`、`web/template-gallery.*` | Prism 本地缓存同时供界面查询和 Agent JSONL 索引使用,精确 ID 保留 |
| 空白工程与模板副本 | `workspace.ts`、`template-library.ts`、`template-library/` | 新建空白原生工程或创建模板独立副本,保留之前工程 |
| 封面、来源与热度 | `web/catalog/`、`scripts/*template*.ts` | 本地资源/快照;热度不代表实时查询 |
diff --git a/docs/readme/brand-hero.ja.jpg b/docs/readme/brand-hero.ja.jpg
index 93697d54..03c61244 100644
Binary files a/docs/readme/brand-hero.ja.jpg and b/docs/readme/brand-hero.ja.jpg differ
diff --git a/docs/readme/brand-hero.jpg b/docs/readme/brand-hero.jpg
index b11adc02..20be126d 100644
Binary files a/docs/readme/brand-hero.jpg and b/docs/readme/brand-hero.jpg differ
diff --git a/docs/readme/brand-hero.mobile.ja.jpg b/docs/readme/brand-hero.mobile.ja.jpg
index eb43f8e4..03c61244 100644
Binary files a/docs/readme/brand-hero.mobile.ja.jpg and b/docs/readme/brand-hero.mobile.ja.jpg differ
diff --git a/docs/readme/brand-hero.mobile.jpg b/docs/readme/brand-hero.mobile.jpg
index 28fcb4a3..20be126d 100644
Binary files a/docs/readme/brand-hero.mobile.jpg and b/docs/readme/brand-hero.mobile.jpg differ
diff --git a/docs/readme/brand-hero.mobile.zh-CN.jpg b/docs/readme/brand-hero.mobile.zh-CN.jpg
index ce89d3af..b6506b00 100644
Binary files a/docs/readme/brand-hero.mobile.zh-CN.jpg and b/docs/readme/brand-hero.mobile.zh-CN.jpg differ
diff --git a/docs/readme/brand-hero.zh-CN.jpg b/docs/readme/brand-hero.zh-CN.jpg
index a556e445..b6506b00 100644
Binary files a/docs/readme/brand-hero.zh-CN.jpg and b/docs/readme/brand-hero.zh-CN.jpg differ
diff --git a/docs/readme/reverse-engineering-cover.md b/docs/readme/reverse-engineering-cover.md
index 654974bb..77ec1368 100644
--- a/docs/readme/reverse-engineering-cover.md
+++ b/docs/readme/reverse-engineering-cover.md
@@ -4,6 +4,12 @@ The [English](brand-hero.jpg), [Chinese](brand-hero.zh-CN.jpg) and [Japanese](br
The left panel uses 0.83–3.23 seconds from [Dan Martell’s original video](https://www.youtube.com/shorts/mk1zJd9Rm4c). The right panel uses the first 2.4 seconds of [@careerwithriya’s career-skills video](https://www.instagram.com/reel/Ddd57MBszhc/). OpenMotion rebuilt the three caption layers for Riya’s footage. The comparison plays Riya’s original audio. Both creators retain the rights to their footage.
+## Current integration cover
+
+The current cover uses the approved talking-head comparison composition with a continuous paper-and-turquoise background. It displays compact agent and media-model rows, including Antigravity and Kimi Code. The English, Simplified Chinese and Japanese covers keep the same layout and the approved English tagline; supporting labels are localized. Mobile image entries carry the same complete cover.
+
+Method: built-in ImageGen editing of the approved cover, followed by JPEG encoding. This is promotional artwork based on the reference/remake and editor imagery, not a newly recorded product session or additional compatibility-test evidence. The linked comparison video remains the actual recreation evidence.
+
## Earlier cover artwork
| Field | Value |
diff --git a/docs/release-workflows.md b/docs/release-workflows.md
index b7f665f3..57163b7c 100644
--- a/docs/release-workflows.md
+++ b/docs/release-workflows.md
@@ -1,6 +1,6 @@
# Motion releases: build, test, publish
-Use two manual Actions entries: **Motion candidate build**, then **Motion npm publication**. The daily flow is **build → optional local testing → manual publish**. Neither entry runs on pushes, PR merges, tags or a schedule. The entries are registered on `main`; Motion application development stays on `feature/motion`. Merging a workflow change does not publish a package, configure npm permissions or switch the product main branch.
+Use two manual Actions entries: **Motion candidate build**, then **Motion npm publication**. The daily flow is **build → optional local testing → manual publish**. Neither entry runs on pushes, PR merges, tags or a schedule. The entries are registered on `main`; Motion application development stays on `feature/motion`. Merging a workflow change does not publish a package or configure npm permissions.
| Operator step | Automated work |
| --- | --- |
@@ -14,9 +14,9 @@ New public test packages use **DEV templates**; stable packages use prod. The `d
## First-time administrator setup
-The default `main` currently contains the legacy project. GitHub requires a `workflow_dispatch` workflow to exist on the **default branch** before its manual entry is available; it can otherwise run from another ref. For candidate build, npm publication and snapshot recovery, select **Use workflow from: feature/motion**. Selecting `main`, `legacy`, a tag or another feature/fix branch fails explicitly before checkout or release work. Older valid candidates built from `main` remain readable; new operations execute the reviewed controls on `feature/motion`. Application source always comes from a commit integrated into `feature/motion`. Register the reviewed control files through a separately authorized small PR. This does not copy the Motion application onto `main` or rewrite its history. See [GitHub's manual workflow requirements](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow).
+The default `main` contains OpenMotion; the former HTML Anything application remains on `legacy`. GitHub requires a `workflow_dispatch` workflow to exist on the **default branch** before its manual entry is available; it can otherwise run from another ref. For candidate build, npm publication and snapshot recovery, select **Use workflow from: feature/motion**. Selecting `main`, `legacy`, a tag or another feature/fix branch fails explicitly before checkout or release work. Older valid candidates built from `main` remain readable; new operations execute the reviewed controls on `feature/motion`. Application source always comes from a commit integrated into `feature/motion`. Keep the reviewed control files aligned between `main` and `feature/motion`. See [GitHub's manual workflow requirements](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow).
-Register these files together:
+Keep these control files together:
- `.github/workflows/motion-candidate.yml`, `motion-publish-test.yml`, `motion-publication-recovery.yml` and `motion-install-check.yml` (read-only manual rechecks).
- `.github/scripts/motion-release.mjs`, `motion-scan.mjs`, `motion-registry.mjs`, `motion-registry-smoke.mjs`, `publish-install-guide.mjs` and `.github/gitleaks.toml`.
@@ -37,7 +37,7 @@ Reuse the existing R2 settings. Only the final snapshot step receives the storag
## 1. Build
-Open **Actions → Motion candidate build → Run workflow**, select **`feature/motion`** and a **channel**. For `test`, normally leave **version** empty. For `stable`, enter an explicit new version such as `0.6.4` (no suffix); empty or mismatched versions fail before building. Use this same branch for publication and recovery; `main` only registers the manual Actions entries.
+Open **Actions → Motion candidate build → Run workflow**, select **`feature/motion`** and a **channel**. For `test`, normally leave **version** empty. For `stable`, enter an explicit new version such as `0.6.4` (no suffix); empty or mismatched versions fail before building. Use this same branch for publication and recovery; `main` registers the manual Actions entries; release operations still execute from `feature/motion`.
An empty version uses the frozen Motion source's `package.json`, increments its patch and appends a short `-test.N`. `N` is the candidate workflow's `GITHUB_RUN_NUMBER` plus **5**: candidate run #1 used the retired long format, and run #2 continues after historical `test.6` as **`0.6.4-test.7`**, then run #3 produces **`0.6.4-test.8`**. Failed builds and explicit overrides still consume run numbers, so gaps are expected. A rerun adds its attempt only after the first attempt, for example `0.6.4-test.7.2`; start a new build if an older rerun is rejected by the no-regression check. Do not reset or move the workflow file without reviewing this numbering offset. Full run ID, attempt and source SHA remain in candidate.json and acceptance.md. See [GitHub run variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables).
diff --git a/docs/repository-migration.md b/docs/repository-migration.md
index acafc170..638521f8 100644
--- a/docs/repository-migration.md
+++ b/docs/repository-migration.md
@@ -1,8 +1,8 @@
# OpenMotion standalone repository
-The `feature/motion` branch replaces the former HTML Anything application with OpenMotion at the repository root. Existing repository commits remain in Git history; this is a normal branch change, not a history rewrite or a merge into main. The repository name is unchanged.
+OpenMotion replaces the former HTML Anything application at the repository root on `main`. The repository name remains `nexu-io/html-anything`; existing commits, issues and pull requests remain in the same repository. The cutover preserves Git history.
-Daily Motion changes branch from the latest `feature/motion` and open PRs with that base. The previous application is preserved at [`legacy`](https://github.com/nexu-io/html-anything/tree/legacy). Switching `main`, renaming the repository and publishing remain separate decisions.
+Daily Motion changes branch from the latest `feature/motion` and open PRs with that base. The previous application is preserved at [`legacy`](https://github.com/nexu-io/html-anything/tree/legacy). The default branch remains `main`. Package publication remains a separate, explicitly authorized operation.
## Upstream synchronization checkpoint