# Motion application npm package > Repository installation defaults to the [source guide](../install.md). Published npm installation is an explicit alternative through the [application guide](install.md). Candidate builds, publication and snapshot recovery use the manual [release workflow](release-workflows.md); merging changes does not publish a package or update hosted guides. For a download-once cold installation, build on the target machine with `node --experimental-strip-types scripts/package-npm.mjs OUTPUT_DIR --bundle-runtime`. This option installs locked production npm dependencies at build time and embeds them in an XZ application archive, omitting `.map` debug sidecars while retaining application sources, executable modules, declarations and licenses. The manifest pins OS/CPU and dependency lock SHA256. Setup rejects another target before changing installation state, verifies the embedded marker, lock and direct package versions, then skips dependency downloads. Select the exact reviewed artifact for the machine; this is not a universal package. Lightweight builds retain target-machine npm installation. Frontend libraries compiled into Studio are development dependencies; editing/export dependencies remain production dependencies. No browser/media binaries are added, and packaging does not publish anything. The npm tgz contains the installer, a prebuilt Motion application archive and its pinned release manifest. One `setup` installs the application and its bundled public MCP Tools and Skills for the selected host. The exact package's embedded `payload/release-npm.json` declares the expected names in `mcp.tools` and `skills`; require every listed name in host discovery, allowing additional negotiated presentation Tools. No adjacent application archive or `--manifest` is needed. The application runs from a managed, writable directory, never from the npx cache; projects remain outside application/cache directories. After successful host registration, setup starts/reuses the headless local service and returns `onboarding.preview` with a project-free template-library URL and host presentation handoff. The Agent opens that page immediately, using `openmotion_open_preview({target:"templates"})` when loaded or the returned URL before current-chat MCP discovery. Setup itself does not launch an OS browser. Preparing or browsing the library never initializes/selects a native project; Open and edit creates a copy only after user selection. A page-start failure is reported as `onboarding.preview.status=unavailable` without rolling back a successful installation or creating a fallback project. Browser-less hosts receive the actual link. Published packages keep the behavior embedded in their own source version. Codex setup shares the source/plugin preparation flow and needs no presentation flag. Default onboarding samples three distinct entries once from the four-entry pool and returns a `prepared` self-contained HTML document. It embeds only the chosen projects' complete silent previews and posters; installation does no rendering or preview download. Open the local library once, publish the verified fragment into the current chat's permitted visualization directory, then stream the welcome followed by its returned content reference. This display does not depend on native MCP reload. Native original-reference playback remains an alternative requiring internet access. An immutable private receipt preserves the selection, language, workspace and preview across supported host refresh recovery. Presentation and automatic MCP activation are independent: visible cards do not establish automatic activation. Preparation does not prove connection or visible delivery. See the [shared presentation contract](install-onboarding.md#installation-success-reply). Historical example: `@openmotion/app@0.6.4-test.6` was published to npm as a test version after separate authorization; ordinary CI still does not publish packages. Its anonymous registry download, isolated macOS Codex setup, repeat setup, eleven MCP Tools and five Skills have been verified. Use the exact version for reproduction. See the [delivery record and known limitations](release-guide.md#published-test-candidate-064-test6), including the production template catalog and the registry's unexpected `latest` tag. Source `package.json` is the development baseline; the published artifact can have a different version. For example, source `0.6.3` can produce `0.6.4-test.6` without a stable `0.6.4` release. Packaging changes output identities only. Manual [candidate builds](release-workflows.md#1-build) accept an empty version and automatically generate the next patch plus a short `test.N` workflow counter (with an attempt suffix on reruns); publication keeps the exact accepted version. All application environments and versions, including test/prerelease/local packages, collect usage data by default and support persistent opt-out and re-enable in Studio Privacy settings. Environment force-off and Do Not Track controls still apply. See [tracking controls](../tracking/README.md#reporting-and-user-control). ## Public names and compatibility Source builds after the OpenMotion naming change register the plugin/MCP server as `openmotion` and advertise the release's `openmotion_*` Tools, canonical `openmotion-*` production Skills, and `openmotion://` resources. The optional Library Skills are also prefixed with `openmotion-`. Previously published packages keep their original names until separately updated; a source change is not a release. - Old `motion_*` Tools, legacy session Tool names and `motion://` resources call the same handlers. Aliases are accepted but omitted from MCP discovery. API protocol 1 remains compatible with old and new backend Tool lists. - Retired Skill names (`motion-director`, `motion-production`, `motion-recreate`, `motion-template-to-video`, `motion-video-to-template`, `reference-video` and the unprefixed Library names) are removed. Update saved invocations and paths to `openmotion-*`; old explicit invocations no longer work. Re-run setup with the same host, home and Skills directory: bundled hosts replace the owned bundle, and flat hosts remove obsolete entries owned by this host/home. Foreign/unowned folders and other installations are preserved. Registration failure restores previous Skills and install state. Separately installed Library entries use the canonical helper described in [Skill migration](skills.md); customized or unowned legacy entries need manual review, not automatic deletion. Refresh host Skill discovery after upgrading. - New adapter/plugin packages and generated connection commands use `openmotion`. Existing `motion` MCP entries can still launch the runtime and use aliases; refresh/reconnect to load the canonical discovery list, or install the new `openmotion` plugin through the host. Do not overwrite an unrelated registration or create a second workspace to rename a connection. - Project/session IDs, content revisions, request-ID deduplication, history, active exports, media/native caches, environment variable names and engine versions keep their existing contracts. New and old names use the same request identity, avoiding duplicate edits/renders during retry. ## Requirements and package contents Users provide Node.js 22.18+ with npm and their Agent host. Builds use the Node version pinned in CI. npm installs locked production dependencies with `npm ci --omit=dev --ignore-scripts`. Setup starts FFmpeg, ffprobe and browser preparation in a detached background worker. MCP connection, source editing and ordinary preview do not wait; Studio displays readiness and retry. `prepare` remains an explicit wait/retry command. Node, native binaries, node_modules, user projects and credentials are not bundled in this npm format. It is not an offline package. Complete platform ZIPs remain a backup. The embedded application uses `scripts/distribution.ts`'s positive file list: MCP/backend, prebuilt Studio, bundled Skills and references, bundled examples, npm/native locks, licenses and approved documentation. The installed application fetches the latest OpenMotion template catalog from the OpenMotion hosted CDN `main` pointer; the website continues to use its CMS publication. The embedded manifest omits the containing tgz's hash; the external delivery manifest records that hash without a circular self-reference. The npm page uses the repository's product `README.md`. Packaging resolves its relative documentation and image links against the exact source commit, while the embedded application keeps the original local links. The installation manual remains in the application docs; it is not the npm landing page. Published test.6 contains the earlier installation-manual README; the correction takes effect with the next separately authorized npm version, not by editing GitHub alone. ## Build and install a local test From a clean checkout based on `main`: ```sh npm ci --no-audit --no-fund npm run package:npm -- dist/npm-test 0.6.4-test.1 ``` The version is an example. Use a new empty output directory for every candidate. Files include `openmotion-app-.tgz`, the application archive, `release-npm.json` and SHA256 sidecars. Only the tgz is required by a consumer; the remaining files are delivery evidence and the explicit-manifest fallback. Copy the tgz alone to another directory to verify this property. An isolated macOS Codex installation: ```sh openmotion_tgz="/absolute/path/openmotion-app-0.6.4-test.1.tgz" openmotion_test="$HOME/Library/Application Support/OpenMotion-test/0.6.4-test.1" mkdir -p "$openmotion_test/profile" "$openmotion_test/workspace" export CODEX_HOME="$openmotion_test/profile" npx --yes --package "$openmotion_tgz" -- openmotion setup --host codex \ --home "$openmotion_test/app" --data-dir "$openmotion_test/data" \ --skills-dir "$openmotion_test/workspace/.agents/skills" && npx --yes --package "$openmotion_tgz" -- openmotion prepare --home "$openmotion_test/app" && cd "$openmotion_test/workspace" && codex ``` The acceptance recipe explicitly waits with `prepare` after setup. Ordinary installation can continue immediately: the backend starts without native-download waits, and Studio reports preparation. Media import, automated screenshots and export check the required components before starting. The isolated Codex profile may require its own login; do not copy credentials into the package. Equivalent Windows PowerShell commands: ```powershell $motionTgz = 'C:\path\openmotion-app-0.6.4-test.1.tgz' $motionTest = Join-Path $env:LOCALAPPDATA 'OpenMotion-test\0.6.4-test.1' New-Item -ItemType Directory -Force "$motionTest\profile", "$motionTest\workspace" | Out-Null $env:CODEX_HOME = "$motionTest\profile" npx --yes --package "$motionTgz" -- openmotion setup --host codex --home "$motionTest\app" --data-dir "$motionTest\data" --skills-dir "$motionTest\workspace\.agents\skills" if ($LASTEXITCODE -ne 0) { throw 'Motion setup failed' } npx --yes --package "$motionTgz" -- openmotion prepare --home "$motionTest\app" if ($LASTEXITCODE -ne 0) { throw 'Native preparation failed' } Set-Location "$motionTest\workspace" codex ``` These are documented commands, not proof of Windows acceptance. Use a directly executable host or pass its JavaScript CLI through `--codex`. The native lock declares Mac arm64 and Windows x64/Windows 11. OpenMotion adds no macOS version gate: proceed with installation and the native executable checks, rather than treating the build/test machine's OS version as a minimum. Node.js and the pinned browser/media binaries must still run on the target machine; this is not acceptance of every macOS version. Other platforms are not implied supported by npm installation. ## Test template data (DEV) New explicitly versioned test npm packages default to **DEV**; stable packages default to **prod**. Existing published versions retain their original environment (test.6 used prod). New NPM packages read the same hosted main template catalog in both environments. DEV/prod controls workspace defaults and explicit CMS routing. To test a DEV application, download an accepted candidate or build one locally: ```sh npm run package:npm -- dist/npm-dev 0.6.4-test.1 --template-env=dev ``` Use that tgz in the installation commands above, with an **independent Codex profile, home, data and Skills directory**. Explicit test/DEV builds are publishable under the candidate channel. Unversioned builds and channel/environment mismatches remain `private:true`. Public packaging exposes DEV routing configuration, not credentials or cached catalog contents; network access/authentication remains a service prerequisite. DEV setup defaults to `openmotion-dev` instead of `openmotion`; `prepare` uses the same environment-specific default. Explicit `--home` must be identical for setup and prepare. An existing installation refuses an implicit data-directory change or a dev/prod switch: use a different home rather than altering the old projects. The environment is embedded in `shared/template-config.json`; the resulting `install.json.templateEnvironment` identifies the installation. Studio and MCP read the same source. [Template configuration](template-catalog.md#environment-and-build) explains the current Resource and catalog behavior. Saving a CMS draft does not publish it. Refresh the catalog, find the template ID and record its catalog/publication version; existing projects are independent copies and do not change when a template is republished. For **source development**, Studio and MCP now default to repository templates when `library/templates/catalog/` exists. Use `MOTION_TEMPLATE_SOURCE=cms MOTION_TEMPLATE_ENV=dev MOTION_DATA_DIR=/absolute/isolated-dev-data npm run mcp` only when testing the DEV CMS publication. The local template startup and plugin paths are documented in [the repository workflow](template-repository.md#run-from-a-local-clone). For an installed package, advanced overrides must be supplied to the actual MCP/Agent process and inherited by the backend. Setting a shell variable only while running setup does not persist it into a later GUI host. Stop the owned old backend and reconnect after changing configuration. Prefer the embedded DEV package over editing installed files or sharing production data. There is no automatic fallback from prod to DEV and no `switch-env` CLI. In explicit CMS mode the environment selects the template catalog; hosted main discovery is independent of it. It does not select model keys, accounts or every remote service. ## Host adapters and ownership | Host | Registration | Skills | | --- | --- | --- | | Codex | `codex mcp add openmotion` | Complete bundle under the selected Skills root | | Claude Code | `claude mcp add-json -s user openmotion` | Flat entries under `${CLAUDE_CONFIG_DIR:-~/.claude}/skills` | | DeepSeek Harness | `dsh plugin --profile web add --ignore-scripts` | Its dedicated bundle/provider Skill root | | WorkBuddy | Merge `mcpServers.openmotion` into its `mcp.json` | Flat entries under its configuration root | Select `--host codex|claude|deepseek|workbuddy` for a registration adapter, or the current Agent's lowercase name for [any other local Agent](#other-local-agents). `--skills-dir` selects the Codex/Claude/WorkBuddy/other-Agent root; Harness uses its own provider. Executable overrides are `--codex`, `--claude`, `--dsh`; Harness also accepts `--profile`. Isolate host configuration with `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `DSH_HOME` or `WORKBUDDY_CONFIG_DIR`; `--home` controls the application installation, not the host profile. Use the same installation flow for every host: collect the platform and Node/npm facts once, select the current Agent, run its setup adapter, then verify actual host loading while video components prepare in the background. An explicit `--host` takes precedence over host context; do not choose a host merely because its CLI is installed. The CLI retains its Codex default for compatibility, so Agent-driven installs should always pass `--host`. Only ask for the missing host/profile when reliable context is unavailable. `openmotion --help`, `setup --help`, `prepare --help` and `--version` work without installing or modifying configuration. For a non-Codex test, keep the isolated application/data paths from the examples above and change only the host-specific configuration: | Selected host | Isolated host configuration | Setup adapter options | | --- | --- | --- | | Codex | Separate `CODEX_HOME` | `--host codex --skills-dir ` | | Claude Code | Separate `CLAUDE_CONFIG_DIR` | `--host claude --skills-dir ` | | DeepSeek Harness | Separate `DSH_HOME` and selected profile | `--host deepseek --profile `; Skills live in this installation's managed bundle | | WorkBuddy | Separate `WORKBUDDY_CONFIG_DIR` | `--host workbuddy --skills-dir ` | Harness callers should pass the actual current profile from their host context, such as `DSH_PROFILE`, rather than assuming `web` or `desktop`. On macOS, setup already detects the standard Desktop CLI at `/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh`; it need not be on PATH. Keep that host-specific lookup in the Harness adapter. Other executable locations use `--dsh`; do not unpack the host or invent a wrapper for ordinary installation. After setup, use working native tools or the direct commands below to continue in the same chat. Refresh native discovery only when needed. Confirm the Tool and Skill names declared by this exact package's embedded manifest (`mcp.tools` and `skills`), allowing additional negotiated presentation Tools, and call `openmotion_get_project` to verify the expected data directory. Do not impose another host's restart or refresh procedure, or substitute an on-disk registration for host loading evidence. The internal ownership marker remains stable across the npm package rename so earlier local installations can be upgraded in place. An installation can serve multiple hosts using the same home/data. `install.json.hosts` retains each host. Skill documentation links are rewritten for flat layouts; Codex/Harness retain bundle-relative links. Re-run setup for each installed host when upgrading Skills. Unowned same-name MCP/Skills are refused. Unrelated settings/Skills and existing projects are retained. A registration failure before the profile changes restores the prior install state and Skills. If Harness has already switched to the new owned bundle, setup retains that bundle and its state even when registration or later onboarding reports an error; rerunning setup reconciles owned profile/state differences. Checked application caches remain available for retry. Compatible phase-one updates do not require closing existing MCP connections or stopping the same workspace's backend. Connections negotiate the API protocol and requested Tool, retaining running exports and completed results; see [shared editor recovery](shared-editor.md). The installer does not terminate existing processes. Incompatible protocols or internal legacy ABIs still require updating the connection and idle backend together. Refresh the host to discover new Tools or reload changed Skills; an already-closed transport needs host reconnection. ### Other local Agents Any `--host` value outside the four adapters, such as `opencode`, `cursor-agent` or `gemini`, uses the same application, launcher, data directory and Skills. Setup does not read or write that host's configuration. It copies flat Skills to `~/.agents/skills` (or `--skills-dir`), records the host in `install.json.hosts` and returns: ```json "agentRegistration": { "serverName": "openmotion", "transport": { "type": "stdio", "command": "/absolute/node", "args": ["/absolute/installHome/run-mcp.mjs"] }, "skillsDirectory": "/absolute/.agents/skills" } ``` The calling Agent adds this local stdio server using its own documented MCP format, preserving unrelated settings, then refreshes MCP and calls `openmotion_get_project`. Use the launcher exactly as returned: `run-mcp.mjs` reads `install.json` and configures the workspace, browser and media paths. Do not register a bare `mcp.ts`. `command` is the absolute Node executable that ran setup (`node.exe` on Windows), so no `.cmd` shim is involved. Adapter-less Agents share one Skills owner in that root, so installing a second such Agent reuses the same entries. `tools`, `call` and `diagnose` accept the same `--host` value; `diagnose` probes the launcher but cannot read that host's configuration. Example for OpenCode (`~/.config/opencode/opencode.json`; OpenCode also reads `~/.agents/skills`): ```json { "mcp": { "openmotion": { "type": "local", "command": ["/absolute/node", "/absolute/installHome/run-mcp.mjs"], "enabled": true } } } ``` Run `opencode mcp list` to confirm `openmotion` is connected and `opencode debug skill` to confirm the `openmotion-*` Skills. A host that cannot add a local stdio MCP server can still use `onboarding.directAccess` from a shell-capable chat. Adapter-less setup is not a compatibility claim for every listed Agent; each host's MCP loading is verified in that host. ## Continue in the current Agent chat Setup returns `onboarding.directAccess` with the exact Node executable and argument arrays for the selected installation and host. Prefer native tools when their workspace matches setup. If native tools are absent or still use an old installation, the Agent runs these commands itself in the same chat; no new Codex chat, separate Agent profile or host restart is required when shell execution is permitted: ```sh node /absolute/appRoot/scripts/npm-installer.mjs tools --host codex --home /absolute/installHome node /absolute/appRoot/scripts/npm-installer.mjs call openmotion_get_project --args-file /absolute/arguments.json --host codex --home /absolute/installHome ``` Use the actual paths from setup, preserving host/profile and CLI overrides. `tools` returns the public schemas and verified data directory. Write a JSON object to the arguments file using host file tools; do not interpolate user content into shell commands. `call` sends one request unchanged through the registered stdio MCP transport, including its cwd/environment. It validates installation ownership, enabled state, public tool contract, version and workspace before sending the requested operation. Host tool allow/deny lists apply. Server-side schema validation, stable request IDs, revision/version guards and export ownership remain unchanged. Tool failures return their evidence with a nonzero exit; the client never retries mutations. On timeout, inspect the original request/project/job state before retrying with the same request ID. Export calls queue jobs; poll the returned job rather than keeping a CLI call open. This is an installed MCP client, not native host discovery or reconnection. It starts only its owned transport process, closes it after each command and leaves the shared backend/projects/jobs intact. It cannot override host policy or permission denials. If shell execution is unavailable or neither access path works, diagnose the actual blocker and use the host's supported recovery, preserving this chat's template/project choice. Ask the user for action only when needed. Never report `hostSessionVerified:false` as an installation failure. ## Versions, upgrades and publication boundary Explicit builds accept `MAJOR.MINOR.PATCH-test.N[.N]` or `MAJOR.MINOR.PATCH`. CI-generated candidates use next-patch `test..`; manually assigned candidates can use `test.1`, `test.2`. Every artifact has one identity across the installer, app package/lock and plugin metadata. Build numbers never overwrite old output; source versions are not bumped by packaging. Source package manifests remain `private:true`. Only an explicit test/DEV or stable/prod build produces publishable tgz metadata. Test artifacts default to `candidate`; the manual publisher advances `test` after registry propagation and runs non-blocking Mac/Windows installation checks afterward. Stable artifacts default to `stage`; both matching prod installation checks must pass before `latest` advances. Local/default and channel/environment-mismatched artifacts remain private. No command here publishes or changes npm tags. See [test and stable acceptance](release-guide.md) for separate maintainer authorization and gates. After publication, the intended user entry is `npx --yes --package @openmotion/app@ -- openmotion setup --host codex`, followed by native discovery or direct installed access in the same chat; `prepare` is optional when an explicit wait or retry is needed. `@test` and `@latest` select channels; acceptance always records the exact resolved version. Installing/running npx alone, publishing a new package or moving a tag does not update an existing managed app. Before upgrading, back up projects/configuration, run setup with the new exact tgz and the **same** home/data/Skills paths, then continue through native tools or direct access while preparation runs (or explicitly wait with prepare). Compatible phase-one connections and active exports can continue. Refresh host discovery for new Tools or Skills; reconnect a closed transport. For an incompatible protocol, finish active exports before updating only the owned connection and idle backend together. Do not terminate unrelated services. Older app directories may remain, but rollback requires a compatible old package and data; back up before an irreversible format change. There is no automatic update or arbitrary-version rollback promise. ## Native tools and diagnostics ### npm download failures Recover npm network failures (`ENOTFOUND`, `EAI_AGAIN`, connection errors or timeouts) automatically before asking the user to troubleshoot: 1. **Try official, then mirror.** Try `https://registry.npmjs.org` then `https://registry.npmmirror.com`, at most once per registry, counting the initial failed attempt and skipping registries already tried. An explicitly selected registry goes first; respect any user or host restriction on alternatives. Stop on authentication, permission or checksum failures rather than switching sources. 2. **Keep settings temporary.** Set `npm_config_registry` and `npm_config_fetch_retries=0` for the attempt's process tree, covering both npx and setup's production `npm ci`. Do not change global npm configuration, project lockfiles or TLS verification. This fallback does not apply to separate browser/FFmpeg download hosts. 3. **Keep the same artifact.** Pin the exact requested/resolved version before switching. For channel tags, use the matching immutable guide and checksum, not the mirror's potentially older tag. If the tag never resolved, use the version stated in the trusted guide. Download a mirrored tgz with lifecycle scripts disabled, verify its SHA256 against that guide before executing it, then use the local-tgz setup command with the same host/profile and isolated paths. A missing mirrored version is not permission to downgrade; a checksum mismatch stops recovery. 4. **Both failed: diagnose, then hand off.** Compare `npm ping` in the actual installation environment and the user's terminal, using the same npm and registry; curl success alone is insufficient. Use the host's supported network-approval flow where permitted, without bypassing a denial. If Agent access remains unavailable, provide the complete setup command and selected environment/paths for the user's terminal: preserve Node/npm, working directory, host/profile, host configuration, application home, data and Skills paths. After setup, reconnect the host and verify its version and `openmotion_get_project` result. If the terminal also fails, resolve DNS/proxy/network access first and report installation as incomplete; preserve the previous installation and user data. A verified local tgz only replaces the outer download: production npm dependencies and native components still need network access. Native readiness and host loading remain separate results. References: [npmmirror](https://npmmirror.com/), [temporary npm configuration](https://docs.npmjs.com/cli/v11/using-npm/config/#environment-variables) and [npm ping](https://docs.npmjs.com/cli/v11/commands/npm-ping/). ### Export a local diagnostic ZIP Test and stable packages share the same collector. Open **Privacy settings → Export diagnostic ZIP** in Studio; the crash screen also offers the export. It saves a local download and does not upload it. The action works while native downloads or the renderer are unavailable, provided the local backend is running. If Studio or MCP cannot connect, run the CLI from the same exact package and installation home used for setup: ```sh openmotion diagnostics --home /absolute/installation-home --output /absolute/support.zip ``` The installed application also exposes `node /absolute/application/scripts/npm-installer.mjs diagnostics --home /absolute/installation-home --output /absolute/support.zip`. For a plugin, complete ZIP or source installation, use its actual data directory: ```sh node /absolute/application/scripts/diagnostics.mjs --data-dir /absolute/project-data --output /absolute/support.zip ``` `--output` is optional; the default is a uniquely named ZIP in the current directory. Existing files are never overwritten. `diagnostics` collects local files without starting MCP, Studio, native downloads, a renderer or a recovery action. It can produce a partial report even when setup has not completed. The separate `diagnose` command below actively probes MCP and is not run by ZIP collection. The archive includes version/build identity, OS/CPU/Node and registered host names when available, native preparation status, a bounded sample of export-job metadata, existing service/render logs and local failure records. `files.json` identifies collected, missing, excluded and truncated files. Missing information is not a successful host-session check. Existing host application logs are not scanned; use that host's own log viewer for failures before OpenMotion starts. The collector does not inspect arbitrary files or include projects, media, conversations, full host/provider configuration or an environment dump. Local records cover installation failures after the home exists, phase-one MCP failures, export failures, displayed operation errors and browser/React crashes. They are independent of usage telemetry and work in test builds and with telemetry disabled. Studio also records page/browser identity, selected workspace and native edit/import/render HTTP requests, and diagnostic-download stages. Requests have page-local correlation IDs, fixed route categories, response status and time to response headers; no request/response bodies, headers, project IDs, file names or query values are recorded. Healthy reads under two seconds, playback/selection updates, asset traffic and cancelled reads are omitted. ZIP export records archive receipt and browser download dispatch separately; dispatch is not proof that the browser saved a file. These completion records appear in a subsequent ZIP or persisted CLI log, not in the ZIP already being downloaded. Browser records stay in memory first, with separate error (20 entries / 16 KiB) and activity (39 entries / 7 KiB) rings. Including the loss summary, UI export remains below 60 records / 24 KiB. At most 20 errors and 40 activity records are admitted per minute per page; repeated errors or failing/slow read routes are coalesced for 30 seconds. The UI archive separates `browser-errors.json` and `browser-activity.json`, including counters for omitted records and failed delivery. One timer batches local storage and backend delivery every five seconds while records are pending; there is no idle heartbeat. Page hide also attempts a flush. Delivery uses at most one request at a time, 20 records per batch and a three-second deadline, without retries. Logging is never awaited by the user operation. Backend ingestion appends a batch together and preserves event timestamps. A browser crash can lose the pending tail; offline CLI cannot recover records that never reached the backend. The backend retains the current and previous diagnostic log, each at most 128 KiB. Existing engine/service logs keep their current retention behavior; the ZIP only reads bounded tails. A crash before a record reaches disk, a failed outer npm download or a failure before the collector can run may leave no log; include reproduction steps and the host's own logs in those cases. Known secret values from the current process environment, common credential formats, authorization/cookie values, URL details, email addresses and local paths are redacted before export. New local diagnostic records are also redacted before storage. Arbitrary private text embedded in an existing error log cannot be classified perfectly: **review the ZIP before sharing**. There is no automatic cloud upload. The HTTP route accepts same-origin POST requests only, with a fixed collection scope, bounded input, one collection at a time and a 30-second cooldown. It returns the ZIP directly without saving server-side archives. Reads skip symlinks and non-regular files; log tails are limited to 128 KiB each, log/archive inputs are bounded, directory scans stop at 100 entries and at most five sampled jobs are included. Local browser-event ingestion is limited to 60 records per minute across pages; excess delivery can be dropped without affecting editing. These controls contain accidental repeated clicks and remote requests; a user with local shell access can still run the CLI repeatedly and consume their own disk space. Export does not grant access beyond the local account's existing permissions. ### Missing MCP tools or a failed connection Run the installed CLI with the same application home and selected host: ```sh node /absolute/application/scripts/npm-installer.mjs diagnose --host codex --home /absolute/installation-home ``` The installed Skill's `scope.json` or `openmotion-install.json` supplies `runtimeRoot` (the application directory), `installHome` and `host`; do not guess them from the video project. The packaged npm CLI also exposes `openmotion diagnose` through the same exact package used for setup. Select `codex`, `claude`, `deepseek` or `workbuddy`; preserve any custom `--codex` executable or Harness `--profile`. The saved Harness profile is used by default. Diagnosis reads the selected host's owned configuration and starts an independent, bounded MCP probe using its command, arguments, registered environment overrides and working directory. It otherwise inherits the diagnostic process environment, which can differ from a GUI host. It verifies initialization, the installed tool list and a `openmotion_get_project` read of the expected data directory. It never registers/replaces configuration, creates a project, restarts another process or replays an export. A probe can start or reuse this installation's backend; it does not wait for native media/browser downloads. Credential-like environment values are redacted from reported startup output. The JSON result includes `status`, `hostSessionVerified:false` and `nextAction`; failures also include the stage, code and message. A successful probe does not establish that the current host chat loaded those tools, and Claude/WorkBuddy/Harness configuration reads cannot observe every session-specific enablement or tool-selection setting. Inspect the host's status/output and correct the reported configuration, runtime or version problem. In an interactive Claude Code session use the server's Reconnect action in `/mcp`; in other hosts use their supported MCP refresh/reconnect control. Then call `openmotion_get_project` through the active host connection, check the directory and original project/version, and resume the task. An empty tool search alone is not a diagnosis. For source/plugin installations without an npm `installHome`, use the host's actual registered launch command and logs. The source Codex bootstrap retains `scripts/check-installed-mcp.mjs`; do not point it at a guessed plugin cache or substitute a different workspace. A closed host transport must be reconnected by the host. Keep running exports and original request IDs while recovering. ### Native media and browser preparation The runtime lock pins HTTPS URLs, versions, target OS/CPU and SHA256 for FFmpeg, ffprobe and Chrome for Testing. Downloads require no repository credentials, never attach repository tokens, and do not run brew/winget. Independent archives are prepared concurrently from the existing platform manifest: three separate components on macOS, browser and combined media on Windows. Explicit `prepare` settles every component before returning; any failure rejects the operation while completed components remain reusable. Component and archive cache locks coalesce requests across processes and app versions sharing the same platform/hash cache. Contenders wait; dead-owner locks can be recovered without deleting live locks. Atomic per-component state supports Studio reloads and failure retry. Completed components are reused, including after another component fails. Temporary extraction and completion markers retain retry/cache protection. Downloads interrupted mid-transfer restart that asset; HTTP range resume is not implemented. A failed download is not ready. Explicit native path overrides remain supported. See [runtime details](test-packages.md). A local `--manifest /absolute/release-npm.json` remains available for legacy delivery and controlled fixtures. HTTP, URL credentials, unsafe extraction paths and invalid hashes are rejected. Do not remove a leftover install lock until its owning process is confirmed stopped. For defects, include exact package/app version, source SHA, OS/CPU, Node/Agent version, template environment/catalog version, project/revision, reproduction steps and redacted logs. Installation, native preparation, host discovery, model creation, technical MP4 checks and human playback are separate evidence. Follow the [acceptance manual](release-guide.md); unrun Windows/host/creation checks remain unrun. ## Shared Agent installation entry The hosted [installation guide template](install.md) provides the short Agent entry. Ordinary CI retains a candidate preview; the separate test publication workflow verifies the accepted candidate, publishes the same bytes, checks the exact registry installation and archives immutable version instructions before advancing the moving test guide. Repository R2 configuration, channel acceptance and enabled manual workflow entries are prerequisites. See [hosted instruction publication](release-guide.md#hosted-installation-instructions). Maintainers: see [manual candidate and test publication workflows](release-workflows.md) for fixed source/version selection, immutable snapshots, registry verification and recovery. A candidate artifact is not a published npm version. ## Managed recreation analysis Recreation measurement and registration use a private Python environment with the exact Python, NumPy and headless OpenCV versions and platform hashes in `scripts/runtime-lock.json`. First use of `skills/openmotion-recreate/scripts/vision-tools.mjs` prepares it in the installation cache. `openmotion prepare --home DIR` also prepares it explicitly. User-installed Python, pip and uv are unnecessary. Preparation downloads the locked archives once, installs only those local wheels without an index or dependency resolution, and publishes the environment atomically after checking imports and versions. Completed environments are reused across application versions sharing the same runtime identity. Complete platform ZIPs include the Python archive and both wheels in `runtime/vision-assets` for offline preparation. Lightweight npm installations need network access on first use. The vision tools support macOS 13+ arm64 and Windows 11+ x64. Host execution and network permissions still apply. Preparation failures report an error and can be retried with the same entry's `prepare` command. Project HTML/JavaScript and exported MP4s do not acquire a Python runtime dependency. The original Python distribution license files, NumPy distribution licenses and OpenCV wheel licenses (including bundled native-library notices) are retained in the shipped archives and installed environment. Source provenance is recorded in the pinned public URLs and hashes. ## Windows legacy installation recovery Published npm installation remains retired; these repairs preserve existing managed installations without enabling publication. Windows Codex, Claude and DeepSeek host adapters resolve supported npm `.cmd`/`.ps1` shims to the JavaScript or native executable and keep arguments outside a shell. Unsupported wrappers fail with an executable-path hint. Missing commands fail immediately; command deadlines are cleared on spawn failure, exit and timeout. Harness setup writes a fresh `hosts/deepseek-` bundle on each run and registers that path instead of renaming the bundle a running host may hold open. The previous owned bundle is retained, including the original `hosts/deepseek` layout. Refresh the host's Tools/Skills after setup. Superseded owned paths are recorded in `install.json.hosts.deepseek.retainedBundles`; setup also inventories older owned bundles after an interrupted run. Inspect cleanup with `node scripts/cleanup-harness-bundles.mjs --home ""`. After stopping every Harness process using that installation, rerun with `--confirm-all-processes-stopped`. Cleanup preserves both the currently registered and state-selected bundles, refuses unverifiable ownership, retains directories it cannot remove and reports them for retry. Automatic cleanup of potentially open bundles is disabled. Project data and unrelated host configuration remain separate. New runtime locks record their owner and recover after its process exits. On hosts without the shared editor, including Windows, a legacy empty `workspace.lock` has no trustworthy owner and is not deleted automatically by the workspace runtime. The macOS shared-editor startup already removes an empty regular legacy lock; use offline recovery only if the lock still blocks startup. From the updated source checkout or application root, inspect it with: ```sh node --experimental-strip-types scripts/recover-workspace-lock.ts --data-dir "" ``` This first command changes nothing. Stop every Studio/backend, connected Agent and export using that exact directory. Only after verifying they have stopped, rerun with `--confirm-all-processes-stopped`. Recovery quarantines the empty file beside its original path, preserves project data and refuses nonempty or symbolic-link locks. Restart using the same data directory. The confirmation is an operator assertion, not automatic proof that no legacy process is alive; do not run recovery against an active workspace.