# Host integrations

## Build a local Codex plugin

If you received an already-built plugin directory, skip to registration; you do not need to build it.

From the source checkout, with Node.js 24+ and pnpm installed:

```sh
pnpm install
pnpm package:hosts
pnpm test:hosts
```

`package:codex` builds `release/codex/rideo/` with the manifest, three skills, JavaScript runtime, metadata, and license notices. Distribute the entire directory. Runtime needs Node.js 24+, yt-dlp for subtitles, and FFmpeg/ffprobe for preparation or new frames; existing bundles need only Node and the built toolkit. No source checkout, build tools, global Rideo, or `node_modules` is required.

`dist/` and `release/` are Git-ignored. Build before installing; Codex does not build source checkouts. Optional Git distribution publishes generated files and a marketplace catalog to a dedicated branch.

The assembler validates matching package/plugin versions and missing build inputs before replacing the previous output. Direct `node scripts/package-hosts.ts` only assembles an existing build; use `pnpm package:codex` to ensure it is current.

## Register and install

Codex installs plugins through a marketplace. For a personal installation, use the Codex plugin-creator skill to register the built directory in the personal marketplace. Its scaffold and marketplace helpers belong to the development environment, not to the shipped plugin.

For a new personal entry with the standard helper location:

```sh
python3 ~/.codex/skills/.system/plugin-creator/scripts/create_basic_plugin.py rideo --with-marketplace
```

Copy the contents of `release/codex/rideo/` into the plugin source directory reported by that helper, replacing the scaffold manifest. With the default scaffold location, run this from the source checkout:

```sh
cp -R release/codex/rideo/. ~/plugins/rideo/
```

Preserve that location for subsequent updates. The helper creates the personal marketplace at `~/.agents/plugins/marketplace.json`; do not overwrite an existing entry blindly. Confirm its name and install:

```sh
python3 ~/.codex/skills/.system/plugin-creator/scripts/read_marketplace_name.py
codex plugin add rideo@personal
codex plugin list
```

Use the actual printed marketplace name if different. The default personal marketplace is discovered implicitly. For an explicitly chosen non-default marketplace, register its root first with `codex plugin marketplace add /absolute/marketplace-root` and use its actual name in `codex plugin add`. Do not point that command at a bare plugin directory.

Start a new Codex task after installation. Use `rideo` for authorship, `rideo-qa` for manuscript questions, and `rideo-review` only on request. Skills resolve the CLI relative to their installation and write to the workspace. The host must support viewing local images.

## Update and remove

Rebuild, copy the new plugin contents to the registered source directory, validate the marketplace name with `read_marketplace_name.py`, then run the plugin-creator update helper on that directory:

```sh
python3 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py /absolute/registered/rideo
codex plugin add rideo@personal
```

The cachebuster changes only the installed source copy's version suffix; keep repository package and manifest versions synchronized. Start a new Codex task to pick up the update. Remove the installed plugin with `codex plugin remove rideo@personal`; this does not remove your source media or generated lessons.

## Validation scope

`pnpm test:hosts` exercises built packages outside the checkout in a Unicode/space-containing path, including offline evidence reads/exports, pi's eight tools, native images, cancellation, bounded output, and write serialization. Release tests use a disposable Git remote. FFmpeg is required for fixtures.

Manifest validation and an isolated Codex marketplace installation complement these runtime tests. Deterministic loader tests alone do not prove that a model inspected images or followed the skill.


## Install the pi package

`pnpm package:hosts` produces `release/npm/rideo-<version>.tgz` and `release/rideo-codex-<version>.tgz`. The npm package includes CLI/core, declarations, pi integration, and both skill layouts. Pi supplies TypeBox; host peers are optional for CLI/library users. Pinned development dependencies in `package.json` define the tested baseline, not universal host compatibility.

Unpack the npm tarball into a permanent directory, then install that directory with pi:

```sh
mkdir -p /absolute/rideo-install
# Replace the version with the actual generated filename.
tar -xzf release/npm/rideo-0.1.0.tgz -C /absolute/rideo-install
pi install /absolute/rideo-install/package
pi list
```

Pi records local package paths without copying them, so keep the unpacked directory in place. Use `-l` for project-local registration if wanted. Start a fresh pi session or use `/reload` after updating files. Replace the unpacked package with a new built tarball for upgrades; `pi remove /absolute/rideo-install/package` removes its registration. Installing a tarball as an npm dependency with production dependencies only is also supported; point pi at that installed directory. Registry publication is not required.

Pi exposes eight native tools through the shared core; see the [tool mapping](../skills/rideo/references/tools.md#runtime). Invoke `/skill:rideo`, `/skill:rideo-qa`, or explicitly request `/skill:rideo-review`. Plugin load and ordinary authorship never start a reviewer.

Use a model with image support. Check `pi --list-models <model>` and select your provider/model through pi. The extension never changes model settings.

`rideo_view_frame` sends one validated PNG and timestamp metadata, with a 10 MiB image limit. `rideo_explore` returns its shortlisted color previews inline alongside state relationships and coverage diagnostics; other tools return metadata and paths. Text results longer than 16,000 characters are saved to `.rideo/results/` in the active workspace, with a bounded preview and complete JSON path returned. This working directory should not be included in learner deliveries.

Evidence reads validate all bundle metadata and paths but deeply verify only accessed PNGs, without caching. Default `loadBundle()` and `rideo_export_frames` verify every image, including unselected ones. See [evidence access](../skills/rideo/references/tools.md#inspect-and-add-evidence) for validation scope.

Tool failures include core error codes and bounded diagnostics. Cancellation remains distinct from timeout/media failure, terminates child processes (POSIX process groups), and cleans staging/cookie snapshots. Once final publication begins, it finishes and may report success despite cancellation. Same-output writes are serialized within one extension; separate processes require one writer per bundle. Linux is the tested platform.

The CLI forwards `SIGINT` and `SIGTERM` into the same cancellation mechanism and waits for cleanup before exiting with status 130 or 143, respectively. Subtitle downloads use a temporary directory until validation succeeds; a cancelled download leaves its output directory empty so it can be retried.

## Shared skill metadata

Canonical instructions live in `skills/`. Codex retains review's explicit invocation policy in `agents/openai.yaml`; pi's generated `dist/pi-skills/` adds `disable-model-invocation: true` only to review frontmatter, since Codex rejects that field. Tests check identical bodies, discovery of all three skills, explicit-only review, and layout-relative CLI resolution.

## CI and Git distribution

The normal CI workflow checks types/lint, unit tests, real-media integration, and host packages. The manually triggered **Host packages** workflow builds and uploads both tarballs. It defaults to artifacts only. Setting `publish_branch` also publishes the generated Codex marketplace to `codex/plugin-release` using a dedicated job with repository contents-write permission. It updates that branch with a normal commit/push and never force-pushes or adds `dist` to the development branch. Publishing changed artifacts requires a new synchronized package/plugin version so Codex does not reuse an old cache entry.

Pushing a version tag such as `v0.1.0` runs the same validation and build, publishes the marketplace branch, and creates a GitHub Release containing both installation archives. The tag must equal `v` followed by the version in both `package.json` and `.codex-plugin/plugin.json`. Tag releases require no npm registry credentials; private repositories keep their release assets private.

`pnpm package:marketplace` stages the branch contents at `release/git/`: `.agents/plugins/marketplace.json` and `plugins/rideo/`. It changes no user marketplace. Once the workflow has published the branch in your GitHub repository, users can install it without building:

```sh
codex plugin marketplace add xunz3/rideo --ref codex/plugin-release
codex plugin add rideo@rideo-releases
```

The repository is private, so authenticate Git with an account that has access before installation. Refresh with `codex plugin marketplace upgrade rideo-releases`, reinstall, and start a new task. This Git route distributes the Codex plugin; pi users install the npm tarball.

Download the pi archive from the private GitHub release with an authenticated GitHub CLI, then use the unpack/install steps above:

```sh
gh release download v0.1.0 --repo xunz3/rideo --pattern 'rideo-0.1.0.tgz'
```

Release downloads are available on the [GitHub releases page](https://github.com/xunz3/rideo/releases).

## npm registry publishing

The public npm package is `rideo`. After registry publication, install it with
`pi install npm:rideo`; the CLI is also available with `npm install -g rideo`.
Codex continues to use the generated marketplace branch.

Tag releases publish the same npm archive produced by the tested build job.
The publish job uses npm 11.17.0 and GitHub OIDC with `id-token: write`; no
long-lived npm publishing token is required. It runs outside the source checkout
so the project's pnpm-only development configuration does not reject npm CLI
commands. Lifecycle scripts are disabled when uploading the built archive.

Configure the package's Trusted Publisher on npmjs.com with GitHub owner `xunz3`,
repository `rideo`, workflow filename `release.yml`, no environment, and direct
`npm publish` allowed. The package must first exist on npm; bootstrap it by
publishing the corresponding GitHub Release npm archive after interactive npm
login. Account login and any 2FA verification remain interactive.

The npm package is public independently of GitHub repository visibility. While
GitHub is private, the workflow disables provenance. Once the repository becomes
public, tag runs enable provenance automatically. Keep `repository.url` aligned
with the repository. Synchronize package/plugin versions before each new tag;
npm versions cannot be overwritten. If only the npm job fails, fix its setup and
rerun the failed job rather than creating or moving the version tag.