feat: add cluster collection and quality tiers to featured models

.github/workflows/ci.yml

@@ -18,5 +18,6 @@ jobs:
         run: |
           node scripts/verify.mjs
           node scripts/ollama-verify.mjs
+          node scripts/featured-verify.mjs
           node scripts/runtime-feed-verify-all.mjs
           python3 -m unittest discover -s scripts -p '*_test.py'

.github/workflows/refresh-featured.yml

@@ -0,0 +1,63 @@
+name: refresh-featured
+
+# Refreshes the curated featured models list: files, sizes, parameters, and
+# context from v1/ollama-models.json and the Hugging Face API. Which models
+# appear is decided only by scripts/featured-curation.mjs, which this job never
+# edits. It also reports possible newer versions for a maintainer to review.
+on:
+  schedule:
+    # Daily, after the Ollama refresh has had a chance to land. GitHub runs
+    # scheduled workflows on a best-effort basis; the minute does not matter.
+    - cron: "53 5 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: refresh-featured
+  cancel-in-progress: false
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # See refresh.yml: pushes made with the default token do not reset
+          # GitHub's 60-day scheduled-workflow cutoff.
+          token: ${{ secrets.REFRESH_TOKEN || github.token }}
+          fetch-depth: 0
+
+      - name: Show tool versions
+        run: node --version
+
+      - name: Test the builder
+        run: node --test scripts/featured.test.mjs
+
+      # Fails without writing when any reference cannot be confirmed, so the
+      # published file stands until a maintainer fixes the curation.
+      - name: Generate
+        run: node scripts/featured-generate.mjs
+
+      - name: Verify the artifact
+        run: node scripts/featured-verify.mjs
+
+      - name: Commit
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "nothing to publish"
+            exit 0
+          fi
+          git config user.name "model-catalog[bot]"
+          git config user.email "noreply@cloudstack.llc"
+          git add v1/featured-models.json
+          git commit -m "chore: refresh the featured models"
+          git push
+
+      # Leads only: a report failure never fails the refresh.
+      - name: Report possible newer versions
+        continue-on-error: true
+        run: node scripts/featured-report.mjs >> "$GITHUB_STEP_SUMMARY"

README.md

@@ -13,7 +13,7 @@ https://raw.githubusercontent.com/cloudstack-llc/model-catalog/main/v1/smart-rou
 | --- | --- | --- | --- |
 | `v1/prices.json` | Token pricing for hosted models | [models.dev](https://models.dev) | 6 hours |
 | `v1/ollama-models.json` | The Ollama library: models, tags, sizes, context windows | [ollama.com](https://ollama.com/library) | 12 hours |
-| `v1/featured-models.json` | Curated local models worth downloading, grouped into collections | Curated; resolved against Ollama and Hugging Face | On change |
+| `v1/featured-models.json` | Curated local models worth downloading, grouped into collections | Curated; resolved against Ollama and Hugging Face | Daily |
 | `v1/smart-route-starters.json` | Model-neutral Smart Route starters, grouped by use | Curated | On change |
 | `v2/runtime/{stable,dev}/runtime-release-feed.signed.json` | Signed Msty Nexus Runtime releases | Ollama, llama.cpp, and Msty MLX metadata | 4 hours |
 
@@ -228,8 +228,8 @@ file stands.
 `v1/featured-models.json` — the local models worth recommending to somebody who has
 just installed a runtime and does not yet know what to download.
 
-Unlike the other two files this one is curated. Which models appear is a judgement; every
-value attached to them is not. Tags, sizes, context windows and parameter counts come from
+Unlike the scraped files this one is curated. Which models appear is a judgement, and it
+lives in `scripts/featured-curation.mjs`; every value attached to them is not. Tags, sizes, context windows and parameter counts come from
 `ollama-models.json`, and repositories, GGUF file names and byte counts come from the
 Hugging Face API. A reference that cannot be confirmed fails the build rather than
 shipping — a featured row with a dead download behind it is worse than one fewer row.
@@ -271,7 +271,8 @@ model can appear in two collections without being described twice.
 | Field | Meaning |
 | --- | --- |
 | `id`, `name` | Required. Everything else is optional. |
-| `publisher`, `summary`, `parameters`, `context`, `capabilities`, `tags` | Description, for display and filtering. |
+| `publisher`, `summary`, `parameters`, `context`, `capabilities`, `tags` | Description, for display and filtering. `"coding"` in `tags` marks a model that is good at writing code. |
+| `tier` | Quality tier: `frontier`, `excellent`, `strong`, or `good`. |
 | `installs[].runtime` | `ollama`, `llamacpp`, or `mlx`. |
 | `installs[].model` | The Ollama tag. Ollama installs are addressed by it; Hugging Face installs are not. |
 | `installs[].repository`, `file`, `revision` | The Hugging Face locator. `revision` defaults to `main`. |
@@ -292,9 +293,50 @@ model is multimodal, so those entries declare `vision`.
 download is a flow this format cannot describe. A repository publishing only shards gets
 no `llamacpp` entry.
 
+**`tier` is a curated quality rating.** Msty Nexus Cluster Advisor ranks by it. It rates
+general chat and reasoning quality against the open models available at the time:
+
+| Tier | Meaning |
+| --- | --- |
+| `frontier` | The best open models, close to hosted frontier models. |
+| `excellent` | One step below: the previous generation's flagships and the top coding models. |
+| `strong` | Capable mid-size models, roughly 20B to 130B. |
+| `good` | Small models, and models with one narrow job (OCR, embeddings). |
+
+Tiers are relative, so review them when a new generation of models is released. A client
+that finds no `tier` estimates one from the model's size and says so. The field is
+additive: older Nexus builds ignore it, so `schema_version` stays 1.
+
+**The `cluster` collection is a contract.** Cluster Advisor reads it by id. It holds MLX
+models too large for one Mac, from model families the cluster runtime can split across
+Macs.
+
+**An Ollama size published as a range uses the upper end.** Ollama shows a range, such as
+`6.6GB - 7.6GB`, for a tag that resolves to different files per platform. `size_bytes` is
+what the download may cost, so a fit check that overestimates is the safer error.
+
 ## Refresh
 
-Regenerated by hand rather than on a schedule, because the curation is the point. The
-builder lives in the Msty Nexus repository at `scripts/build-featured-models.py`; it reads
-the committed `ollama-models.json` from this repository and the Hugging Face API, and
-fails on any reference it cannot confirm.
+A daily job (`refresh-featured.yml`) rebuilds the file from the curation, the committed
+`ollama-models.json`, and the Hugging Face API. It refreshes files, sizes, parameters,
+context and popularity, and never adds or drops a model: only a reviewed edit of
+`scripts/featured-curation.mjs` does that.
+
+The job commits only when something other than `generated_at` or popularity changed;
+Msty Nexus reads popularity live and treats the published numbers as a fallback. Any
+reference it cannot confirm, or any Ollama size it cannot read, fails the run without
+writing, so the published file stands until a maintainer fixes the curation.
+
+After each run, `featured-report.mjs` lists mlx-community repositories that may be newer
+versions of featured models (by each model's `watch` term) in the job summary. These are
+leads for a maintainer, not changes.
+
+To change the list, edit `scripts/featured-curation.mjs`, then rebuild and commit both:
+
+```bash
+node scripts/featured-generate.mjs   # fetch and rewrite v1/featured-models.json
+node scripts/featured-verify.mjs     # offline: shape, sizes, and match with the curation
+node --test scripts/featured.test.mjs
+```
+
+CI runs the verifier, so a curation edit without a rebuild fails the pull request.

package.json

@@ -5,8 +5,9 @@
   "license": "MIT",
   "scripts": {
     "test": "node --test scripts/*.test.mjs",
-    "verify": "node scripts/verify.mjs && node scripts/ollama-verify.mjs && node scripts/smart-route-starters-verify.mjs && node scripts/runtime-feed-verify-all.mjs",
+    "verify": "node scripts/verify.mjs && node scripts/ollama-verify.mjs && node scripts/featured-verify.mjs && node scripts/smart-route-starters-verify.mjs && node scripts/runtime-feed-verify-all.mjs",
     "generate": "node scripts/generate.mjs",
-    "generate:ollama": "node scripts/ollama-generate.mjs"
+    "generate:ollama": "node scripts/ollama-generate.mjs",
+    "generate:featured": "node scripts/featured-generate.mjs"
   }
 }