# `Agentic.LLM.Catalog`

Unified model catalog backed by a GenServer.

Holds all known models from three sources (priority order):
  1. User overrides from `~/.worth/config.exs`
  2. Dynamic discovery from `provider.fetch_catalog/1`
  3. Provider's static `default_models/0`

Persisted to `~/.worth/catalog.json` (schema-versioned).
Loaded at boot for warm-path latency, refreshed async in background.

# `all`

Return all models in the catalog.

# `by_canonical`

Group all `tier`-eligible models by `canonical_id`.

Returns `%{canonical_id => [%Model{}, ...]}`. Used by the
multi-pathway router to score pathways within each canonical group.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `find`

Find models matching filters.

Options:
  * `:provider` — filter by provider atom
  * `:tier` — filter by tier_hint (`:primary`, `:lightweight`)
  * `:has` — capability tag or list of tags (all must be present)
  * `:requires` — alias for `:has` (per the multi-pathway routing
    design); both work and stack
  * `:canonical` — filter by `canonical_id` string; returns every
    pathway model that maps to the given canonical
  * `:source` — filter by source (`:static`, `:discovered`, `:user_config`)

# `for_provider`

Return models for a specific provider.

# `info`

Return catalog metadata (counts, last refresh, etc).

# `lookup`

Look up a single model by provider and model id.

# `refresh`

Trigger an async refresh of all enabled providers.

# `refresh_provider`

Trigger an async refresh of a single provider.

# `start_link`

---

*Consult [api-reference.md](api-reference.md) for complete listing*