#Releasing this fork

A complete OMPK release has three independent publication gates. Finishing one gate does not finish either of the others:

bun scripts/release.ts X.Y.Z creates the tag and drives the GitHub gate. It does not publish the private Hugging Face channel, and a GitHub Release is not evidence that either installer mode has moved to the same version. In particular, npm is an independent, required gate: the default installers cannot receive X.Y.Z until the complete npm package graph for X.Y.Z is available.

#Installer behavior

The canonical installer endpoints serve the installer scripts, not a preselected binary:

# Default on macOS and Linux: install/validate Bun, then install the npm package.
curl -fsSL https://oh-my-pk.pkking.computer/install.sh | sh

# Explicit standalone binary mode.
curl -fsSL https://oh-my-pk.pkking.computer/install.sh | sh -s -- --binary

# Default on Windows: install/validate Bun, then install the npm package.
irm https://oh-my-pk.pkking.computer/install.ps1 | iex

# Explicit standalone binary mode.
& ([scriptblock]::Create((irm https://oh-my-pk.pkking.computer/install.ps1))) -Binary

Default mode installs @pk-nerdsaver-ai/pi-coding-agent from npm. Explicit binary mode supports macOS x64/arm64, Linux x64/arm64, and Windows x64. The two modes have separate publication gates even though a complete release should use the same X.Y.Z version in both.

Passing --ref / -Ref without the binary flag selects the source-install path. Passing it together with the binary flag selects that exact binary tag.

#Hugging Face binary-channel contract

The standalone binaries live in the private Hugging Face model repository pkkidking/oh-my-pi-binaries by default. HF_REPO can select another private repository. The Cloudflare Worker holds the read token; installer clients never receive a Hugging Face credential.

The repository layout for a complete release is:

VERSION                         # exactly: vX.Y.Z plus a newline
vX.Y.Z/omp-darwin-arm64
vX.Y.Z/omp-darwin-x64
vX.Y.Z/omp-linux-arm64
vX.Y.Z/omp-linux-x64
vX.Y.Z/omp-windows-x64.exe

The public install endpoint exposes those private objects as:

https://oh-my-pk.pkking.computer/version
https://oh-my-pk.pkking.computer/bin/vX.Y.Z/<filename>

VERSION must contain the V-prefixed tag, such as v16.4.6, never the bare package version. The Unix and PowerShell installers use /version only in explicit binary mode, then request /bin/<tag>/<filename>.

publish-binaries-hf.ts checks the five filenames above across the requested build and files already present under the tag. It flips VERSION only after the tag is complete. Partial uploads remain addressable by their versioned /bin/vX.Y.Z/... paths, but unpinned binary installs continue resolving the previous complete tag.

--force-version bypasses the completeness guard and can expose 404s on missing platforms; reserve it for a deliberately partial channel. --no-version uploads without changing the live pointer. --force-build rebuilds and re-uploads requested files that already exist.

#Prerequisites

• bun, sd, git, and the Rust/Cargo toolchain used by the release and

native-build scripts.

• The native toolchain and prebuilt native addon required by every binary target

requested on a build host.

• The Hugging Face hf CLI and a write-scoped HF_TOKEN for the private model

repository.

• A configured npm publication identity. CI publication should use the

repository's trusted-publishing/token route rather than treating a local login on one build host as cross-platform completion.

Never place either Hugging Face or npm credentials in commands committed to the repository, release notes, or logs.

#Release procedure

Use an unprefixed semantic version (X.Y.Z) with release.ts; it creates the V-prefixed Git tag (vX.Y.Z).

#1. GitHub gate

bun scripts/release.ts X.Y.Z

The script performs preflight checks, updates public package/workspace versions and changelogs, commits, tags, pushes, and waits for the enabled GitHub Actions release run. The GitHub result is one gate only.

#2. Hugging Face binary gate

Run the publisher on hosts with the required native artifacts and toolchains. Always pass the intended V-prefixed tag explicitly:

# Windows x64 host
$env:HF_TOKEN = "<write-scoped-token>"
bun scripts/publish-binaries-hf.ts --tag vX.Y.Z --targets win32-x64

# Linux build host
HF_TOKEN="<write-scoped-token>" bun scripts/publish-binaries-hf.ts \
  --tag vX.Y.Z --targets linux-x64,linux-arm64

# macOS build host
HF_TOKEN="<write-scoped-token>" bun scripts/publish-binaries-hf.ts \
  --tag vX.Y.Z --targets darwin-x64,darwin-arm64

Requested cross-target builds still need that target's native addon and toolchain; the binary publisher does not manufacture a missing cross-platform native build. Reruns are idempotent unless --force-build is supplied. The last run that makes all five filenames present flips VERSION to vX.Y.Z.

For local recovery, release-local.ts composes the tag step and the Hugging Face publisher:

bun scripts/release-local.ts X.Y.Z
bun scripts/release-local.ts X.Y.Z --skip-tag --targets darwin-x64,darwin-arm64
bun scripts/release-local.ts X.Y.Z --dry-run

It builds the host target by default. Its --npm option invokes the general npm publish command, but that alone is not evidence that all five generated native leaf packages were published; use the complete npm publication route below.

#3. npm gate

The npm release must publish the same X.Y.Z across:

• the selected 13-package core/workspace graph published by

ci-release-publish.ts, including @pk-nerdsaver-ai/pi-coding-agent and @pk-nerdsaver-ai/pi-natives; and

• @pk-nerdsaver-ai/pi-natives-linux-x64,

@pk-nerdsaver-ai/pi-natives-linux-arm64, @pk-nerdsaver-ai/pi-natives-darwin-x64, @pk-nerdsaver-ai/pi-natives-darwin-arm64, and @pk-nerdsaver-ai/pi-natives-win32-x64.

ci-release-publish.ts deliberately splits this work. Its default mode publishes the selected 13-package core/workspace graph, including the native core package. After the GitHub release is verified, the dedicated release_npm_native matrix downloads each target's matching .node artifacts and invokes the native-leaf mode before release_npm can publish the core/workspace graph.

Trusted publishing must be configured for all 18 npm packages with repository kingkillery/oh-my-pk, workflow ci.yml, and no npm environment restriction. A package that has never been published cannot yet have that trusted publisher configured; seed it once with a short-lived granular token, configure the trusted publisher, then revoke the bootstrap token. For this remediation, @pk-nerdsaver-ai/pi-deep-research is the only package requiring that one-time seed.

For a new shared version, publish all five native leaves successfully before publishing the workspace/core graph:

bun scripts/ci-release-publish.ts --native-leaf linux-x64
bun scripts/ci-release-publish.ts --native-leaf linux-arm64
bun scripts/ci-release-publish.ts --native-leaf darwin-x64
bun scripts/ci-release-publish.ts --native-leaf darwin-arm64
bun scripts/ci-release-publish.ts --native-leaf win32-x64
bun scripts/ci-release-publish.ts

These are CI publication interfaces, not a claim that one local host has all native artifacts. Use the repository's release publication job so every native-leaf invocation receives the artifact produced for its platform. Do not publish the workspace/core graph first: it would make the default package version visible before its complete cross-platform native dependency set.

The npm gate is complete only when the registry contains the workspace/core packages and all five native leaf packages at X.Y.Z. Until then, do not describe the release as available through the default installers, regardless of the GitHub Release or Hugging Face VERSION value.

#Completion checklist

• [ ] GitHub has the intended vX.Y.Z tag and completed GitHub Release.
• [ ] The private Hugging Face model repository contains all five binaries under

vX.Y.Z/.

• [ ] Hugging Face VERSION contains exactly vX.Y.Z.
• [ ] /bin/vX.Y.Z/<filename> maps to each expected platform asset through the

Worker.

• [ ] npm has the selected 13-package core/workspace graph and all five native

leaf packages at X.Y.Z.

• [ ] The default installer resolves the npm release; explicit binary mode

resolves the Hugging Face release.

See the install-redirect guide for Worker route and secret configuration.