should --checkpoint carry its ecosystem? (design question split out of #345)

[ZacxDev]

Split out of #345, which was fixed docs-only: the --checkpoint headline example
was removed from civitai generate --help and replaced with a placeholder example that
spells the coupling out and hands the pairing to the user. That closes the copy-paste
trap. It does not answer the design question underneath it, which is this:

The question

Should --checkpoint carry an ecosystem with it — and if not, should the CLI be able
to tell the user that the pair it is about to charge for is incoherent?

Today --checkpoint selects a model version and nothing else. The settings the server
generates with — engine, steps, cfg scale, sampler — follow the ecosystem
(--ecosystem, or the server's default when none is passed), not the checkpoint. The
observed result (#345, one paid run, 2026-08-10): an SD 1.5 checkpoint
(urn:air:sd1:checkpoint:civitai:4384@128713) submitted under ecosystem: zImage,
engine: sdcpp, steps: 9, cfgScale: 1 — charged 8 Buzz, Status: failed, 0
deliverable outputs. Nothing refused it: not the CLI, not the estimator, not the
generator.

There is also no --steps / --cfg-scale to correct the defaults by hand, deliberately
— see #329 and item 14
(steps: 0 is accepted at a 0.333 cost factor: billed, wrong output). So today the
only correction path is --print-input → edit → --input.

Why it is a design question and not a defect fix

Every obvious "fix" is a vendoring decision, and
item 13 is
explicit that the generation path mirrors nothing: which checkpoint belongs to which
ecosystem is server state with a shelf life, and a stale local copy starts refusing
valid new inputs, which is worse than the gap it closes. Candidate directions, none
chosen:

1. --checkpoint implies an ecosystem. Needs a mapping from version id → ecosystem.
   A live lookup is not a mirror (item 13 already permits ResolveModelVersion on that
   grounds) — but the existing GET /api/v1/model-versions/{id} returns baseModel, not
   an ecosystem key, so this needs the platform to expose the mapping, or a translation
   table, which is a mirror.
2. Refuse --checkpoint without --ecosystem. Cheap, local, mirrors nothing — the
   same shape as the existing --image requires --ecosystem refusal. Costs every
   caller whose checkpoint does match the default an extra flag, and does not stop a
   user from naming the wrong ecosystem.
3. Warn only, fail-soft, when a checkpoint's baseModel and the named ecosystem look
   unrelated. Needs the same mapping as (1), but a stale one only produces a needless
   note (the serverQuantityClamp shape).
4. Do nothing beyond the docs fix, and let the server own it — arguably the item-13
   answer.

This also sharpens #279 / Resources ready

--dry-run printed Resources ready: true for this job. That is consistent with what
the flag means (every job's queuePosition.support is available) and it is why item
28(a) already refuses to call it "generatable" — but #345 is now a second measured case,
alongside #279's 8 submits across 3 checkpoints, of ready: true preceding zero outputs.
Worth asking as part of this: is there any pre-submit signal that separates a
coherent job from an incoherent one, or is ready structurally incapable of it and the
label the only lever?

Scope

Design decision + product call, not an agent's to make. Nothing here should be
implemented before the direction is chosen — in particular do not add a local
ecosystem/checkpoint table on the strength of this issue.

Related: #345 (the docs fix that shipped), #329 (why there is no --steps/--cfg-scale
to correct it with), #279 (Resources ready reporting ready for jobs that produced
nothing).