# ktg-plugin-marketplace (catalog)

Catalog repository for the ktg-plugin-marketplace. After the polyrepo migration this repo hosts only
the marketplace manifest and the catalog-level docs; every plugin and the shared design-system live in
their own Forgejo repositories under `https://git.fromaitochitta.com/open/`.

## What lives here

- `.claude-plugin/marketplace.json` — the marketplace manifest (plugin entries point at external repos)
- `README.md` — the landing/catalog page
- `CONVENTIONS.md` — marketplace-wide conventions inherited by every plugin repo
- `GOVERNANCE.md` — governance + fork-and-own model
- `.mailmap`, `.gitleaks.toml`, `.gitleaksignore` — shared git-hygiene baselines

## Catalog maintenance

- Marketplace conventions: see CONVENTIONS.md.
- Adding/updating a plugin entry: edit `.claude-plugin/marketplace.json` (external `source: "url"` with
  a pinned `ref`) and re-state the plugin in README.md with its verified version.
- Plugin source, issues, and releases live in each plugin's own repository — not here.
- **Releasing a plugin (canonical path — `scripts/release-plugin.mjs`):** since the polyrepo split,
  a release is a TWO-repo act — tag the plugin repo AND bump the catalog `ref`. Forgetting the second
  step strands users on the old version (the exact drift this helper exists to prevent). Run
  `node scripts/release-plugin.mjs <plugin> [--version X.Y.Z]` — dry-run by default; it REFUSES unless
  `plugin.json` == README badge == the target version AND the `vX.Y.Z` tag exists, then prints the
  planned bump. Apply with `--write [--commit] [--push]`; `--create-tag` mints+pushes a missing plugin
  tag first. On `--write` it bumps the catalog `ref` AND the catalog README's per-plugin `` `vX.Y.Z` ``
  label together (and `git add`s both on `--commit`). Because it only moves both to a verified, tagged,
  consistent version, `check-versions.mjs` is green by construction. Never hand-edit a `ref` or a
  README label for a release — use this. Pure planner + label reconciler covered by
  `scripts/release-plugin.test.mjs`.
- **Version-consistency gate:** run `node scripts/check-versions.mjs` before committing any `ref`
  change. For each plugin it checks (against the sibling repo) that the catalog `ref` resolves to a
  real git tag (ERROR if dangling — breaks install), that `plugin.json` version == README
  version-badge (ERROR), that the catalog README's per-plugin `` `vX.Y.Z` `` label == the catalog
  `ref` (ERROR — the human-facing doc must not misstate the installed version), and that the catalog
  `ref` matches `plugin.json` version (WARN — catalog lags or an unreleased bump). Exit 1 on any
  ERROR; `--strict` also fails on WARN. Pure-function core covered by
  `scripts/check-versions.test.mjs` (`node --test scripts/check-versions.test.mjs`).