/socialforge:model-check — which model to call, decided today

Script location. If your host does not set ${CLAUDE_PLUGIN_ROOT}, the scripts are in this plugin's scripts/ folder, next to skills/. Run them with Python 3.10 or newer: python, or python3 where python is not found (macOS, many Linux systems).

SocialForge does not know which model to use. That is deliberate.

A model id written into a plugin is a claim about the day it was written, and this plugin gets run long after that day. Six ids used to sit on the execution path. One video fallback stayed pinned to a superseded generation for about six months, and nothing in the system could say so — which matters because a retired id does not degrade gracefully. It fails at the exact moment the two providers ahead of it have already failed and the fallback is all that is left.

So the code asks for a kind of model. You find out what currently satisfies it.

The rule

Never supply a model id from memory. Not from this file, not from a recipe, not from what a model was called last time you looked. If model_book.py says unknown or stale, go and read the provider's catalogue.

What the code asks for

python "${CLAUDE_PLUGIN_ROOT}/scripts/model_book.py" --action kinds

Capabilities, not products — video.image-to-video, not a version number. A kind outlives every model that has ever satisfied it, which is the entire point.

Finding the current best

1. See where to look, and what is odd about each provider:

python "${CLAUDE_PLUGIN_ROOT}/scripts/model_book.py" --action discovery

Two things it will tell you that save time: Higgsfield puts the model in the URL path (so a hardcoded path is a hardcoded model), and Kie AI blocks automated fetches — HTTP 403, measured. Do not report that as "no model exists"; ask the user.

2. Read the provider's model list with your own web tools. This is a plugin — there is no crawler and no server, which is why the answer is as fresh as your last look rather than as old as the last release.
3. Judge what is actually best for the kind, not what is newest or loudest. A reference-heavy brief and a prompt-driven cinematic brief are different jobs, and the model that wins one often loses the other. Check what the brief needs: start-frame support, duration ceiling, reference-image count, whether audio is required.
4. Record it, with the URL you read:

python "${CLAUDE_PLUGIN_ROOT}/scripts/model_book.py" --action record \
  --kind video.image-to-video --provider wavespeed \
  --model-id "<exact id from the catalogue>" \
  --source https://wavespeed.ai/models \
  --max-duration-s 15 --notes "start+end frame, optional audio"

A record without a source URL is rejected — a model id with no provenance is the same guess this system exists to replace.

5. Then price it. A newer model is not automatically the right call: run /socialforge:price-check and compare before committing a month's run to it.

Checking before a production month

python "${CLAUDE_PLUGIN_ROOT}/scripts/model_book.py" --action staleness

Reports what has gone stale (older than 7 days) and, more usefully, which kinds have no model at all. Both need a look before a batch run.

Seven days, rather than the price book's 24 hours, because catalogues move in releases while prices move without announcement.

The ladder the code climbs

1. A live discovery you recorded recently → used.
2. The shipped registry alias → used, but always with a warning naming its age. This rung exists so a first run works before anything is discovered, not so anyone can rely on it.
3. Nothing → the generation refuses and moves on only to a provider the user was quoted for, rather than calling an id that may have been retired.

If you see the rung-2 warning during a real run, that is the signal to do a discovery pass. It is not an error, but it means the plugin is answering from a file rather than from the world.

What this skill will not do

• Supply a model id from memory, from a recipe file, or from this document
• Record a model without the URL it was read from
• Treat "newest" as "best" without checking the brief's actual requirements
• Report a blocked fetch as an absence of models
• Let a generation proceed on an unresolved model