HubBound file

What it is

The HubBound file is hubbound.json in the project directory. It records the exact artifacts and kits a project depends on and, optionally, the local packages that this repository can publish.

For install and upgrade, HubBound finds the nearest project file by walking up from the current directory. Deploy is deliberately different: --path must point to the directory that contains the manifest, so a parent manifest is never selected accidentally.

What it is for

Use dependencies to declare the tooling a project expects. Running hubbound install with no arguments bulk-installs every dependency — similar to bare npm install reading package.json.

Use deployments to describe artifacts and kits that hubbound deploy may publish. Install reads dependencies; deploy reads deployments. Keeping those maps separate prevents a project dependency from becoming a release just because it appears in the same file.

File structure

New files use schema_version 2. hubbound init creates the name and an empty dependencies object; add deployments when the repository publishes artifacts or kits.

{
  "schema_version": 2,
  "name": "my-app",
  "dependencies": {
    "artifacts": {
      "vendor/shared-rule": "1.4.0"
    },
    "kits": {
      "vendor/base-kit": "2.0.0"
    }
  },
  "deployments": {
    "auditor": {
      "kind": "artifact",
      "path": "packages/auditor",
      "tag": "security-auditor",
      "version": "1.2.0",
      "visibility": "public",
      "artifact_type": "SKILL",
      "description": "Security audit skill",
      "content": { "entrypoint": "SKILL.md" },
      "files": ["SKILL.md", "references/**", "scripts/**"]
    },
    "security-kit": {
      "kind": "kit",
      "path": "packages/security-kit",
      "tag": "security-kit",
      "version": "2.0.0",
      "visibility": "public",
      "description": "Security tooling",
      "changelog": "Publish the auditor skill",
      "members": [
        { "deployment": "auditor" },
        { "tag": "vendor/remote-auditor", "version": "1.5.0" }
      ]
    }
  }
}

• Project dependency pins must be exact SemVer values such as 1.2.0 — latest is not valid in a v2 project manifest. Profile manifests retain their separate historical latest behavior.
• Unknown fields, duplicate JSON keys, invalid types, duplicate kit members and local deployment cycles are rejected.
• HubBound finds the file by walking up from the current directory.

Legacy files and migration

Older manifests with root-level artifacts, kits, or publish fields are accepted as v1 for compatibility and normalized in memory. Mutating operations serialize the canonical v2 shape under dependencies and deployments; hubbound init writes v2 directly.

Do not mix root-level artifacts/kits with a v2 document. In v2, dependencies is the only dependency map and deployments is the only publication map.

Publish with hubbound deploy

A deployment is a release recipe, not an upload directory guessed from the current shell. Select one or more deployment names, or omit names to process every entry in deployments.

For an artifact, deploy snapshots the files declared by files, hashes every byte, asks the authenticated release control plane which digests are missing, uploads those bytes to the presigned URLs, and commits the release. A kit sends its exact artifact composition through the kit release route; local artifact members are prepared before the kit.

• Preflight requires a Git worktree, remote.origin.url, an HTTPS remote without embedded credentials, and a 40- or 64-character hexadecimal HEAD SHA. Query and fragment are removed from the normalized repository URL.
• Artifact file patterns are relative and support **. Every match must be a regular, non-symlink UTF-8 text file: at most 250 files, 2 MiB per file and 10 MiB total logical size.
• The snapshot excludes .git, hubbound.json, .env files, backup files and private key/certificate extensions (.pem, .key, .crt), and rejects binary formats such as images, archives, PDFs, executables and fonts.
• The authenticated control-plane calls use DPoP. The presigned CAS PUT uses the exact headers returned by the backend and must not receive Authorization or DPoP headers.
• A committed release and its public-registry projection are separate states. In the current checkout the public watcher is not wired, so a public release may be committed while the command reports that publication status is unavailable; verify release_state and publication_state separately.

Compatible commands

These commands read and/or write the project hubbound.json.

vs profile manifests

Both use hubbound.json, but project manifests and profile manifests have different responsibilities.

• Project hubbound.json → local/project dependencies and optional deployments; usually committed.
• profiles/<name>/hubbound.json → global dependency pins under user config; profiles cannot contain deployments.
• --profile on install always targets a profile file and forces global scope.
• Bare hubbound install requires a project hubbound.json (or run hubbound init first).