# Static Artifact API Contract

Contract version: `static-artifact-api-v1`

This document defines the public JSON artifact surface for registry consumers.
The artifacts are generated by `claude-skill-registry-core`; generated files in
the merged `claude-skill-registry` repository are publish outputs, not source
files to patch by hand.

## Locations

- Core Pages base URL: `https://majiayu000.github.io/claude-skill-registry-core/`
- Merged artifact raw base URL:
  `https://raw.githubusercontent.com/majiayu000/claude-skill-registry/main/`

Core Pages is optimized for the web app and public read APIs. The merged
artifact is optimized for bulk registry compatibility and raw archive browsing.

## Public Entry Points

| Path | Location | Contract |
| --- | --- | --- |
| `search-index-lite.json` | Core Pages | Startup catalog index with deduped summaries and quality/security signals. |
| `search-index.json` | Core Pages | Compatibility pointer for the full search payload. |
| `search-index-manifest.json` | Core Pages | Full search shard manifest. |
| `search-shards/part-000.json` | Core Pages | Full search shard part pattern. |
| `featured.json` | Core Pages | Featured skills for the web app. |
| `plugins.json` | Core Pages | Plugin catalog. |
| `stats.json` | Core Pages | Generated counts, shard sizes, and summary statistics. |
| `quality-index.json` | Core Pages | Compatibility pointer for quality records. |
| `quality-index-manifest.json` | Core Pages | Quality shard manifest. |
| `quality-shards/part-000.json` | Core Pages | Quality shard part pattern. |
| `security-index.json` | Core Pages | Compatibility pointer for security records. |
| `security-index-manifest.json` | Core Pages | Security shard manifest. |
| `security-shards/part-000.json` | Core Pages | Security shard part pattern. |
| `ranking-index.json` | Core Pages | Compatibility pointer for ranking records. |
| `ranking-index-manifest.json` | Core Pages | Ranking shard manifest. |
| `ranking-shards/part-000.json` | Core Pages | Ranking shard part pattern. |
| `categories/index.json` | Core Pages | Category manifest index. |
| `categories/<category>.json` | Core Pages | Legacy category compatibility pointer. |
| `categories/<category>/manifest.json` | Core Pages | Category part manifest. |
| `categories/<category>/part-000.json` | Core Pages | Category part pattern. |
| `registry_summary.json` | Core raw | Lightweight source summary and counts. |
| `registry.json` | Merged raw | Compatibility pointer for the full registry payload. |
| `registry-manifest.json` | Merged raw | Registry shard manifest. |
| `registry-shards/00.json` | Merged raw | Registry shard pattern, keyed by two-character shard id. |
| `provenance/merge-source.json` | Merged raw | Source refs used for the merged publish artifact. |

Any new public JSON artifact must be added to this table in the same PR that
adds or changes the generated artifact.

## Compatibility Pointers

Large historical full-payload files are now small pointer files. A pointer
object must include:

- `deprecated_full_payload: true`
- `message`
- `manifest` when the replacement manifest is published next to the pointer
- `compat_since`
- `replacement`

Pointer files must not contain a full `skills` or `records` payload. Consumers
must follow `manifest` or `replacement` instead of assuming the compatibility
file contains all records.

Current pointer entry points:

- `search-index.json`
- `quality-index.json`
- `security-index.json`
- `ranking-index.json`
- `categories/<category>.json`
- `registry.json`

## Manifests

Manifest objects must include a `schema_version`, an `updated_at` or
`generated_at` timestamp, a record count, and shard or part references.

Search, quality, security, and ranking manifests use shard entries with:

- `path`
- `gzip_path` when a gzip artifact is written
- `count`
- `bytes`
- `gzip_bytes` when a gzip artifact is written
- `sha256`

Category manifests use part entries with:

- `path`
- `gzip_path`
- `count`
- `bytes`
- `gzip_bytes`
- `sha256`

Registry manifests use shard entries with:

- `id`
- `path`
- `gzip_path`
- `count`
- `bytes`
- `gzip_bytes`
- `sha256`

Consumers should validate `sha256` when they need reproducible syncs. Consumers
should prefer `gzip_path` when bandwidth matters and plain `path` when a simpler
client is more important.

## Shard Payloads

Shard payloads must include:

- `schema_version`
- an identity field for the shard or part
- `count`
- a bounded payload array

Search shard payload arrays are `skills`. Signal shard payload arrays are
`records`. Category part payload arrays are `skills`. Registry shard payload
arrays are `skills`.

Security signal records expose `security_status` plus `security_decision` when
scanner evidence was available. The decision object contains the scanner name,
scanner version, ruleset hash, source content hash, scan timestamp, and a
deterministic decision id. Missing security decisions must be treated as
unknown evidence, not clean evidence.

Shard ordering is deterministic for a given generator version, but consumers
must not treat ordering as a stable API unless the manifest explicitly documents
the ordering strategy.

## Deprecation Rules

Removing or changing a public entry point is a breaking change. A breaking
change must either:

- add a new path and leave the old path as a compatibility pointer, or
- update this contract with a migration note and a compatibility window.

Compatibility pointer fields:

- `compat_since`: first date or version when the pointer behavior was present
- `compat_until`: optional planned end of compatibility
- `replacement`: path or path pattern consumers should use

If `compat_until` is absent, consumers may assume no removal date has been
announced yet.

## Consumer Guidance

For startup search, use `search-index-lite.json` first. For exhaustive search,
follow `search-index.json` to `search-index-manifest.json`, then load the listed
search shards.

For category browsing, load `categories/index.json`, then follow the selected
category manifest and parts. Do not fetch every category part on startup.

For trust and ranking overlays, load the pointer, then the corresponding
manifest and shards. Treat missing signal records as unknown, not clean.

For full registry sync, use the merged artifact `registry-manifest.json` and
`registry-shards/*.json`. Use `registry.json` only as a compatibility pointer.