Keep mismatch examples out of code and docs

Leave concrete catalog/loader mismatch cases in the PR description; keep
in-repo sync tooling and maintainer docs generic aside from required
config maps.

Author: lapy

docs/maintainers/loader_and_catalog.md

@@ -24,24 +24,10 @@ For every **installable, standalone** `ModelPackage`:
 Dependency / subcomponent packages (`standalone=False`, with
 `parent_package_id`) do **not** need their own loader.
 
-Bundled loaders without a downloadable package (today: `silero_vad`) are allowed.
-If you add another, list it in `BUNDLED_LOADERS_WITHOUT_PACKAGE` inside
+Registered loaders that ship as bundled assets (no downloadable package) are
+allowed. List them in `BUNDLED_LOADERS_WITHOUT_PACKAGE` inside
 `tools/check_loader_catalog_sync.py`.
 
-## Verified parked families (this release tree)
-
-These registry stubs are **commented out**, and the loader sources are **not
-present** under `src/models/` / `include/engine/models/` (or community paths):
-
-| Registry stub | Catalog package(s) | Notes |
-|---|---|---|
-| `kokoro_tts` | `kokoro_82m_bf16` | Warm-bench tests remain; no loader sources |
-| `higgs_tts` | `higgs_audio_v3_tts_4b` (`family=higgs_audio_tts`) | Name mismatch: pick one id when re-enabling |
-| `parakeet_tdt` | `parakeet_tdt_0_6b_v3` | Warm-bench / docs may remain |
-
-Matching catalog entries must use `UnsupportedSource` until the loader code is
-actually merged and registered.
-
 If a loader is not ready for this release tree:
 
 1. Keep it **commented out** in `src/framework/runtime/registry.cpp`, and
@@ -51,6 +37,9 @@ If a loader is not ready for this release tree:
 
 Do **not** leave a live `SnapshotSource` for a commented-out loader.
 
+Optional catalog↔registry family renames for parked stubs go in
+`PARKED_FAMILY_ALIASES` in the sync check (collapse to one id when re-enabling).
+
 ## Checklist: adding a model family
 
 1. Implement `include/engine/models/<family>/` (or `community_models/`) with a
@@ -62,8 +51,7 @@ Do **not** leave a live `SnapshotSource` for a commented-out loader.
 3. Add `model_specs/<family>.json` when the family needs package-spec discovery.
 4. Add one or more `ModelPackage` entries in `tools/model_manager.py`:
    - Set `family="<family>"` explicitly when the package id does not strip cleanly
-     to the loader id (examples: `kokoro_82m_bf16` → `kokoro_tts`,
-     `vietneu_tts_v3_turbo` → `vietneu_tts`).
+     to the loader id.
    - Set `tasks=(...)` when defaults would be ambiguous.
    - Use `standalone=False` + `parent_package_id` for tokenizers / subcomponents.
 5. Update README supported-model / package tables.
@@ -99,9 +87,8 @@ Pick **one** family string and use it everywhere:
 - `ModelPackage.family`
 - README “Supported Models” family column
 
-Avoid mismatches such as catalog `higgs_audio_tts` with a registry stub named
-`higgs_tts`. Integrators match on the string; aliases are not implied (the sync
-check only knows the small parked alias map for currently parked stubs).
+Integrators match on the string; aliases are not implied unless listed in
+`PARKED_FAMILY_ALIASES` for currently parked stubs.
 
 ## CI
 

tools/check_loader_catalog_sync.py

@@ -1,21 +1,9 @@
 #!/usr/bin/env python3
 """Fail when installable catalog packages reference unregistered loaders.
 
-The machine-readable contract from PR #74 makes package ``family`` and
-``audiocpp_cli --list-loaders`` authoritative for integrators. Catalog entries
-must not advertise installable packages for families that are commented out or
-missing from ``src/framework/runtime/registry.cpp``.
-
-Verified release-tree facts this check encodes:
-
-- Parked registry stubs currently include ``kokoro_tts``, ``higgs_tts``, and
-  ``parakeet_tdt``. Those loader *sources are not in this tree* (no
-  ``src/models/<family>`` / matching include); only comments + warm-bench tests
-  remain. Matching catalog packages must be ``UnsupportedSource``.
-- ``higgs_audio_tts`` is treated as an alias of the parked ``higgs_tts`` stub
-  until one family id is chosen when the loader returns.
-- ``silero_vad`` is a registered loader without a model_manager package (bundled
-  asset path). That is allowed; see docs/maintainers/loader_and_catalog.md.
+``model_manager list --json`` family fields and ``audiocpp_cli --list-loaders``
+must stay aligned. Installable standalone packages cannot advertise a family
+that is missing or commented out in ``src/framework/runtime/registry.cpp``.
 
 See docs/maintainers/loader_and_catalog.md.
 """
@@ -35,8 +23,7 @@
 
 _LOADER_CALL_RE = re.compile(r"\bmake_([a-z0-9_]+)_loader\s*\(\s*\)")
 
-# Catalog family strings that refer to a differently named parked registry stub.
-# When re-enabling a loader, collapse these to one id everywhere.
+# Optional: catalog family strings that map to a differently named parked stub.
 PARKED_FAMILY_ALIASES: dict[str, set[str]] = {
     "higgs_tts": {"higgs_audio_tts"},
 }
@@ -161,7 +148,6 @@ def check_catalog(
             )
 
         if explicit is None and inferred not in active and family in active:
-            # Should be unreachable if family comes from inference, but keep tight.
             errors.append(
                 f"{package_id}: set ModelPackage.family explicitly "
                 f"(id inference '{inferred}' is not a registered loader)"
@@ -173,7 +159,6 @@ def check_catalog(
                 f"is not registered in registry.cpp{parked_hint(family, commented)}"
             )
         elif family_is_parked(family, commented):
-            # Active and commented with same name should not happen; still guard.
             errors.append(
                 f"{package_id}: family '{family}' is both active and commented in registry.cpp"
             )
@@ -250,37 +235,40 @@ def check_readme(
 class _SyncCheckSelfTests(unittest.TestCase):
     def test_parse_active_and_commented(self) -> None:
         text = """
-        // make_kokoro_tts_loader(),
-        make_pocket_tts_loader(),
-        make_higgs_tts_loader(), // trailing comment still active
+        // make_family_a_loader(),
+        make_family_b_loader(),
+        make_family_c_loader(), // trailing comment still active
         """
         active, commented = parse_registry_loaders(text)
-        self.assertEqual(active, {"pocket_tts", "higgs_tts"})
-        self.assertEqual(commented, {"kokoro_tts"})
+        self.assertEqual(active, {"family_b", "family_c"})
+        self.assertEqual(commented, {"family_a"})
 
     def test_parked_alias_blocks_installable(self) -> None:
         class Pkg:
             def __init__(self, family=None):
                 self.family = family
 
+        stub = next(iter(PARKED_FAMILY_ALIASES))
+        alias = next(iter(PARKED_FAMILY_ALIASES[stub]))
+
         def payload(package):
             return {
-                "id": "higgs_audio_v3_tts_4b",
-                "family": "higgs_audio_tts",
+                "id": "pkg_alias",
+                "family": alias,
                 "installable": True,
                 "standalone": True,
                 "source": {"kind": "huggingface_snapshot"},
             }
 
         errors, _ = check_catalog(
-            active={"pocket_tts"},
-            commented={"higgs_tts"},
-            packages=[Pkg(family="higgs_audio_tts")],
+            active={"family_b"},
+            commented={stub},
+            packages=[Pkg(family=alias)],
             package_payload=payload,
-            default_family_from_package_id=lambda _pid: "higgs_audio_v3_tts",
+            default_family_from_package_id=lambda _pid: "pkg_alias",
         )
-        self.assertTrue(any("higgs_audio_tts" in e for e in errors))
-        self.assertTrue(any("parked loader 'higgs_tts'" in e for e in errors))
+        self.assertTrue(any(alias in e for e in errors))
+        self.assertTrue(any(f"parked loader '{stub}'" in e for e in errors))
 
 
 def main() -> int:

tools/model_manager.py

@@ -220,9 +220,6 @@ def package_usage_examples(package: ModelPackage) -> list[str]:
         id="kokoro_82m_bf16",
         display_name="Kokoro 82M bf16",
         target_directory="Kokoro-82M-bf16",
-        # Loader is not registered in this release tree (see registry.cpp and
-        # docs/maintainers/loader_and_catalog.md). Keep the id for docs/history
-        # but do not advertise an installable HF snapshot.
         source=UnsupportedSource(
             reason=(
                 "kokoro_tts loader is not registered in this release tree yet "
@@ -849,9 +846,6 @@ def package_usage_examples(package: ModelPackage) -> list[str]:
         id="higgs_audio_v3_tts_4b",
         display_name="Higgs Audio v3 TTS 4B",
         target_directory="higgs-audio-v3-tts-4b",
-        # Catalog family must match the registered loader family id. The parked
-        # registry stub currently uses higgs_tts; when re-enabling, pick one
-        # family string and use it in registry, model_specs, and this field.
         source=UnsupportedSource(
             reason=(
                 "higgs_tts / higgs_audio_tts loader is not registered in this "