feat(catalog): support shared provider metadata

docs/FUSIONAIZE-SHARED-METADATA.md

@@ -0,0 +1,178 @@
+# fusionAIze Shared Metadata
+
+## Purpose
+
+This document defines the intended shape of the shared metadata line for
+fusionAIze products.
+
+It is deliberately **not** a generic cross-repo metadata platform.
+
+Scope:
+
+- `fusionAIze Gate`
+- future fusionAIze products such as `Grid`, `Lens`, and `Fabric`
+
+Out of scope:
+
+- unrelated repositories
+- general-purpose metadata hosting
+- a mandatory hosted control plane
+
+## Why this exists
+
+Gate already needs stronger truth around:
+
+- provider identity
+- model and offer aliases
+- modality and capability metadata
+- pricing provenance
+- freshness and review state
+
+Those same concerns can later matter for other fusionAIze products. The shared
+metadata line should therefore be designed once as a reusable fusionAIze
+capability instead of re-invented inside each product.
+
+## Working model
+
+Recommended first model:
+
+1. a dedicated Git repo for fusionAIze product metadata
+2. versioned JSON documents
+3. static-hostable snapshots
+4. optional scheduled refresh jobs outside product runtimes
+5. product-side refresh or import hooks
+
+This gives us:
+
+- reviewability in Git
+- easy local mirroring
+- no database requirement
+- no forced fusionAIze-operated hosting
+
+## Proposed repo shape
+
+```text
+fusionaize-metadata/
+  README.md
+  schemas/
+    provider-catalog.v1.schema.json
+  providers/
+    catalog.v1.json
+    sources.v1.json
+  snapshots/
+    providers/
+      2026-03-31T18-00-00Z.catalog.v1.json
+  products/
+    gate/
+      overlays.v1.json
+    grid/
+      overlays.v1.json
+    lens/
+      overlays.v1.json
+    fabric/
+      overlays.v1.json
+```
+
+## Provider catalog snapshot shape
+
+Recommended top-level form:
+
+```json
+{
+  "schema_version": "fusionaize-provider-catalog/v1",
+  "generated_at": "2026-03-31T18:00:00Z",
+  "source_repo": "fusionaize-metadata",
+  "providers": {
+    "deepseek-chat": {
+      "recommended_model": "deepseek-chat",
+      "aliases": ["deepseek-chat", "ds-v3"],
+      "track": "stable",
+      "offer_track": "direct",
+      "provider_type": "direct",
+      "auth_modes": ["api_key"],
+      "volatility": "low",
+      "evidence_level": "official",
+      "official_source_url": "https://api-docs.deepseek.com/",
+      "signup_url": "https://platform.deepseek.com/",
+      "watch_sources": [],
+      "notes": "Balanced DeepSeek direct route",
+      "last_reviewed": "2026-03-31",
+      "pricing": {
+        "source_type": "provider-docs",
+        "source_url": "https://api-docs.deepseek.com/pricing",
+        "refreshed_at": "2026-03-31T17:45:00Z",
+        "freshness_status": "fresh"
+      }
+    }
+  }
+}
+```
+
+## Required metadata principles
+
+Every price or offer-oriented field should be able to answer:
+
+- where did this value come from?
+- when was it refreshed?
+- how fresh is it?
+- is it official, mixed, manual, or observed?
+
+Recommended provenance fields:
+
+- `source_type`
+- `source_url`
+- `refreshed_at`
+- `freshness_status`
+
+## Gate integration path
+
+The first Gate slice should stay intentionally small:
+
+- Gate keeps its embedded curated catalog as a fallback baseline
+- Gate can optionally load an external JSON snapshot
+- the external snapshot can add new providers or override embedded fields
+
+That gives us a clean migration path:
+
+1. embedded Python catalog only
+2. optional JSON snapshot overrides
+3. JSON snapshot becomes preferred truth source
+4. embedded catalog shrinks to bootstrap fallback only
+
+## Current Gate hooks
+
+Gate now supports two operator-side import hooks:
+
+- `FAIGATE_PROVIDER_METADATA_FILE=/path/to/provider-catalog.snapshot.v1.json`
+- `FAIGATE_PROVIDER_METADATA_DIR=/path/to/fusionaize-metadata`
+
+If `FAIGATE_PROVIDER_METADATA_FILE` is set, Gate loads that JSON snapshot
+directly and merges it into the embedded provider catalog.
+
+If `FAIGATE_PROVIDER_METADATA_DIR` is set, Gate loads:
+
+- `providers/catalog.v1.json`
+- `products/gate/overlays.v1.json`
+
+and materializes an effective Gate catalog in memory before merging it into the
+embedded provider catalog.
+
+For runtime use, Gate also ships a small helper that materializes a repo
+checkout into one snapshot file:
+
+```bash
+./scripts/faigate-provider-metadata-sync \
+  --repo /path/to/fusionaize-metadata \
+  --product gate
+```
+
+The output snapshot can then be pointed to with
+`FAIGATE_PROVIDER_METADATA_FILE` and refreshed alongside restart or
+repo-update flows.
+
+For the first tracked gaps in Gate, the example `products/gate/overlays.v1.json`
+already includes:
+
+- `anthropic-haiku`
+- `anthropic-sonnet`
+- `gemini-pro`

docs/IMPLEMENTATION-PLAN.md

@@ -175,6 +175,143 @@ Reference:
 
 - [Dashboard IA](./DASHBOARD-IA.md)
 
+### Immediate operator-trust slices after dashboard v1
+
+These are the next high-signal follow-ups now that the first dashboard surface
+exists and exposes the real gaps.
+
+They should be treated as short operator-trust slices, not as a second broad UI
+redesign.
+
+#### Cluster A - cost truth and catalog freshness
+
+Observed gap:
+
+- cost data is not yet trustworthy enough to explain spend posture per provider
+- several providers still show as untracked in the catalog layer
+
+Challenge:
+
+- provider "price" is not one thing
+- direct-provider list pricing, aggregator marketplace pricing, free-tier offers,
+  and effective billed usage can diverge
+- the product should not claim false precision where only a stale public price
+  table exists
+
+Recommendation:
+
+- introduce a versioned provider-metadata source of truth that can live as JSON
+  in a repo rather than as a hosted database
+- design that metadata source as a shared fusionAIze boundary from day one so
+  Gate is only the first consumer, not the only one
+- keep that scope explicitly limited to fusionAIze products rather than turning
+  it into a generic cross-repo metadata service
+- keep cost provenance explicit per field:
+  - source price
+  - source timestamp
+  - freshness status
+  - source type (`provider-docs`, `aggregator-offer`, `manual-review`,
+    `observed-usage`)
+- add a small refresh job outside Gate that updates that metadata on a fixed
+  rhythm
+- pull that metadata into Gate through a conservative update path tied to normal
+  catalog refresh and restart flows
+
+Working shape:
+
+- versioned JSON documents
+- statically hostable if desired, but not dependent on a dedicated hosted
+  database
+- reusable later for `fusionAIze Grid`, `Lens`, `Fabric`, and similar products
+- not intended for unrelated repositories outside the fusionAIze product line
+- reviewable in Git with clear operator override paths
+
+Immediate slices:
+
+1. catalog schema for price provenance and freshness
+2. tracked assumptions for `anthropic-haiku`, `anthropic-sonnet`, and
+   `gemini-pro`
+3. dashboard surfacing for `tracked`, `stale`, `untracked`, and `source age`
+4. post-update metadata refresh hook tied to Gate's normal update cadence
+
+#### Cluster B - route and lane explainability
+
+Observed gap:
+
+- operators can see routes and lanes, but not yet in a way that feels obvious
+  at a glance
+
+Challenge:
+
+- a graphic by itself will not fix this if the underlying route explanation is
+  still too implicit
+- visual route maps should follow clearer route-decision semantics, not replace
+  them
+
+Recommendation:
+
+- make route choice legible in layers:
+  - requested intent
+  - chosen lane
+  - chosen execution route
+  - same-lane fallback candidates
+  - downgrade path if fallback crossed clusters
+- then add a light visual route map once the textual explanation is already
+  operator-trustworthy
+
+Immediate slices:
+
+1. "why this lane / why this route" drilldown in Routes and Request Log
+2. explicit same-lane fallback vs downgrade markers
+3. lane-family summary cards in Overview and Routes
+4. lightweight visual route map once route trace semantics are stable
+
+#### Cluster C - intelligent command bar and shell parity
+
+Observed gap:
+
+- the command bar filters well enough, but it is not yet intelligent
+- the dashboard does not yet move in lockstep with shell capabilities and
+  config workflows
+
+Challenge:
+
+- "intelligent" should not become another black box
+- if the dashboard can suggest scopes or edits, the same logic must stay
+  inspectable and reproducible from CLI and YAML
+
+Recommendation:
+
+- keep the command bar operator-first:
+  - saved scopes
+  - recommended pivots
+  - next useful drilldowns
+- build shell and dashboard against the same capability layer rather than
+  inventing separate UX-only semantics
+- add config actions only through safe preview/diff/apply flows, not direct
+  opaque mutation
+
+Immediate slices:
+
+1. shell-backed scope suggestions (`high spend`, `fallback active`,
+   `premium drift`, `untracked catalog`)
+2. deep links from dashboard panels to equivalent shell or API views
+3. dashboard config actions with preview, diff, backup, and explicit apply
+4. parity review so dashboard filters, shell helpers, and YAML names stay
+   aligned
+
+#### Recommended near-term order
+
+1. cost truth and tracked-catalog freshness
+2. route and lane explainability
+3. command bar intelligence and shell/config parity
+
+This order keeps the next product gains grounded in trust:
+
+- first make the cost and catalog story believable
+- then make route choice more legible
+- then add smarter operator controls on top of that clearer model
+
 ### `v1.16.x` - adaptive orchestration trust
 
 Primary outcome:

docs/examples/fusionaize-metadata-repo/README.md

@@ -0,0 +1,49 @@
+# fusionAIze Metadata Repo Skeleton
+
+This directory is a starter skeleton for a future dedicated
+`fusionaize-metadata` repository.
+
+It is intentionally scoped to fusionAIze products only:
+
+- Gate
+- Grid
+- Lens
+- Fabric
+
+It is not intended as a shared metadata platform for unrelated repositories.
+
+## Layout
+
+```text
+fusionaize-metadata/
+  README.md
+  schemas/
+    provider-catalog.v1.schema.json
+  providers/
+    catalog.v1.json
+    sources.v1.json
+  products/
+    gate/
+      overlays.v1.json
+```
+
+## Gate integration
+
+Gate supports two input modes:
+
+1. direct snapshot file
+   - `FAIGATE_PROVIDER_METADATA_FILE=/path/to/provider-catalog.snapshot.v1.json`
+2. metadata repo checkout with product overlay
+   - `FAIGATE_PROVIDER_METADATA_DIR=/path/to/fusionaize-metadata`
+   - optional `FAIGATE_PROVIDER_METADATA_PRODUCT=gate`
+
+To materialize a snapshot from a repo checkout for runtime use:
+
+```bash
+./scripts/faigate-provider-metadata-sync \
+  --repo /path/to/fusionaize-metadata \
+  --product gate
+
+Restart and managed update flows can call the same helper automatically when
+`FAIGATE_PROVIDER_METADATA_DIR` is set in the runtime environment.
+```