/add-trainer-model

name: add-trainer-model
description: Add a new trainable base model to BOTH trainers end-to-end — the in-app trainer (main Next.js app, src/) and the Training Studio (apps/training-studio). Orchestrates add-ecosystem (if the base model is missing) and add-training-support (main-app wiring), then mirrors the model into the Training Studio catalog, which nothing else covers. AI-Toolkit only (Kohya is discontinued). Use when onboarding a new model family for training, or a new version of one — e.g. ZImage, MiniMax H3, a new Flux/Wan variant. Always checks whether @civitai/client ships the ecosystem's training input type first.

Add a Trainer Model

There are **two** trainers, and a new trainable model has to land in both or it will only appear in one:

1. **In-app trainer** — the "Train a LoRA" flow in the main Next.js app (`src/components/Training/**`, `src/utils/training.ts`, `src/server/...`). Kohya + AI-Toolkit. New models are gated behind a per-model **Flipt flag** (mod-only until launch). 2. **Training Studio** — the SvelteKit replacement at `apps/training-studio`. **AI-Toolkit only.** Its model catalog is a **vendored mirror** of the in-app trainer's list, and it has its own per-model gate: a `ModelCard.flagKey` (Flipt, fail-closed) hides a new model from everyone but the segmented cohort until launch — the mirror of the main app's `<name>Training` flag. Whichever host mounts the Studio resolves it: the standalone shell's server, or the main app for the `/training-studio` embed (through `studioModelFlagFeatures`). A card with no `flagKey` is visible to every signed-in user immediately.

This skill is the umbrella that keeps the two in step. It owns the **decision layer** (the three facts below), delegates the pieces that already have skills, and owns the Training Studio mirror step, which no other skill covers.

> **AI-Toolkit only.** Kohya has been discontinued; every new model trains via AI-Toolkit. The one > exception you may meet is a Flux.2-style model that has no AI-Toolkit ecosystem and trains through > the older `imageResourceTraining` path with an explicit base AIR and its own `engine` > (`flux2-dev`, `flux-dev-fast`, `musubi`). It takes **no** AI-Toolkit hyperparameters. Treat it as the > rare case and confirm with the user before going down it.

The three facts to establish first (Step 0)

Ask the user or infer from the model card / an orchestrator sample. Do **not** touch any file until all three are answered — each one changes what you do:

1. **Does the base model / ecosystem already exist?**

   grep -niE "<name>" packages/civitai-shared/src/basemodel.constants.ts

The definitions live in the `@civitai/shared` package — `src/shared/constants/basemodel.constants.ts` is a 4-line re-export shim (grepping it finds nothing, for every model). Look for `ECO.<Name>`, an `EcosystemRecord`, and a `BaseModelRecord`. **If any are missing → run the `add-ecosystem` skill first** (it creates the ECO/BM constants, ecosystem, family, license and base model). This skill assumes they exist.

2. **Is it the same ecosystem as a model that is already trainable, or a genuinely new one?**

• **New version of an existing trainable ecosystem** (e.g. another Wan version, another SDXL

fine-tune) → you are adding a `trainingModelInfo` **key** to an ecosystem already wired up. Most of the main-app plumbing (schema enum aggregate, orchestrator union branch, feature flag, `baseTypeToEcosystem`, `isAiToolkitSupported`) is already in place; you mainly add the new key + its UI defaults, and a new **version** to the existing Training Studio card.

• **New ecosystem** → the full `add-training-support` file list applies, and the Training Studio gets

a **new card**. Confirm the exact orchestrator `ecosystem` literal and whether the SDK type carries a `modelVariant` (Flux.1 `dev|schnell`, Wan `2.1|2.2`, Flux.2 Klein `4b|9b`) — this disambiguates "new version" from "new ecosystem".

3. **Does `@civitai/client` ship the ecosystem's training input type?** The orchestrator API depends on the SDK, so submission validation and the typed dispatch need it.

   grep -niE "<Name>AiToolkitTrainingInput|ecosystem: '<name>'" \
     node_modules/@civitai/client/dist/generated/types.gen.d.ts

• **Present** → note the exact `ecosystem` literal, whether `modelVariant` is required, any fixed

fields (e.g. Boogu `batchSize` fixed at 1), and the server-computed `readonly` outputs (never send those).

• **Absent** → check `npm view @civitai/client versions --json | tail` and bump with

`pnpm add @civitai/client@<v>`. The current pin is in `package.json` (`@civitai/client`). If the type is still absent after bumping, the AI-Toolkit dispatch casts `ecosystem as any` so it works untyped — but say so to the user and prefer a typed SDK. **The `@civitai/client` bump, when needed, is the answer to the brief's "does the client need updating?" — surface it explicitly.**

Step 1 — Confirm the plan with the user

State the whole plan back before editing, across both trainers:

Add trainer model: <Name>
  Base model exists in basemodel.constants.ts:  yes | NO → run add-ecosystem first
  Relationship:  new ecosystem | new version of <existing ecosystem>
  @civitai/client:  ships <Name>AiToolkitTrainingInput | needs bump to <v> | untyped (cast)
  Engine:  ai-toolkit  (or imageResourceTraining/<engine> for a Flux.2-style model)
  ecosystem literal: '<eco>'   modelVariant: <none | enum>
  Media: image | video | audio
  baseType: '<baseType>'   trainingModelInfo key: '<key>'
  Defaults: steps <n>, unetLR <n>, dim/alpha <n>/<n>, scheduler <x>, batch <n> (max <n>), res <n>
  AIR: <placeholder HF urn | civitai urn>
  Main-app Flipt flag: <name>Training / <name>-training  (mod-only)
  Training Studio: new card | new version on the <family> card
    flagKey: '<name>-training' (gate a new mod