feat: add a first-party engine and model-pack catalog

CONTEXT.md

@@ -1,6 +1,6 @@
 # OpenLoop Context
 
-OpenLoop is a local-first music generation tool for Apple Silicon, powered by a local ACE-Step backend. It has two interfaces — a desktop GUI and a command-line CLI — that share all state: settings, history, models, and the backend process.
+OpenLoop is a local-first music generation tool for Apple Silicon. ACE-Step 1.5 is the bound Engine today; additional Engines and Model Packs are registered in a first-party catalog so they can be downloaded and switched without rewriting Settings. It has two interfaces — a desktop GUI and a command-line CLI — that share all state: settings, history, models, and the backend process.
 
 ## Language
 
@@ -27,8 +27,20 @@ _Avoid_: History, Generation Record
 A configuration option intended for users who deliberately open advanced or diagnostic controls.
 _Avoid_: Primary workflow, beginner setting
 
+**Engine**:
+A generation family with its own Local Backend contract, capability schema, and Model Packs.
+_Avoid_: Model, Model Pack, Model Slot
+
+**Model Pack**:
+A downloadable (or announced) weight set owned by one Engine. Users install and delete Model Packs, not Engines.
+_Avoid_: Engine, Model Slot, Model Variant
+
+**Model Slot**:
+A selectable run configuration that points at one Model Pack. One Model Pack may back several Model Slots.
+_Avoid_: Engine, Model Pack, Model Variant
+
 **Local Backend**:
-The ACE-Step HTTP process managed by OpenLoop on the user's machine.
+The on-device HTTP process for the active Engine. ACE-Step is the only bound Local Backend in the current release.
 
 **Model Bootstrap**:
 The local readiness path that decides whether generation can run.
@@ -37,7 +49,7 @@ The local readiness path that decides whether generation can run.
 The OpenLoop-managed filesystem layout required by the Local Backend.
 
 **Settings**:
-Persisted local configuration for model selection, runtime directories, backend startup, output defaults, language, and first-run state.
+Persisted local configuration for Engine and Model Slot selection, runtime directories, backend startup, output defaults, language, and first-run state.
 
 ## Relationships
 
@@ -60,11 +72,14 @@ Persisted local configuration for model selection, runtime directories, backend
 - Missing-file items can be cleared by deleting their **Generation Record** when no **Output File** remains.
 - **Backend Logs** are diagnostic artifacts with automatic retention, not user-managed history.
 - **Model Bootstrap** represents whether local generation is ready, not only whether a model is downloading.
-- **Model Bootstrap** includes the selected model, model files, **Runtime Layout**, and **Local Backend** health.
+- **Model Bootstrap** includes the selected **Model Slot**, its **Model Pack**, **Runtime Layout**, and **Local Backend** health.
 - **Runtime Layout** may repair OpenLoop-managed links, but must not silently reorganize unknown user-owned files.
-- **Settings** that affect **Local Backend** startup are `backendPort`, `modelDirectory`, `backendWorkingDirectory`, `logDirectory`, and `modelVariant`.
+- **Settings** that affect **Local Backend** startup are `backendPort`, `modelDirectory`, `backendWorkingDirectory`, `logDirectory`, `modelVariant`, and `selectedModelId`.
 - Backend-impacting **Settings** changes should tell users they affect the next **Local Backend** start; v1 does not automatically restart the backend.
 - `modelDirectory` means OpenLoop-managed model storage, not an arbitrary ACE-Step project directory.
+- The first-party catalog is the only place new **Engines**, **Model Packs**, and **Model Slots** are registered. Commands, the CLI, and the Settings UI must not hard-code family names when listing or switching.
+- An **Engine** without a bound **Local Backend** may appear in the catalog so a future pack (for example MiniMax Music 3 Turbo) can attach later. It must not run a **Generation Task**.
+- `modelVariant` is the ACE-Step **Model Slot** alias (`lite` / `turbo` / `pro`). `selectedModelId` is the canonical **Model Slot** id (`ace-step/turbo`, `minimax-music3/turbo`). When both are set, `selectedModelId` wins.
 - OpenLoop uses its bundled `uv` sidecar for the **Local Backend**; legacy external backend command settings are pruned, not migrated.
 - User-facing screens should present simple **Generation Task**, **History**, and **Settings** language; implementation details belong in **Advanced Settings** or diagnostics.
 - **Advanced Settings** are opt-in; beginner workflows should work without understanding **Runtime Layout**, sidecars, IPC commands, or backend internals.

docs/agents/domain.md

@@ -25,6 +25,11 @@ This is a single-context repo:
 └── src/
 ```
 
+New **Engines**, **Model Packs**, and **Model Slots** are registered in
+`src-tauri/src/services/model_catalog/` (Rust source of truth) and mirrored in
+`src/app/lib/model-catalog.ts`. Do not hard-code a new family in commands, the
+CLI router, or Settings when listing or switching.
+
 ## Use the glossary's vocabulary
 
 When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.

docs/cli.md

@@ -80,17 +80,19 @@ openloop pull pro
 
 ### `openloop models`
 
-Manage model variants.
+List the first-party Engine / Model Pack catalog, and manage installable ACE-Step packs.
 
 ```bash
-openloop models                           # list models (default)
-openloop models download turbo            # download a variant
+openloop models                           # list engines, slots, and announced packs
+openloop models download turbo            # download an ACE-Step variant
 openloop models delete turbo              # delete a downloaded variant
 openloop models cancel turbo              # cancel an ongoing download
 openloop models clear-partial turbo       # remove partial download artifacts
 openloop models delete-all                # delete all downloaded models
 ```
 
+Announced families (for example `minimax-music3/turbo`) appear in the list so a future pack can keep a stable id. They are not downloadable until an Engine adapter is bound.
+
 | Flag     | Description                    |
 | -------- | ------------------------------ |
 | `--json` | JSON output                    |

src-tauri/src/cli/models.rs

@@ -9,6 +9,7 @@ use crate::{
     models::{errors::AppResult, settings::ModelVariant},
     services::{
         model_bootstrap::{checkpoints_dir_for, descriptor_for},
+        model_catalog::{self, PackInstallPolicy},
         model_manager::{read_manifest, ModelManager, ACE_MODEL_DESCRIPTORS},
     },
 };
@@ -63,32 +64,58 @@ fn execute_list(state: &AppState, json: bool) -> AppResult<()> {
         }
     }
 
+    let active_slot = model_catalog::selected_slot_id(&settings);
+
     if json {
         let mut items = Vec::new();
         for descriptor in ACE_MODEL_DESCRIPTORS {
             let is_downloaded = settings.downloaded_models.contains(&descriptor.variant);
-            let is_active = settings.model_variant == Some(descriptor.variant);
+            let slot = model_catalog::slot_for_ace_variant(descriptor.variant);
+            let is_active = active_slot.as_deref() == Some(slot.id);
 
             items.push(serde_json::json!({
+                "id": slot.id,
+                "engine": slot.engine.as_str(),
+                "pack": slot.pack_id,
                 "variant": descriptor.variant.as_str(),
                 "size_gb": descriptor.recommended_memory_gb,
                 "status": if is_downloaded { "downloaded" } else { "not_downloaded" },
                 "active": is_active,
+                "selectable": slot.selectable,
+            }));
+        }
+        for pack in model_catalog::CATALOG_PACKS {
+            if pack.ace_pack.is_some() {
+                continue;
+            }
+            items.push(serde_json::json!({
+                "id": pack.id,
+                "engine": pack.engine.as_str(),
+                "pack": pack.id,
+                "variant": serde_json::Value::Null,
+                "size_gb": pack.recommended_memory_gb,
+                "status": match pack.install_policy {
+                    PackInstallPolicy::Installable => "not_downloaded",
+                    PackInstallPolicy::Announced => "announced",
+                },
+                "active": active_slot.as_deref() == Some(pack.id),
+                "selectable": false,
             }));
         }
         let output = serde_json::to_string_pretty(&items).map_err(|e| cli_error(e.to_string()))?;
         super::json_output(&output);
     } else {
         println!(
-            "{:<10} {:<8} {:<12} Description",
-            r#"Variant"#, r#"Size"#, r#"Status"#
+            "{:<18} {:<24} {:<12} Description",
+            r#"Engine"#, r#"Slot"#, r#"Status"#
         );
-        let separator = "-".repeat(70);
+        let separator = "-".repeat(86);
         println!("{separator}");
 
         for descriptor in ACE_MODEL_DESCRIPTORS {
             let is_downloaded = settings.downloaded_models.contains(&descriptor.variant);
-            let is_active = settings.model_variant == Some(descriptor.variant);
+            let slot = model_catalog::slot_for_ace_variant(descriptor.variant);
+            let is_active = active_slot.as_deref() == Some(slot.id);
 
             let status = if is_active {
                 "● active"
@@ -98,16 +125,26 @@ fn execute_list(state: &AppState, json: bool) -> AppResult<()> {
                 "—"
             };
 
-            let size = format!("{}GB", descriptor.recommended_memory_gb);
-
             println!(
-                "{:<10} {:<8} {:<12} {}",
-                descriptor.variant.label(),
-                size,
+                "{:<18} {:<24} {:<12} {}",
+                slot.engine.as_str(),
+                slot.id,
                 status,
                 descriptor.description
             );
         }
+        for pack in model_catalog::CATALOG_PACKS {
+            if pack.ace_pack.is_some() {
+                continue;
+            }
+            println!(
+                "{:<18} {:<24} {:<12} {}",
+                pack.engine.as_str(),
+                pack.id,
+                "announced",
+                pack.description
+            );
+        }
     }
 
     Ok(())

src-tauri/src/commands/models.rs

@@ -2,7 +2,10 @@ use tauri::{AppHandle, State};
 
 use crate::{
     models::{errors::AppResult, settings::ModelVariant},
-    services::model_manager::{AceModelDescriptor, ModelStatusSnapshot, ACE_MODEL_DESCRIPTORS},
+    services::{
+        model_catalog::{self, ModelRegistry},
+        model_manager::{AceModelDescriptor, ModelStatusSnapshot, ACE_MODEL_DESCRIPTORS},
+    },
     AppState,
 };
 
@@ -11,6 +14,11 @@ pub fn list_model_catalog() -> Vec<AceModelDescriptor> {
     ACE_MODEL_DESCRIPTORS.to_vec()
 }
 
+#[tauri::command]
+pub fn list_model_registry() -> ModelRegistry {
+    model_catalog::registry()
+}
+
 #[tauri::command]
 pub fn get_model_status(state: State<'_, AppState>) -> AppResult<Vec<ModelStatusSnapshot>> {
     let settings = state.db.get_settings()?;

src-tauri/src/lib.rs

@@ -132,6 +132,7 @@ pub fn run() {
             commands::settings::remove_cli_from_path,
             commands::settings::is_cli_in_path,
             commands::models::list_model_catalog,
+            commands::models::list_model_registry,
             commands::models::get_model_status,
             commands::models::download_model,
             commands::models::delete_model,

src-tauri/src/models/settings.rs

@@ -49,6 +49,7 @@ impl std::fmt::Display for ModelVariant {
 pub struct AppSettings {
     pub profile: RecommendedProfile,
     pub model_variant: Option<ModelVariant>,
+    pub selected_model_id: Option<String>,
     pub downloaded_models: Vec<ModelVariant>,
     pub output_directory: Option<String>,
     pub backend_port: u16,
@@ -86,6 +87,7 @@ impl Default for AppSettings {
         Self {
             profile: RecommendedProfile::Standard,
             model_variant: None,
+            selected_model_id: None,
             downloaded_models: Vec::new(),
             output_directory: None,
             backend_port: 8001,
@@ -162,6 +164,7 @@ fn mirrors_to_setting_string(mirrors: &[String]) -> Result<String, serde_json::E
 pub enum SettingKey {
     Profile,
     ModelVariant,
+    SelectedModelId,
     DownloadedModels,
     OutputDirectory,
     BackendPort,
@@ -183,6 +186,7 @@ impl SettingKey {
         match key {
             "profile" => Ok(Self::Profile),
             "modelVariant" => Ok(Self::ModelVariant),
+            "selectedModelId" => Ok(Self::SelectedModelId),
             "downloadedModels" => Ok(Self::DownloadedModels),
             "outputDirectory" => Ok(Self::OutputDirectory),
             "backendPort" => Ok(Self::BackendPort),
@@ -207,6 +211,7 @@ impl SettingKey {
         match self {
             Self::Profile => "profile",
             Self::ModelVariant => "modelVariant",
+            Self::SelectedModelId => "selectedModelId",
             Self::DownloadedModels => "downloadedModels",
             Self::OutputDirectory => "outputDirectory",
             Self::BackendPort => "backendPort",
@@ -232,6 +237,7 @@ impl SettingKey {
                 | Self::BackendWorkingDirectory
                 | Self::LogDirectory
                 | Self::ModelVariant
+                | Self::SelectedModelId
                 | Self::ModelMirror
         )
     }
@@ -250,6 +256,11 @@ impl AppSettings {
                     AppError::validation_failed(format!("invalid modelVariant value: {error}"))
                 })?;
             }
+            SettingKey::SelectedModelId => {
+                self.selected_model_id = serde_json::from_value(value).map_err(|error| {
+                    AppError::validation_failed(format!("invalid selectedModelId value: {error}"))
+                })?;
+            }
             SettingKey::DownloadedModels => {
                 self.downloaded_models = serde_json::from_value(value).map_err(|error| {
                     AppError::validation_failed(format!("invalid downloadedModels value: {error}"))
@@ -334,6 +345,10 @@ impl AppSettings {
         let serialized = vec![
             ("profile", serde_json::to_string(&self.profile)),
             ("modelVariant", serde_json::to_string(&self.model_variant)),
+            (
+                "selectedModelId",
+                serde_json::to_string(&self.selected_model_id),
+            ),
             (
                 "downloadedModels",
                 serde_json::to_string(&self.downloaded_models),
@@ -407,6 +422,7 @@ mod tests {
         let keys = [
             "profile",
             "modelVariant",
+            "selectedModelId",
             "downloadedModels",
             "outputDirectory",
             "backendPort",
@@ -449,6 +465,7 @@ mod tests {
         assert!(SettingKey::BackendWorkingDirectory.impacts_backend_startup());
         assert!(SettingKey::LogDirectory.impacts_backend_startup());
         assert!(SettingKey::ModelVariant.impacts_backend_startup());
+        assert!(SettingKey::SelectedModelId.impacts_backend_startup());
         assert!(SettingKey::ModelMirror.impacts_backend_startup());
     }
 

src-tauri/src/services/mod.rs

@@ -7,6 +7,7 @@ pub mod file_store;
 pub mod generation_task;
 pub mod history;
 pub mod model_bootstrap;
+pub mod model_catalog;
 pub mod model_manager;
 pub mod network_log;
 pub mod observability;