Publishing

Publishing is the process of pushing a built tarball to the artifact registry and updating the catalog's discovery index. Gitea is the Matrix-native registry; the v1 publish path targets Gitea behind the npm-compatible HTTP API. npmjs.com is a target-state mirror path for public verticals; it is not the default.

Pages

• Publish flow — the end-to-end pipeline today
• Promotion — moving a version between channels
• Revocation — removing or yanking a published version
• Private packages — Gitea-only, pre-launch
• Public packages — npmjs.com path (target state)

The two paths

Default — Gitea (Matrix-native)

mx publish --registry https://registry.hivecast.ai/api/packages/open-matrix/npm/

Gitea serves the npm-compatible API. mx publish shells out to npm publish against that URL. Operators can delete versions on Gitea, which is why pre-launch development uses Gitea exclusively. This is the v1 path.

Public — npmjs.com (target state)

Status: target state — vertical-specific, post-v1. A package intended for distribution outside the HiveCast ecosystem can publish to npmjs.com. The npm publish safety audit at projects/matrix-3/packages/docs/content/security/npm-publish-safety.md is mandatory prerequisite reading. Once published to npmjs.com, a version is permanent — npm does not allow deletion.

The substrate's launch wedge is not npmjs.com; it is hivecast install gitea://... and the MCP bridge that lets existing AI agents consume Matrix actors. Public npm publication is a vertical's distribution choice, not the substrate's.

Critical context

Publishing operations are dangerous. An accidental npm publish to npmjs.com is permanent. The npm publish safety audit (projects/matrix-3/packages/docs/content/security/npm-publish-safety.md) documents the gate that must pass before any public publish. Read that audit before running any publish flow against npmjs.com.

The Gitea path is reversible (operators can delete versions), which is why pre-launch development uses Gitea exclusively.

What mx publish does

The orchestration lives in projects/matrix-3/packages/mx-cli/src/commands/publish.ts. The authoring side of the same flow (manifest validation, packing, version metadata) lives in docs-package-lifecycle / Publishing.

This docs package owns the registry-side description: where the tarball ends up, how the index is updated, how channels and revocation work. The author-facing pipeline is in docs-package-lifecycle.

See also

• Artifact Registry — where tarballs are stored after mx publish completes
• Install Resolution — the receiving side of every publication path
• docs-package-lifecycle / Publishing — authoring-side pipeline
• docs-package-lifecycle / Versioning — semver discipline

Source: Publish wiring is .github/workflows/release.yml and projects/deploy-cloud/deploy.sh:43. The npm publish safety audit at projects/matrix-3/packages/docs/content/security/npm-publish-safety.md is the prerequisite reading for any public-publish work.