Pinned catalogues

Chimera's catalogue screens read three public repositories:

catalogue	repository	files read
connectors	brcampidelli/chimera-connectors	dist/catalog.json (generated by its CI from one YAML per connector)
skills	brcampidelli/chimera-skills	catalog/<id>.json, one per skill
plugins	brcampidelli/chimera-plugins	.claude-plugin/marketplace.json and catalog/<id>.json

Each one is read at one commit, never at a branch. A catalogue cannot change under you: a push to one of these repositories changes nothing in an installed Chimera until a release ships a new pin.

What "pinned" means

chimera/catalogs/pins.json ships inside the package. For each catalogue it records the repository, a full 40-character commit sha, and the sha256 of every file the app reads at that commit. The app:

• fetches only https://raw.githubusercontent.com/<owner>/<repo>/<sha>/<path> for a tuple the pin file names — anything else is refused before a request is made;
• hashes the bytes and refuses them if they are not the pinned sha256 — they are neither parsed nor cached;
• caps each file at 1 MiB and goes through the same bounded fetch the plugin installer uses (HTTPS, the two GitHub hosts only, a timeout, GITHUB_TOKEN when set);
• keeps verified files under CHIMERA_HOME/catalogs/cache/<owner>__<repo>/<sha>/, so a catalogue read once reads offline afterwards. With nothing cached and no network the catalogue is shown empty, with the reason.

Nothing at runtime updates a pin, and reading a catalogue installs nothing. Installing an item still goes through the plugin installer, the skill bundle path or the MCP screen, and lands switched off until you turn it on.

The desktop reads them through GET /api/catalogs/{kind} (kind = connectors, skills or plugins). Each item carries where it was read (repository, commit, file), its license and category, and whether today's Chimera could install it — with the reason when not. There is no install or download count: Chimera has no telemetry, so any such number would be invented. Stars and dates are null until they are read with the date of the reading.

Checking for newer catalogues

chimera catalog pins            # the commit each catalogue is pinned at
chimera catalog pins --check    # which repositories have commits past their pin; changes nothing

Bumping the pins (a release step)

Updating a pin is a deliberate act, done in a pull request a reviewer reads:

chimera catalog pins --check                               # what moved
python scripts/bump_catalog_pins.py                        # every catalogue at its current main
python scripts/bump_catalog_pins.py --only skills          # or one catalogue
python scripts/bump_catalog_pins.py --sha skills=<40-hex>  # or one catalogue at one commit
git diff chimera/catalogs/pins.json                        # the commits and the files that changed

The script lists the catalogue files at the chosen commit, downloads each one and records the sha256 of the exact bytes served. Read what changed in the catalogue repositories between the old and new commits before merging — the pin is the point at which the release vouches for what the screens will show. See RELEASING.md.