# Install OpenMotion 0.1.0

This guide pins the complete npm application `@openmotion/app@0.1.0` on the **stable** software channel. It includes MCP, the built Studio and production Skills. The default template environment is **prod**: new test versions embed DEV defaults, stable versions embed prod, and previously published versions keep their original environment.

## Instructions for the Agent

1. Collect OS/CPU, Node.js/npm versions and the current Agent identity together, using the host's supplied context where available. Node.js 22.18+ with npm and the Agent must already be installed. Supported native targets: darwin/arm64, win32/x64 (Windows 11+). If a macOS target has no declared minimum version, proceed with setup and native executable checks; do not infer a minimum from the build/test machine's OS version. Do not claim support for another target from package-download success.
2. Select the current host explicitly: `codex` (Codex), `claude` (Claude Code), `deepseek` (DeepSeek Harness) or `workbuddy` (WorkBuddy) have registration adapters. Any other local Agent, such as OpenCode, Cursor Agent or Gemini CLI, passes its own lowercase name (for example `opencode`); setup installs the same application and Skills, leaves that host's configuration unchanged and returns `agentRegistration` for the Agent to add to its own MCP configuration. Never borrow another host's adapter. An explicit user selection takes precedence. Do not infer the current host from which CLIs happen to be installed. Ask only when the current host or required profile cannot be established. Configure only that host; preserve projects, credentials and unrelated MCP/Skills settings.
3. For a test candidate, use a separate host profile, application home, project data and Skills directory. Keep those paths and reuse them for prepare and future reconnects. The [platform installation recipes](https://github.com/nexu-io/openmotion/blob/19f7424e0cf45606c463216f41c6f8a9db393bfe/docs/npm-installation.md) describe the actual supported options. Do not run a test candidate into the user's daily profile by default.
4. Choose exactly one setup command below, applying the test isolation paths first when required. Setup starts checked video-component downloads in the background. Do not wait for prepare to connect MCP, create/edit projects or open ordinary preview. Studio shows preparation status and retry; media import, automated capture and export require their respective components. Compatible phase-one updates can keep existing connections; reconnect closed or incompatible transports. When the current host can discover the public Tools and production Skills, verify the version/environment and the Tool/Skill names declared by this exact package's embedded `payload/release-npm.json` (`mcp.tools` and `skills`); negotiated presentation Tools may also appear. Make an actual `openmotion_get_project` call. If this chat has not loaded them or still points at another installation, use `onboarding.directAccess` below; registration alone does not prove native loading. Do not postpone the installation reply or template library opening until a new chat or the first MCP call.
5. On successful setup, follow the installation-success reply below in this same conversation. Open the template library without creating a project. Installation does not authorize downloading template project source, rendering or calling a paid model. Report a failed installation honestly; do not claim success until it is fixed.

For npm network failures, automatically try `https://registry.npmjs.org` then `https://registry.npmmirror.com`, at most once per registry, counting the initial failed attempt. Respect an explicitly selected registry and host policy. Set `npm_config_registry` and `npm_config_fetch_retries=0` only for that attempt, including setup's npm child process. Keep the exact version; verify any mirrored tgz against the matching immutable guide's SHA256 before executing it. If both fail, follow [npm download recovery](https://github.com/nexu-io/openmotion/blob/19f7424e0cf45606c463216f41c6f8a9db393bfe/docs/npm-installation.md#npm-download-failures) for network checks and a terminal handoff. Permission or checksum failures stop immediately. A local tgz still needs npm access for setup's production dependencies.

## Installation-success reply

Accept presentation and automatic MCP activation independently.

### Presentation acceptance

1. Open the actual local template library once, without creating a project. Detailed library inspection is unnecessary.
2. Deliver the maintained welcome and exactly three full-duration project-preview cards. On Codex, publish the self-contained HTML fragment and place its returned content reference directly after the welcome in the final reply. Native MCP Apps remain an alternative for original reference films when native tools are available.
3. Preserve the three IDs/order sampled without replacement from the five-entry pool in `shared/onboarding-templates.ts` (the catalog IDs referenced by PR #472). Confirm that the welcome and all three cards are visible; full audiovisual review remains a separate user check.

`onboardingStatus` and `onboardingComplete` describe presentation only. Setup and connection recovery leave it `awaiting_host_delivery` and incomplete until visible delivery is confirmed; library preparation failure remains `preview_unavailable`. `hostHandoff.automaticActivation`, its reason and `hostSessionVerified` report the independent connection check. A working native connection can present the component even when the installer's control socket is unavailable. Visible cards do not prove that installation loaded MCP automatically, and activation failure does not invalidate an otherwise verified presentation.

### Self-contained project previews (default)

Default preparation freezes three IDs/order once across `catalog`, `inlinePresentation`, `hostHandoff` and recovery. It returns `prepared` with an integrity-locked HTML path, SHA256 and the selected IDs. The fragment embeds only those three projects' prebuilt WebM (VP9)/JPEG bytes. Complete silent videos retain 12 fps, with widths up to 512 px and two-pass 20 kbit/s encoding. The builder checks the largest three-media combination, and the renderer enforces the complete document's 1,000,000-byte limit; changing codecs does not guarantee fine-text or full-screen fidelity. Explicit builtin examples retain their existing MP4 previews. It needs neither external media origins nor current-chat MCP activation. Publish it with `scripts/inline-onboarding.mjs --publish-from PATH --sha256 SHA256 --host-directory DIRECTORY` using the current chat's explicitly permitted visualization directory. Publication reads the frozen language from the hash-verified document and returns `finalReplyMarkdown`, containing the complete maintained welcome followed by `contentReference`. After opening the library, emit that complete field verbatim as normal final reply text; do not summarize it or replace the introduction with an installation-status report. Report connection diagnostics separately in progress updates. If the welcome was actually delivered earlier, publish with `--welcome-delivered` to return only the card reference. The document itself contains cards only. A prepared/published file does not establish visible delivery.

These are **silent renders of the repository's editable projects**, not original reference films or a claim of verified recreation fidelity. All five previews are prebuilt by maintainers with `node scripts/build-onboarding-previews.mjs`; installation does no rendering or media download. The builder uses pinned Hyperframes, Chrome and FFmpeg, strips audio only in scratch copies, preserves complete project duration, and records source/media hashes. `--hydrate-fonts` may retrieve hash-verified project fonts missing from a source checkout. Original reference videos are never downloaded for embedding. No source project is changed by the build. Chinese card descriptions use `简介：` followed by the localized summary; the media provenance is documented here rather than repeated in that description.

### Native original reference cards (alternative)

Native MCP Apps retain the original reference films and their declared media origin. For a working native connection, call `openmotion_show_template_recommendations` with the exact prepared IDs/order, request language and `onboarding:true`. This displays the maintained welcome above the three cards; do not duplicate it in the final reply. Use `onboarding:false` after a welcome already delivered. Explicit `renderInlineOnboarding({previewSource:'reference', ...})` returns `native_required`, since the document renderer cannot inherit native App media policy. Preserve the selection; do not substitute builtins or alter host security. A shell presentation call does not mount a native component. Original reference playback requires network access.

### Automatic current-chat activation

This is a separate acceptance track: installation must automatically load the native tools and verify the installed workspace in the installing chat. Registration, an independent handshake, a queued refresh or a later connected chat does not establish that result. Record the installation/chat identities and actual host recovery path; do not infer automatic activation from presentation acceptance.

Source and npm setup use `prepareInstallationFlow`. After registration, an existing supported Codex control connection checks `thread/loaded/list` for the calling `CODEX_THREAD_ID`. A healthy native connection is reused. Missing/stale tool discovery, an outdated application version or a mismatching immutable card resource requests one `config/mcpServer/reload`. The refresh is queued for a host tool boundary; an immediate status read is not its completion.

After that tool step finishes, execute the returned `recovery.command`/`recovery.args` in this same turn. The private immutable receipt preserves the chat, application, workspace, language, three IDs/order and library URL. Recovery performs verification only: no reinstall, library startup, resampling or additional reload. Native discovery and `openmotion_get_project` must verify the expected workspace through the calling thread before `hostSessionVerified` is true. They do not prove visible welcome/cards.

Use `OPENMOTION_CODEX_SOCKET` for an explicitly known existing control entry, otherwise use the current profile's default entry. Resolve that entry with `realpath`; current-user-owned symlinks are supported when the resolved target is a current-user-owned socket in a current-user-owned directory that is not group- or world-writable. Pass the verified canonical path to the CLI proxy, then verify that the existing host has this chat loaded before any reload. Resolving this known entry is supported discovery, not endpoint guessing. Missing, dangling, cyclic, foreign-owned and unsafe targets remain blocked.

Do not scan unrelated paths for endpoints, start another app-server to simulate this chat, alter host listeners/security, inject instructions through `codex queue` or automatically restart Codex. If the user explicitly chooses to reconnect, record it as manual recovery; it does not establish automatic activation in the original installing chat. A private-stdio host with no supported reload capability blocks automatic-activation acceptance. Retain that reason independently in diagnostics and the receipt. Use already working native tools directly to deliver the welcome/cards; do not withhold presentation because the script control socket is missing.

Codex plugin setup reaches this contract through `extensions.com.openai.onboardingSkill`. Its directory must also be in the plugin's `skills` roots. CLI registration alone does not invoke the desktop install callback or create a current-chat refresh capability. Installed files, current-chat connection and visible native delivery are separate outcomes.

### Open the library

Use `openmotion_open_preview({target:"templates"})` when loaded, otherwise setup's exact `preview.previewUrl`. Open it in this chat's right-hand browser, preserving embedding parameters and reusing its tab. With CUA, create it using `cua.createBrowserTab('iab', previewUrl, {visible:true})`, mark it as a deliverable and complete mandatory browser bookkeeping. Otherwise use the supported `open_in_codex` browser target with `placement:"right"` and no other thread ID. Opening is sufficient; do not inspect the complete inventory or audit playback. Report queued/unavailable presentation accurately. Never create a placeholder project or submit project display receipts for the library.

### Welcome copy and blocked delivery

The native component uses the shared localized welcome dictionary. The Chinese welcome begins:

```text
🎉 OpenMotion 安装好啦，右侧就是模板库！

我是你的开源视频创作搭档，我有丰富的高水准视频模板，也支持从参考视频或一个灵感出发，和你一起创作精彩的视频。

模板库支持搜索，也可以随意浏览，找到喜欢的点击「复刻模板」就能开始你的创作！

不想自己找？先看看我挑的这 3 个 👇
```

If neither the prepared inline document nor native recommendation cards can be displayed, open the library and make the entire final reply exactly these three paragraphs for Chinese requests:

```text
🎉 OpenMotion 安装好啦，右侧就是模板库！

我是你的开源视频创作搭档，我有丰富的高水准视频模板，也支持从参考视频或一个灵感出发，和你一起创作精彩的视频。

模板库支持搜索，也可以随意浏览，找到喜欢的点击「复刻模板」就能开始你的创作！
```

The top-level `welcomeMarkdown` supplies these paragraphs from the maintained localized welcome dictionary; other supported languages use the same heading/introduction/discovery fields. Output it verbatim once, with its paragraph breaks. Keep status, source revisions, verification results, blockers, library links, recovery details and card invitations outside this reply. Diagnostics and the immutable receipt retain the real incomplete onboarding state and blocker; the concise welcome does not mark native delivery or activation complete. Only use the right-hand-library heading after the library visibly opens; a library-opening failure remains a separate installation failure. For later recovery after the welcome, append `--welcome-delivered` to the saved recovery command so it returns cards-only arguments.

### Explicit builtin compatibility

Explicit builtin examples can still use the same prepared document route. They never replace the five-entry pool's selected projects. Automatic MCP activation is assessed separately for either route.

### Accepted template selection

For creation, directly editable sources use openmotion-template-to-video; curated references use openmotion-recreate. A project-rendered preview does not change that routing or authorize creation.

Use the exact accepted ID and scope through [accepted template selection](../skills/openmotion-production/references/templates.md#accepted-template-selection). A named choice retains that recommendation; a generic agreement to several equal choices still needs a selection. Recreate only fills an unsent editable brief through a negotiated composer bridge, or copies it to the clipboard with a floating Toast. Browsing, playback and copying do not authorize creation/export; the user-sent brief does. Preserve customized requirements and any existing GUI-created project, and never create a duplicate during recovery.

## Choose the selected host's setup command

The commands below show normal installations. For test candidates, apply the separate configuration/profile, home, data and Skills paths from the [platform recipes](https://github.com/nexu-io/openmotion/blob/19f7424e0cf45606c463216f41c6f8a9db393bfe/docs/npm-installation.md) first. Run only the selected row.

| Current Agent | Setup command | Host-specific selection |
| --- | --- | --- |
| Codex | `npx --yes --package "@openmotion/app@0.1.0" openmotion setup --host codex` | Preserve the selected `CODEX_HOME` and Skills root. |
| Claude Code | `npx --yes --package "@openmotion/app@0.1.0" openmotion setup --host claude` | Preserve the selected `CLAUDE_CONFIG_DIR` and Skills root. |
| DeepSeek Harness | `npx --yes --package "@openmotion/app@0.1.0" openmotion setup --host deepseek --profile PROFILE` | Replace `PROFILE` with the actual selected profile from the host context; do not guess `web` or `desktop`. The standard macOS Desktop CLI is detected even when `dsh` is absent from PATH; use `--dsh` for another executable location. |
| WorkBuddy | `npx --yes --package "@openmotion/app@0.1.0" openmotion setup --host workbuddy` | Preserve the selected `WORKBUDDY_CONFIG_DIR` and Skills root. |
| Any other local Agent | `npx --yes --package "@openmotion/app@0.1.0" openmotion setup --host AGENT` | Replace `AGENT` with the current Agent's lowercase name, such as `opencode`. Skills default to `~/.agents/skills`; use `--skills-dir` if this Agent reads another root. Add `agentRegistration.transport.command` and `args` exactly as returned to this Agent's documented local stdio MCP configuration, refresh MCP, then call `openmotion_get_project`. Until the native tools load, use `onboarding.directAccess`. [Other local Agents](https://github.com/nexu-io/openmotion/blob/19f7424e0cf45606c463216f41c6f8a9db393bfe/docs/npm-installation.md#other-local-agents) |

Optional: explicitly wait for all video components or retry preparation for the same installation:

```sh
npx --yes --package "@openmotion/app@0.1.0" openmotion prepare
```

Repeat an explicit `--home` from setup on prepare. Setup installs the selected host's MCP and Skills; a second installer or application/manifest download is unnecessary. Use `openmotion --help`, `setup --help` or `prepare --help` from this exact package for supported options. Inspect installer source or host internals only to investigate a concrete failure; a missing CLI on PATH alone is not a reason to create a wrapper.

## Runtime and environment

Setup copies the checked application into a managed writable directory and installs its locked production npm dependencies. The application and user projects do not run from the temporary npx cache. Setup starts a detached preparation worker for the platform's independent native archives concurrently: browser/FFmpeg/ffprobe separately on macOS, browser/combined media on Windows. The local backend and Studio start without waiting. Studio displays per-component download/verification/extraction/checking status and retries failed components. Installers, MCP and Studio join shared cache locks rather than downloading again. An explicit prepare waits for all components and reports failure; successful checked components remain reusable. No export starts automatically after preparation. This is not an offline package.

There is no persisted switch-environment command in this version. Test versions embed DEV defaults and use an environment-specific installation; stable versions embed prod. DEV access still requires the service network/authentication. A public npm package does not grant access or bundle private catalog contents. When changing environment, use a separate home/data/profile; merely setting an environment variable while running setup does not configure a later desktop Agent. Do not silently fall back from one environment to another.

## Upgrade, recovery and feedback

Pin this exact version when reproducing an issue. Before an upgrade, back up project data and preserve the same installation/data paths. Compatible phase-one updates retain existing connections and active exports. For an incompatible protocol, finish active exports before updating only this installation's connection and idle backend together; reconnect after setup/prepare. Refresh host discovery for new Tools or Skills, and preserve unrelated settings. Older applications may not read newer data formats: compatible reinstall or backup restoration requires separate verification. Moving a server-side default does not downgrade installed clients.

Include the exact version, OS/CPU, Node/Agent versions, template environment, project/revision, reproduction and redacted logs in a report. Installation, real Agent creation, technical MP4 export and human audiovisual acceptance are separate results.

Release identity: source `19f7424e0cf45606c463216f41c6f8a9db393bfe`; npm tgz SHA256 `dc56ca5e0f0b618544930e059e9dfcbb31fac72d60052b72ff8c5a7ea3efd5b6`. [Source and installation details](https://github.com/nexu-io/openmotion/blob/19f7424e0cf45606c463216f41c6f8a9db393bfe/docs/npm-installation.md).
