Publishing Packages

Each HQ package ships from its own repo on its own version — there is no shared version and no single tag that publishes everything. See the Ecosystem & Repo Map for the full topology.

npm organization

The CLI and sync engine publish under the @indigoai-us npm scope. Content packs publish as @indigoai-us/hq-pack-*. The desktop and cloud apps are not npm packages — they release as a signed app or a cloud deploy.

Repo	Ships as	Scoped	Release mechanism
hq-cli	@indigoai-us/hq-cli	Yes	npm publish from the repo
hq-cloud	@indigoai-us/hq-cloud	Yes	npm publish from the repo
hq-packages	@indigoai-us/hq-pack-*	Yes	npm publish per pack
hq-core	npx create-hq scaffold	—	latest scaffold pulled by create-hq
hq-sync	macOS app	—	v* tag → signed DMG + latest.json
hq-console / hq-pro / hq-deploy	cloud apps	—	Vercel / SST deploy

Prerequisites

• npm account with publish access to the @indigoai-us org
• NPM_TOKEN secret set in the target repo’s GitHub settings
• Two-factor authentication enabled on the npm account

Publishing an npm package (hq-cli, hq-cloud)

Work in the relevant repo. Each is standalone — bump only that repo’s version.

1. Bump the version

cd hq-cli           # or hq-cloud
npm version patch   # or minor / major

2. Build, typecheck, test

npm run build && npm run typecheck && npm test

3. Publish

npm publish --access public

Dependency note: hq-cli depends on a published @indigoai-us/hq-cloud. When a change spans both, publish hq-cloud first, then bump hq-cli’s dependency range and publish hq-cli.

Automated publishing (CI/CD)

Each package repo has its own release workflow that triggers on a version tag pushed in that repo:

on:
  push:
    tags: ['v*']

Typical steps: checkout → setup Node → npm ci → build → typecheck → npm publish. Because the repos are independent, a tag in hq-cli publishes only hq-cli; it never touches hq-cloud or the apps.

Releasing the scaffold (hq-core)

hq-core is the create-hq seed, not an npm package. Users always pull the latest scaffold via npx create-hq, so “releasing” means landing changes on the repo’s main branch and bumping hqVersion in core.yaml. Existing instances upgrade with /update-hq.

# scaffold a throwaway instance to test changes
npx create-hq ~/test-hq

Releasing the desktop app (hq-sync)

The menubar app releases by pushing a v* tag, which runs the sign/notarize/DMG workflow and publishes latest.json for auto-update. Bump the version in package.json, src-tauri/Cargo.toml, and src-tauri/tauri.conf.json together before tagging.

Releasing a content pack (hq-packages)

Each pack carries its own version in package.yaml and publishes as @indigoai-us/hq-pack-<name>. Users install with hq install @indigoai-us/hq-pack-<name> — see hq-packages.

Version strategy (per package)

• Major: breaking changes to the package’s interface
• Minor: new features / commands
• Patch: bug fixes, content updates

Each repo versions independently, so compatibility is expressed through dependency ranges (e.g. hq-cli declaring @indigoai-us/hq-cloud ~5.25.0) rather than a shared release train.