Module Catalogs

Understand Lenso module discovery catalogs, official fallback entries, and install boundaries.

A module catalog is discovery data. It helps an operator find modules, but it does not install them.

This split is important:

• official or explicit catalog = remember this module exists;
• module install = write host-local install state;
• Host composition = load Linked Modules and reconcile installed Services.

Local catalog file

For local discovery experiments, point .env at a catalog file:

LENSO_MODULE_CATALOG_FILE=.lenso/module-catalog.json

Catalog entries contain the module name, version, release reference, provider service, base URL, summary, capabilities, and Console package hints.

Install from catalog or manifest

The install command is still the boundary that changes the host:

lenso module install support-ticket

For a local release artifact, pass the runtime service base URL:

lenso module install dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json \
  --base-url http://127.0.0.1:4110/lenso/service/v1

Install writes host-local state such as .env, install receipts, service descriptors, and Console extension registry files. See Module Installation for that write set.

Available Modules order

Runtime Console’s Available Modules view merges discovery sources:

1. explicit .env LENSO_MODULE_CATALOG_FILE=<path>;
2. already configured Service providers;
3. built-in builtin:lenso-official-module-catalog.

The built-in catalog is the default official source for fresh hosts. It is not a hidden database of installed modules.

Linked modules in catalogs

First-party linked modules such as auth, auth-password, and auth-device can appear in the catalog because they are installable host features.

Their install path is different from service-backed modules:

lenso module install auth
lenso module install auth-password
lenso module install auth-device

Linked installs update the generated Host’s local composition and Module settings. Service installation records provider and lifecycle state; Console UI artifacts are owned by the Module Release and independent Console Service.

Catalog entry shape

A useful catalog entry answers the operator’s first questions:

{
  "name": "support-ticket",
  "version": "0.1.0",
  "protocol": "lenso.module-release.v1",
  "manifestReference": "dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json",
  "baseUrl": "http://127.0.0.1:4110/lenso/service/v1",
  "source": "service",
  "providedBy": "support-suite-provider",
  "summary": "Ticket intake, triage, and operations",
  "capabilities": [
    "support_ticket.tickets.read",
    "support_ticket.tickets.write"
  ]
}

The host still verifies the manifest during installation and startup. Catalog metadata is for discovery, not trust.

When to use a catalog

Use a catalog when:

• your team has a known set of service-backed modules;
• operators should see modules before installing them;
• you want Runtime Console to show a curated install path;
• the module manifest URL is stable enough to share.

Skip a catalog when you are testing a local module. Install the release artifact directly, then add catalog metadata after the module is worth discovering.