@hotstack/catalogue-snapshot 0.20260709.1

package/README.md

@@ -0,0 +1,70 @@
+# @hotstack/catalogue-snapshot
+
+A versioned, offline snapshot of the HotStack Catalogue federated index —
+every entry from the curated HotStack registry, the official MCP Registry,
+and the Claude Code plugins marketplace, already denylist-filtered,
+collision-reconciled, and de-duplicated by the same rules the live catalogue
+service applies. Ship the catalogue **into** your app at build time; no
+hosted service, no network at runtime.
+
+## Install
+
+```sh
+npm install --save-dev @hotstack/catalogue-snapshot
+```
+
+Generation output is data you commit, so a dev dependency is the norm.
+
+## Quickstart
+
+```ts
+import { loadSnapshot, toMarketplaceIndex } from '@hotstack/catalogue-snapshot';
+
+const snapshot = loadSnapshot();
+console.log(`${snapshot.entries.length} entries from ${snapshot.sources.length} sources`);
+
+// Pick what you bundle — tiers and scores are on every entry.
+const picked = snapshot.entries.filter(
+  (entry) => entry.tier === 'curated' || entry.sourceId === 'claude-plugins-official'
+);
+
+// Project to a Multicode MarketplaceIndex document.
+const { index, idMap, skipped } = toMarketplaceIndex(picked, { inlineIcons: true });
+```
+
+## What's in an entry
+
+- `id` — publisher-namespaced catalogue id (`railway/railway-mcp`)
+- `kind` — `inline-mcp` (config-only server), `bundle` (signed downloadable
+  plugin), or `plugin` (code-bearing marketplace reference)
+- `sourceId` / `tier` — provenance: which configured source listed it, at
+  which trust tier (`curated` > `community` > `indexed`)
+- `logoSlug` — brand logo stem under the packaged `logos/` dir (CC0
+  simple-icons set), `null` when unmatched — never a wrong logo
+- `score` — GitHub-derived ranking score persisted at build time (0 when the
+  snapshot was built without enrichment)
+- `dedupPrimary` — `false` for near-duplicate listings of a tool another
+  entry represents better; demote, don't hide
+- `native` — the normalized upstream document, verbatim
+
+## Honesty semantics
+
+- The catalogue never asserts safety. Tier and signature metadata inform your
+  own trust policy; unsigned content should route through your own consent
+  flow.
+- `toMarketplaceIndex` never mutates signed bundles — their ed25519 signature
+  covers the exact JSON value, which rides through byte-identical.
+- Entries a projection cannot express are returned in `skipped` with reasons,
+  never dropped silently.
+
+## Regenerating the data
+
+From the repo root (`hotstack-catalogue`):
+
+```sh
+npm run snapshot:build            # no GitHub enrichment; scores stay 0
+GITHUB_TOKEN=… npm run snapshot:build -- --enrich
+```
+
+The builder is deterministic apart from `generatedAt` (entries sorted by id),
+so regeneration diffs stay reviewable.