harness.json reference

See what harness.json is for the concept. This page covers every field baselane checks in your harness.json.

Fields

version: must be exactly 1. There is no v2 shape yet.
registry: a registry base URL string, or null (falls back to the BASELANE_REGISTRY env var, then the CLI default https://registry.baselane.sh).
target: { kind: "repo" | "machine", id }. id is the repo's directory name, or the machine's hostname for a -g install.
packs: an object mapping a pack name (either github:owner/repo or @scope/name) to one exact version, like a git ref, branch, tag, sha, or an exact registry version. It never records a range like "1.2.0 or newer." Baselane calls this exact value a pin.
capabilities: a free-form, JSON-serializable object of per-target capability configuration. Optional; defaults to {}.
materialized: the install receipt, optional (defaults to all-empty). Its sub-fields:
- vendored: {path, sha256}[] for files written verbatim (the legacy shape, a bare path string with an implied sha256: null, is also accepted).
- managedRegions: {path, regions}[] for content-preserving files (e.g. AGENTS.md). Each region records the contributing packId, its version, and a sha256 of the region body.
- derivedCommitted: paths derived (not pack-authored) but committed anyway.
- resolutions: per pack name, what the pin actually resolved to: {ref, sha, packId}.
- capabilities: per capability name (e.g. system-map), a receipt: {sourceSha, generatedTs, paths: {path, sha256}[]}.

Examples

Every example on this page is tested automatically. Valid ones install cleanly; invalid ones show the error described.

Minimal valid repo manifest

Valid. The smallest manifest validateManifest accepts: version 1, a repo target, and one exact pack pin. registry/capabilities/materialized are all optional and default to null/{}/empty lists.

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/disciplined-workflow": "v1.4.0"
  }
}

Machine (global, -g) target manifest

Valid. `baselane install -g` writes here instead of a repo: target.kind is "machine" and target.id is the hostname (targetLocation() in packages/materialize/src/manifest-io.ts). Lives at ~/.baselane/harness.json, materializing into ~/.claude/.

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "machine",
    "id": "mohammads-macbook"
  },
  "packs": {
    "github:baselane/second-brain": "v1.0.0"
  }
}

Registry + git pack pins together

Valid. A manifest can mix pin styles: a `github:owner/repo` key pinned to a git ref/tag, and a `@scope/name` key pinned to an exact registry version. Pins are always exact strings — manifest pins never carry a range.

{
  "version": 1,
  "registry": "https://registry.baselane.sh",
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/frontend-taste": "main",
    "@baselane/second-brain": "1.2.0"
  }
}

Capabilities declared

Valid. `capabilities` is a free-form object (validated only as JSON-serializable) — it holds whatever per-target capability configuration a pack's install left behind, distinct from `materialized.capabilities`, which is the receipt of what got written.

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/second-brain": "v1.0.0"
  },
  "capabilities": {
    "wiki": {
      "store": "repo",
      "method": "baselane"
    }
  }
}

Materialized receipt: vendored files with sha256

Valid. `materialized.vendored` is the v2 shape — {path, sha256} pairs, one per vendored file. `baselane drift` compares the file currently on disk's hash against this receipt to detect modification. A pre-M2 install may still have the legacy string-only shape (sha256: null).

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/second-brain": "v1.0.0"
  },
  "materialized": {
    "vendored": [
      {
        "path": ".claude/skills/second-brain/SKILL.md",
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      {
        "path": ".claude/agents/librarian.md",
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    ]
  }
}

Materialized receipt: managed regions with per-pack versions

Valid. `materialized.managedRegions` covers content-preserving files (AGENTS.md, CLAUDE.md, ...) baselane merges into rather than clobbers. Each entry's `regions` array records, per contributing pack, the pack version and a sha256 of the region body — drift on either dimension is `version-drift` or `content-drift` respectively.

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/disciplined-workflow": "v1.4.0"
  },
  "materialized": {
    "managedRegions": [
      {
        "path": "AGENTS.md",
        "regions": [
          {
            "packId": "disciplined-workflow",
            "version": "1.4.0",
            "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
          }
        ]
      }
    ]
  }
}

Materialized receipt: resolutions + capabilities receipt

Valid. `materialized.resolutions` records, per pack name, exactly what the pin resolved to at install time (ref, sha, packId) — the audit trail behind the pin. `materialized.capabilities` records what a centrally-computed capability (system-map/wiki/graph) wrote: a source sha, a generation timestamp, and the hashed paths it produced.

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/second-brain": "v1.0.0"
  },
  "materialized": {
    "resolutions": {
      "github:baselane/second-brain": {
        "ref": "v1.0.0",
        "sha": "dddddddddddddddddddddddddddddddddddddddd",
        "packId": "second-brain"
      }
    },
    "capabilities": {
      "system-map": {
        "sourceSha": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "generatedTs": "2026-07-17T00:00:00.000Z",
        "paths": [
          {
            "path": "ARCHITECTURE.md",
            "sha256": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
          }
        ]
      }
    }
  }
}

INVALID — unsupported version

Invalid. Rejected. `version` must be exactly the number 1 (validateManifest: `unsupported version ... expected 1`). There is no v2 manifest format yet.

{
  "version": 2,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {}
}

INVALID — empty pack pin

Invalid. Rejected. A pack pin must be a non-empty string — manifest pins are exact pins only, and an empty string pins nothing. validateManifest rejects it rather than silently treating it as "latest".

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/second-brain": ""
  }
}

INVALID — bad materialized shape

Invalid. Rejected. `materialized.vendored` entries must be either a plain string path (legacy) or a {path, sha256} object — a bare number is neither, so validateManifest rejects it.

{
  "version": 1,
  "registry": null,
  "target": {
    "kind": "repo",
    "id": "wrkflw"
  },
  "packs": {
    "github:baselane/second-brain": "v1.0.0"
  },
  "materialized": {
    "vendored": [
      42
    ]
  }
}