Catalog Integration and Cost Tracking: Release Notes

This page records what the catalog-integration and cost-tracking work added to forge-cli. Earlier docs called these the "V1.5" and "V2" releases. Those are internal milestone names: the CLI is numbered 0.x, and no 1.5 or 2.0 release exists. The work first appeared in the 0.8.1a1 and 0.8.2a1 pre-releases and is in 0.8.3, the first stable release that has it, and in 0.18.1. Where the notes below describe behavior, they describe CLI 0.18.1.

For the current release, see Release notes 0.18.0 and the pages it links.

What was added

Theme	Where to read more
Seven source-catalog adapters	Catalogs index
A three-stage flow that carries catalog metadata through forge	Architecture
Industry auto-detection from catalog tags	Architecture
`fluid ai setup --source` wizard	Credential resolver
MCP `forge_from_source` and read-only catalog tools, with an `inputSchema` on every tool	MCP server
Cost summary: missing-usage footer, variant-lint footer, per-org price override	Cost tracking
`capability_matrix` in the cache key	below

Catalog integration

Seven adapters

Source-side catalog adapters read metadata from existing catalogs. They are the complement to the publish-target providers:

Their --source names are snowflake, unity, bigquery, dataplex, glue, datahub and datamesh_manager. Each adapter follows the nine reusable patterns described in the architecture page.

Two surfaces, one pipeline

Both surfaces dispatch to the same staged pipeline:

# CLI
fluid forge data-model from-source \
  --source snowflake \
  --credential-id snowflake-prod \
  --database BIZ_LAB --schema SEEDED \
  --modeling-technique data_vault_2 \
  -o biz_lab.fluid.yaml

// MCP: Claude Code, Cursor, any MCP client
{
  "tool": "forge_from_source",
  "arguments": {
    "source": "snowflake",
    "credentials": { "credential_id": "snowflake-prod" },
    "scope": { "database": "BIZ_LAB", "schema": "SEEDED" },
    "technique": "data_vault_2",
    "output_path": "biz_lab.fluid.yaml"
  }
}

fluid forge data-model from-source also accepts --source postgres, mysql and sqlite with a --uri, which the catalog adapters do not cover.

System roles never become owners

Snowflake ACCOUNTADMIN, SYSADMIN, SECURITYADMIN, USERADMIN, ORGADMIN and PUBLIC are not promoted to metadata.owner.team, and neither are the other names in the architecture page's list. They land in labels.catalogCreatingRoles, for audit only, so the contract names the business team and not the role that ran the DDL.

Industry auto-detection

Catalog domain tags are matched against INDUSTRY_DOMAIN_HINTS, which covers the telecommunications, healthcare, finance and retail industry packs. The most common hit across the scope wins, and --industry overrides it. See the architecture page.

`fluid ai setup --source` wizard

Per-source interactive setup with auth-method recommendations and field validation. It saves non-sensitive fields to ~/.fluid/sources.yaml and secrets to the OS keyring.

fluid ai setup --source snowflake --name snowflake-prod
fluid ai status                              # lists configured sources

fluid ai status lists the configured catalogs alongside the LLM provider configuration.

MCP `inputSchema`

Every MCP tool advertises a JSON Schema for its arguments at tools/list, so clients can offer typed autocomplete. For the catalog tools that includes:

source, an enum of the seven adapter names (forge_from_source also takes postgres, postgresql, mysql and sqlite)
technique, an enum of data_vault_2 and dimensional
credentials.credential_id, a pointer into ~/.fluid/sources.yaml; the tools never accept raw secrets
scope.database, scope.schema, scope.tables and scope.catalog
output_path, which must resolve under one of the server's --writable-paths

Cost tracking

The cost summary printed after fluid forge data-model gained three things, all described in Cost tracking:

A footer that says how many calls reported no usage, so a low total is not read as authoritative.
A footer with the variant-lint warning count, per variant.
A per-org price override file, ~/.fluid/prices.json, that accepts a wrapped ({"prices": {...}}) or a flat layout.

`capability_matrix` in the cache key

The cache key for a staged LLM call includes a hash of the model's capability matrix, next to the model, the prompt and the parameters. Changing a capability flag (extended-thinking budget, prompt-cache mode, structured-output strictness) therefore invalidates the cached response, and two runs with the same model, prompt and parameters but different capability matrices do not share a cache entry.

Migration notes

The default pip install data-product-forge does not install every catalog SDK. A missing SDK raises CatalogConfigError with the pip install line to run, for example pip install "data-product-forge[snowflake]".
Existing fluid forge data-model from-intent and from-ddl flows are unchanged; from-source is an additional entry point.
Cost summaries gain the new footer lines only when the matching counter is non-zero.
Cache entries written before the capability_matrix segment existed are not reused.