---
name: manage-harbor-versions
description: Check and bump Harbor component versions for every runtime, UI, API, dependency, packaging, or deployment-config change in this repository. Use before completing implementation work, release preparation, or any change that can alter the shipped Mac client, Gateway client, or Gateway backend.
---

# Manage Harbor Versions

Treat `src/shared/versions.js` as the only component-version source. Do not use the root package version as a release version.

## Required workflow

1. Inspect the complete diff and choose the comparison base, normally `HEAD` for working-tree changes or the target branch for a review.
2. Run `npm run version:harbor -- affected <base>`.
3. Classify the highest compatibility impact:
   - `major`: changes an ecosystem contract or requires all cooperating components and clients to update;
   - `minor`: changes one component and its tightly linked components while remaining compatible with other clients on the same major;
   - `hotfix`: changes only the affected component without requiring linked components or other clients to update.
4. Run one explicit bump command:
   - `npm run version:harbor -- bump major`
   - `npm run version:harbor -- bump minor <components...>`
   - `npm run version:harbor -- bump hotfix <components...>`
5. Run `npm run version:harbor -- check <base>` and the repository tests before completion.

Valid component names are `mac`, `gateway-client`, and `gateway-backend`. A major bump always updates all three components. A minor bump for either Gateway component automatically updates both Gateway client and Gateway backend. A hotfix updates only the named component.

Do not bump documentation- or test-only changes. If the version contract is new and the base has no `src/shared/versions.js`, keep the initial versions and let the checker report that no baseline exists.