---
name: refresh-catalog
description: Re-fetches metadata for catalog sources (`skill-sources.json`) and updates fields like `last_updated`, star counts, latest commit sha, and license. Use periodically (monthly) to keep the catalog accurate. Does not change source IDs or tier classifications.
when_to_use: |
  Manual / scheduled. Invocable directly: "/maxvision-orchestration:refresh-catalog",
  "atualize o catálogo de fontes do plugin",
  "refresh sources" (when triaging stale entries).
disable-model-invocation: true
allowed-tools: Read Bash(jq *) Bash(gh api *) Bash(date *) Bash(cat *) Edit
---

# Refresh catalog

Re-fetches live metadata for entries in `skills/discover-skill/references/skill-sources.json` and rewrites the file with refreshed fields.

## Workflow

### 1. Read current catalog

```bash
CATALOG=${CLAUDE_SKILL_DIR}/../discover-skill/references/skill-sources.json
```

### 2. For each `sources[*]` entry

Extract `version_check.endpoint` and call:

```bash
gh api <endpoint> --jq .sha
gh api repos/<owner>/<repo> --jq '{stars: .stargazers_count, license: .license.spdx_id, default_branch: .default_branch, archived: .archived}'
```

Update fields:

- `latest_commit_sha`: refreshed sha
- `stars`: refreshed star count
- `license`: refreshed SPDX (warn if changed)
- `archived`: if `true`, mark entry with warning `archived_upstream: true`

### 3. For each `discovery_aggregators[*]` entry

If `type: github_repo`, refresh stars and last commit. Otherwise just verify the URL returns 200 (best-effort fetch).

### 4. Bump catalog metadata

```json
{
  "$schema_version": "1.0.0",
  "catalog_version": "0.1.X",   // bump patch
  "last_updated": "<today ISO>"
}
```

### 5. Diff and confirm

Show the diff (added/removed/changed entries) and ask for `sim` before writing.

### 6. Write back

Use Edit to apply the diff to `skill-sources.json`. Never replace whole file content unless absolutely necessary — preserve user-added entries (anything outside the canonical IDs).

## Guardrails

- **Never remove a tier_4 warning** even if upstream looks fine — manual review required.
- **Never auto-promote a tier_3 entry to tier_2.** Tier classification is curatorial, not automated.
- **Never auto-add new sources** discovered on aggregators. This skill only refreshes what's already in the catalog.
- **Always show diff before write.** Even if all changes look minor (sha bumps), the user must approve.
- **Skip authenticated-required endpoints.** If `gh api` returns 401 for a private repo, skip and warn — the catalog should only contain public sources.

## Output

```
Catalog refresh complete:
  Sources checked:    14
  Entries updated:    9
  New warnings:       1 (alirezarezvani/claude-skills star count dropped 5%)
  Archived upstream:  0
  Diff written to:    skill-sources.json
  Catalog version:    0.1.0 → 0.1.1
```