/add-ecosystem

name: add-ecosystem
description: Add a new ecosystem and base model to basemodel.constants.ts. Use when onboarding a new model family from providers like Baidu, ByteDance, Google, etc. Handles ECO constants, BM constants, ecosystem record, family (creates new if needed), license (creates new if needed), and base model record. Optionally triggers add-generation-support at the end.

Add Ecosystem

Adds a new ecosystem and base model entry to [basemodel.constants.ts](src/shared/constants/basemodel.constants.ts). Everything else downstream (generation support, graph, handler, workflow wiring) is handled by the **add-generation-support** skill.

When to use

Use when a new model provider or variant is being added to Civitai — e.g., new provider (Baidu's Ernie), new architecture (Flux's Kontext), or a variant of an existing family whose resources aren't interchangeable with its siblings.

This skill has two modes, and you should only be here if one of them applies:

• **New ecosystem**: a new line, or a checkpoint that existing resources in its ecosystem won't run on (for example `LTXV` → `LTXV2`).
• **Base model only**: a hosted-weights checkpoint that existing resources in its ecosystem *do* run on (for example `SDXL 0.9` → `SDXL 1.0`). Skip the `ECO`, family and ecosystem steps. Add only the `BM` constant and the `baseModelRecords` entry, pointing at the existing ecosystem. Also used for the API-only exception below.

**A new release of an API-only model that already has an ecosystem usually needs neither.** It becomes a new model version under the existing base model, with no constants change. Stop and say so — unless the existing base model is hosted weights whose licence, restrictions or LoRAs must not apply to the API release; then use **Base model only** with `hidden: true` (`Ideogram 4.5` beside `Ideogram 4.0`). `onboard-generator-model` Phase 0 has the full decision.

The test: does this need its own ecosystem?

Answer this **before** picking IDs. The ecosystem is the **compatibility** key, not a UI grouping and not a media label:

> **A variant needs its own ecosystem when a LoRA (or other addon) trained for it would NOT work on every model carrying the sibling's baseModel.**

That is the whole test. [getGenerationSupport](src/shared/constants/basemodel.constants.ts) returns `'full'` unconditionally for same-ecosystem pairs — there is no media dimension and no per-model nuance in it. Putting two things in one ecosystem asserts "resources cross freely between these," so only do it when that's true.

**Architecture is not weights.** The most common way to get this wrong is reading a vendor's "one unified model" marketing as "one checkpoint." Providers routinely ship a shared architecture as separate weight releases, and a LoRA is trained against *weights*. Check what actually ships — distinct releases, distinct sizes, distinct endpoints — not what the announcement calls the family.

**Do not split on output media.** "Image vs video" is not the question; "do resources cross" is. If one checkpoint does both, that's one ecosystem with a `type: ['image', 'video']` base model (Grok). If they're separate checkpoints that happen to differ in output media, that's two ecosystems (Wan Image 2.7 / Wan Video 2.7 — note there are deliberately no `crossEcosystemRules` between them).

**When genuinely unsure, split.** The two mistakes are not symmetric:

| Choice | If wrong | Cost to fix | | --- | --- | --- | | Split, but they're compatible | Resources don't cross | Add `crossEcosystemRules` entries — additive, that's what the mechanism is for | | Merged, but they're incompatible | Incompatible resources offered as compatible | Change the ecosystem key → **changes the AIR URN namespace on already-published resources** |

Splitting is reversible; merging is not. This is doubly true when you're creating the first ecosystem for an API-only line: no community resources exist yet, so the split costs nothing today and keeps the option open. This doesn't apply to a later release in that line, which gets no new records at all (see "When to use").

Media-specific *labelling* for creators is a `BaseModelRecord` concern, not an ecosystem one — several base models can share one ecosystem, each with its own `name` and `type`.

Workflow (interactive after research)

Do research first, then ask the user only for what can't be inferred.

1. Gather model info

Ask the user for the model name and a reference link (HuggingFace page, official repo, announcement). Then research before asking anything else:

• **WebFetch** the reference link to extract:
• Provider/company (drives family selection)
• License (match against existing `licenses` array or flag as new)
• Model type (`image` vs `video` — sometimes both)
• **How it actually ships** — one checkpoint or several separate weight releases? This decides the ecosystem split (see "The test" above), so read for distinct releases/sizes/endpoints rather than trusting the family name.
• Short description for the base model record
• Search the codebase for prior patterns: `Grep` for the provider name to see if a family already exists

2. Pick IDs

Read the current state of [basemodel.constants.ts](src/shared/constants/basemodel.constants.ts) to determine the next available IDs. Use Read with offsets — don't load the whole file.

• **`ECO.<Name>`**: next available ecosystem ID. Groupings in `ECO`:
• Image models: 1-50 range (first come, first served; find next gap)
• Video models: 47-66 range
• Utility: 66+
• Child ecosystems (`parentEcosystemId` set): 100+ for SDXL children, 200+ for AuraFlow children
• Pick the next unused number within the appropriate block
• **`BM.<Name>`**: next available base model ID. Read the `BM` constant block, find the next unused number.
• **Family ID**: try to match an existing family in `ecosystemFamilies`. If none match, propose creating a new one (confirm with user).
• **License ID**: try to match