# Ambient Systems — Documentation (customer package)
- **Version:** 20260914-vfc353f3
- **Built:** 2026-09-14T14:09:45.060Z
- **ambient-core ref:** fc353f3
- **Live wiki:** https://www.ambientsystems.ai/docs/index.html
This file is the full public documentation wiki as Markdown sources.
Site ops runbooks are included because they ship in the public `/docs/` tree.
---
## catalog/core-metrics.md
# Core metrics layer
Ambient Core defines **15 shared templates** in `catalog/shared/metrics.yaml`. At generate time they expand into every industry pack as `{industry}.core.{slug}` keys (270 expanded keys across 18 packs). Each industry page lists its core rows alongside pack-specific metrics.
### Predictive Maintenance Cost Savings
- **ID:** 23
- **Type:** Financial
- **Unit:** Currency (e.g., USD)
- **Description:** Cost savings achieved by preventing equipment failures through predictive maintenance.
- **Inputs:** `repair_cost_avoided`, `predictive_maintenance_cost`
- **Methodology:** Potential Repair Cost Avoided - Predictive Maintenance Cost
- **Calculation:** **`repair_cost_avoided - predictive_maintenance_cost`**
- **Catalog key:** `0MJiYgAPcgkzE3xEgOFE`
### Cost per Kilogram of Produce
- **ID:** 20
- **Type:** Operational
- **Unit:** $/kg
- **Description:** Total cost associated with producing one kilogram of crops.
- **Inputs:** `total_production_cost`, `total_operational_cost`
- **Methodology:** Total Production Cost (Seeds, Fertilizers, Nutrients) + Total Operational Cost (Labor, Energy, Water, Maintenance) / Total Yield (kg)
- **Calculation:** **`total_production_cost + total_operational_cost`**
- **Catalog key:** `6IfrKxlTi9pbGzpuLL5u`
### Energy Cost per Unit of Light Delivered
- **ID:** 22
- **Type:** Operational
- **Unit:** kWh/lux-hour
- **Description:** Energy consumption required to deliver the desired light intensity.
- **Inputs:** `energy_consumed`, `total_light_delivered`
- **Methodology:** Energy Consumed (kWh) / Total Light Delivered (lux-hours or similar unit)
- **Calculation:** **`energy_consumed / total_light_delivered`**
- **Catalog key:** `8B9bFHS6GSsjzHx9ppKu`
### Annual Recurring Revenue (ARR)
- **ID:** 1017
- **Type:** Financial
- **Unit:** Currency/year
- **Description:** Annualized run-rate of recurring subscription revenue.
- **Methodology:** ARR = MRR × 12
- **Calculation:** **`mrr * 12`**
- **Catalog key:** `Allverticalfarmingsaas-arr`
### Customer Acquisition Cost (CAC)
- **ID:** 1035
- **Type:** Financial
- **Unit:** Currency (e.g., USD)
- **Description:** Fully-loaded sales & marketing cost to acquire one new customer.
- **Inputs:** `sales_marketing_spend`, `new_customers`
- **Methodology:** CAC = Total Sales & Marketing Spend / New Customers Acquired
- **Calculation:** **`sales_marketing_spend / new_customers`**
- **Catalog key:** `Allverticalfarmingsaas-cac`
### Gross Revenue Churn Rate
- **ID:** 1029
- **Type:** Operational
- **Unit:** %
- **Description:** Percentage of recurring revenue lost to cancellations and downgrades.
- **Inputs:** `churned_mrr`, `starting_mrr`
- **Methodology:** Gross Churn = (Churned MRR / Starting MRR) × 100
- **Calculation:** **`churned_mrr / starting_mrr * 100`**
- **Catalog key:** `Allverticalfarmingsaas-gross-churn`
### Customer Lifetime Value (LTV)
- **ID:** 1041
- **Type:** Financial
- **Unit:** Currency (e.g., USD)
- **Description:** Expected gross-margin revenue from a customer over their lifetime.
- **Inputs:** `avg_revenue_per_account`, `gross_margin_pct`, `churn_rate`
- **Methodology:** LTV = (Average Revenue per Account × Gross Margin %) / Churn Rate
- **Calculation:** **`(avg_revenue_per_account * gross_margin_pct / 100) / churn_rate`**
- **Catalog key:** `Allverticalfarmingsaas-ltv`
### LTV : CAC Ratio
- **ID:** 1047
- **Type:** Financial
- **Unit:** Ratio
- **Description:** Ratio of customer lifetime value to acquisition cost — core SaaS unit economics.
- **Methodology:** LTV:CAC = Customer Lifetime Value / Customer Acquisition Cost
- **Calculation:** **`ltv / cac`**
- **Catalog key:** `Allverticalfarmingsaas-ltv-cac`
### Monthly Recurring Revenue (MRR)
- **ID:** 1011
- **Type:** Financial
- **Unit:** Currency/month
- **Description:** Normalized recurring subscription revenue billed in a month.
- **Inputs:** `active_subscriptions`, `avg_monthly_price`
- **Methodology:** MRR = Σ (Active Subscriptions × Monthly Subscription Price)
- **Calculation:** **`active_subscriptions * avg_monthly_price`**
- **Catalog key:** `Allverticalfarmingsaas-mrr`
### Net Revenue Retention (NRR)
- **ID:** 1023
- **Type:** Financial
- **Unit:** %
- **Description:** Revenue retained and expanded from existing customers, net of churn and contraction.
- **Inputs:** `starting_mrr`, `expansion_mrr`, `contraction_mrr`, `churned_mrr`
- **Methodology:** NRR = ((Starting MRR + Expansion − Contraction − Churn) / Starting MRR) × 100
- **Calculation:** **`(starting_mrr + expansion_mrr - contraction_mrr - churned_mrr) / starting_mrr * 100`**
- **Catalog key:** `Allverticalfarmingsaas-nrr`
### Rule of 40
- **ID:** 1053
- **Type:** Financial
- **Unit:** %
- **Description:** Balance of growth and profitability for recurring-revenue businesses.
- **Inputs:** `revenue_growth_pct`, `profit_margin_pct`
- **Methodology:** Rule of 40 = Revenue Growth % + Profit Margin %
- **Calculation:** **`revenue_growth_pct + profit_margin_pct`**
- **Catalog key:** `Allverticalfarmingsaas-rule-of-40`
### Crop Health Index
- **ID:** 19
- **Type:** Operational
- **Unit:** Index
- **Description:** An index indicating the overall health of crops based on various parameters.
- **Inputs:** `sum_health_scores`, `total_crops`
- **Methodology:** Crop Health Index = (Sum of Health Scores / Total Number of Crops) * 100
- **Calculation:** **`sum_health_scores / total_crops * 100`**
- **Catalog key:** `E5khIDv93onvwtXBUsJH`
### Profit Margin
- **ID:** 21
- **Type:** Financial
- **Unit:** %
- **Description:** Difference between revenue and total costs.
- **Inputs:** `produce_revenue`, `total_production_cost`, `total_operational_cost`
- **Methodology:** Revenue from Produce Sales - Total Production Cost - Total Operational Cost
- **Calculation:** **`produce_revenue - total_production_cost - total_operational_cost`**
- **Catalog key:** `F6IlgQNV6qNtUhk3BVtT`
### Labor Cost per Kilogram of Produce
- **ID:** 18
- **Type:** Operational
- **Unit:** $/kg
- **Description:** Average labor cost associated with producing one kilogram of produce.
- **Inputs:** `total_labor_costs`, `total_harvested_kg`
- **Methodology:** Labor Cost per Kilogram of Produce = Total Labor Costs / Total Harvested Produce (kg)
- **Calculation:** **`total_labor_costs / total_harvested_kg`**
- **Catalog key:** `WeTkxvZyeWX51XfBGsuR`
### Water Usage Efficiency
- **ID:** 16
- **Type:** Operational
- **Unit:** kg/liter
- **Description:** Amount of produce harvested per liter of water used.
- **Inputs:** `total_harvested_kg`, `total_water_liters`
- **Methodology:** Water Usage Efficiency = Total Harvested Produce (kg) / Total Water Used (liters)
- **Calculation:** **`total_harvested_kg / total_water_liters`**
- **Catalog key:** `f3yEk5mEWwKhAFFQFyje`
### Yield per Square Meter
- **ID:** 15
- **Type:** Operational
- **Unit:** kg/m²
- **Description:** Amount of produce harvested per square meter of growing area.
- **Inputs:** `total_harvested_kg`, `total_growing_area`
- **Methodology:** Yield per Square Meter = Total Harvested Produce (kg) / Total Growing Area (m²)
- **Calculation:** **`total_harvested_kg / total_growing_area`**
- **Catalog key:** `jnQw1pD0motTKBZ9csPD`
### Monthly Burn Rate
- **ID:** 999
- **Type:** Financial
- **Unit:** Currency/month
- **Description:** Net cash consumed per month (negative net operating cash flow).
- **Inputs:** `cash_out`, `cash_in`
- **Methodology:** Net Burn = Cash Out − Cash In (per month)
- **Calculation:** **`cash_out - cash_in`**
- **Catalog key:** `vertical_farming.core.burn_rate`
### Cash Conversion Cycle
- **ID:** 987
- **Type:** Financial
- **Unit:** Days
- **Description:** Days to convert investments in inventory and receivables back into cash.
- **Inputs:** `days_inventory_outstanding`
- **Methodology:** CCC = DSO + Days Inventory Outstanding − DPO
- **Calculation:** **`dso + days_inventory_outstanding - dpo`**
- **Catalog key:** `vertical_farming.core.ccc`
### Current Ratio
- **ID:** 927
- **Type:** Financial
- **Unit:** Ratio
- **Description:** Short-term liquidity: ability to cover current liabilities with current assets.
- **Inputs:** `current_assets`, `current_liabilities`
- **Methodology:** Current Ratio = Current Assets / Current Liabilities
- **Calculation:** **`current_assets / current_liabilities`**
- **Catalog key:** `vertical_farming.core.current_ratio`
### Days Payable Outstanding (DPO)
- **ID:** 981
- **Type:** Financial
- **Unit:** Days
- **Description:** Average number of days the business takes to pay its suppliers.
- **Inputs:** `accounts_payable`, `cogs`, `days`
- **Methodology:** DPO = (Accounts Payable / COGS) × Number of Days
- **Calculation:** **`accounts_payable / cogs * days`**
- **Catalog key:** `vertical_farming.core.dpo`
### Days Sales Outstanding (DSO)
- **ID:** 975
- **Type:** Financial
- **Unit:** Days
- **Description:** Average number of days to collect cash after a sale.
- **Inputs:** `accounts_receivable`, `total_credit_sales`, `days`
- **Methodology:** DSO = (Accounts Receivable / Total Credit Sales) × Number of Days
- **Calculation:** **`accounts_receivable / total_credit_sales * days`**
- **Catalog key:** `vertical_farming.core.dso`
### EBITDA Margin
- **ID:** 951
- **Type:** Financial
- **Unit:** %
- **Description:** Core operating cash profitability before interest, tax, depreciation and amortization.
- **Inputs:** `ebitda`, `revenue`
- **Methodology:** EBITDA Margin = (EBITDA / Revenue) × 100
- **Calculation:** **`ebitda / revenue * 100`**
- **Catalog key:** `vertical_farming.core.ebitda_margin`
### Gross Profit Margin
- **ID:** 939
- **Type:** Financial
- **Unit:** %
- **Description:** Share of revenue retained after the direct cost of goods sold.
- **Inputs:** `revenue`, `cogs`
- **Methodology:** Gross Margin = ((Revenue − COGS) / Revenue) × 100
- **Calculation:** **`(revenue - cogs) / revenue * 100`**
- **Catalog key:** `vertical_farming.core.gross_margin`
### Headcount (FTE)
- **ID:** 1085
- **Type:** Operational
- **Unit:** Count
- **Description:** Period-end count of active full-time-equivalent employees. A directly measured input, not a derived ratio.
- **Methodology:** Period-end count of active employees expressed as full-time equivalents (directly measured, not calculated).
- **Calculation:** _No machine-readable calc — directly reported or qualitative._
- **Catalog key:** `vertical_farming.core.headcount`
### Net Profit Margin
- **ID:** 957
- **Type:** Financial
- **Unit:** %
- **Description:** Bottom-line profitability after all costs, interest and tax.
- **Inputs:** `net_income`, `revenue`
- **Methodology:** Net Profit Margin = (Net Income / Revenue) × 100
- **Calculation:** **`net_income / revenue * 100`**
- **Catalog key:** `vertical_farming.core.net_margin`
### Operating Cash Flow
- **ID:** 993
- **Type:** Financial
- **Unit:** Currency (e.g., USD)
- **Description:** Cash generated by core operations during the period.
- **Inputs:** `net_income`, `non_cash_charges`, `increase_in_working_capital`
- **Methodology:** Operating Cash Flow = Net Income + Non-Cash Charges − Increase in Working Capital
- **Calculation:** **`net_income + non_cash_charges - increase_in_working_capital`**
- **Catalog key:** `vertical_farming.core.operating_cash_flow`
### Operating Margin (EBIT)
- **ID:** 945
- **Type:** Financial
- **Unit:** %
- **Description:** Operating profitability after operating expenses (EBIT margin).
- **Inputs:** `operating_income`, `revenue`
- **Methodology:** Operating Margin = (Operating Income / Revenue) × 100
- **Calculation:** **`operating_income / revenue * 100`**
- **Catalog key:** `vertical_farming.core.operating_margin`
### Quick Ratio (Acid Test)
- **ID:** 933
- **Type:** Financial
- **Unit:** Ratio
- **Description:** Acid-test liquidity excluding inventory — most conservative short-term solvency view.
- **Inputs:** `current_assets`, `inventory`, `current_liabilities`
- **Methodology:** Quick Ratio = (Current Assets − Inventory) / Current Liabilities
- **Calculation:** **`(current_assets - inventory) / current_liabilities`**
- **Catalog key:** `vertical_farming.core.quick_ratio`
### Revenue Growth Rate
- **ID:** 963
- **Type:** Financial
- **Unit:** %
- **Description:** Period-over-period revenue growth rate.
- **Inputs:** `revenue`, `revenue_prior`
- **Methodology:** Revenue Growth = ((Current Period Revenue − Prior Period Revenue) / Prior Period Revenue) × 100
- **Calculation:** **`(revenue - revenue_prior) / revenue_prior * 100`**
- **Catalog key:** `vertical_farming.core.revenue_growth`
### Cash Runway
- **ID:** 1005
- **Type:** Financial
- **Unit:** Months
- **Description:** Number of months of cash remaining at the current net burn rate.
- **Inputs:** `current_cash_balance`
- **Methodology:** Runway (months) = Current Cash Balance / Monthly Net Burn
- **Calculation:** **`current_cash_balance / burn_rate`**
- **Catalog key:** `vertical_farming.core.runway`
### Working Capital
- **ID:** 969
- **Type:** Financial
- **Unit:** Currency (e.g., USD)
- **Description:** Operating liquidity available to fund day-to-day operations.
- **Inputs:** `current_assets`, `current_liabilities`
- **Methodology:** Working Capital = Current Assets − Current Liabilities
- **Calculation:** **`current_assets - current_liabilities`**
- **Catalog key:** `vertical_farming.core.working_capital`
### Energy Consumption per Square Meter
- **ID:** 17
- **Type:** Operational
- **Unit:** kWh/m²
- **Description:** Amount of energy consumed per square meter of growing area.
- **Inputs:** `total_energy_kwh`, `total_growing_area`
- **Methodology:** Energy Consumption per Square Meter = Total Energy Consumed (kWh) / Total Growing Area (m²)
- **Calculation:** **`total_energy_kwh / total_growing_area`**
- **Catalog key:** `yGoqLDC3Mrk1OeH36jkB`
## Data engineering pipeline
Ambient Core ships the **catalog** (typed data options and metrics) and `ambient_pipeline` helpers. Lakehouse jobs and schedules live in the application repository that pins a core tag.
```mermaid
flowchart LR
upload[Bronze CSV upload]
option[Pack data option fields]
silver[Silver tenant-metrics]
calc[ambient_calc]
gold[Gold products]
upload --> option --> silver --> calc --> gold
```
**Canonical order:** map columns → coerce types → unpivot → stamp lineage → (optional Silver validate) → contract assert → write. Gold vertical products evaluate catalog formulas with `ambient_calc` after Silver.
### How this pack feeds the pipeline
- **Accounts payable aging** — feeds [Days Payable Outstanding (DPO)](#days-payable-outstanding-dpo), [Cash Conversion Cycle](#cash-conversion-cycle)
- **Accounts receivable aging** — feeds [Days Sales Outstanding (DSO)](#days-sales-outstanding-dso), [Cash Conversion Cycle](#cash-conversion-cycle)
- **Balance sheet** — feeds [Current Ratio](#current-ratio), [Quick Ratio (Acid Test)](#quick-ratio-acid-test), [Working Capital](#working-capital), [Cash Conversion Cycle](#cash-conversion-cycle)
- **Bank statements** — feeds [Operating Cash Flow](#operating-cash-flow), [Monthly Burn Rate](#monthly-burn-rate), [Cash Runway](#cash-runway)
- **CRM / Sales pipeline** — feeds [Monthly Recurring Revenue (MRR)](#monthly-recurring-revenue-mrr), [Customer Acquisition Cost (CAC)](#customer-acquisition-cost-cac)
- **General ledger** — feeds [Gross Profit Margin](#gross-profit-margin), [Operating Margin (EBIT)](#operating-margin-ebit), [EBITDA Margin](#ebitda-margin), [Net Profit Margin](#net-profit-margin), [Revenue Growth Rate](#revenue-growth-rate), [Days Sales Outstanding (DSO)](#days-sales-outstanding-dso), [Days Payable Outstanding (DPO)](#days-payable-outstanding-dpo), [Operating Cash Flow](#operating-cash-flow), [Customer Acquisition Cost (CAC)](#customer-acquisition-cost-cac)
- **Marketing spend records** — feeds [Customer Acquisition Cost (CAC)](#customer-acquisition-cost-cac), [LTV : CAC Ratio](#ltv--cac-ratio)
- **Product usage logs** — feeds [Net Revenue Retention (NRR)](#net-revenue-retention-nrr), [Gross Revenue Churn Rate](#gross-revenue-churn-rate)
- **Subscription billing records** — feeds [Monthly Recurring Revenue (MRR)](#monthly-recurring-revenue-mrr), [Annual Recurring Revenue (ARR)](#annual-recurring-revenue-arr), [Net Revenue Retention (NRR)](#net-revenue-retention-nrr), [Gross Revenue Churn Rate](#gross-revenue-churn-rate), [Customer Lifetime Value (LTV)](#customer-lifetime-value-ltv), [LTV : CAC Ratio](#ltv--cac-ratio), [Rule of 40](#rule-of-40)
- **Trial balance** — feeds [Current Ratio](#current-ratio), [Quick Ratio (Acid Test)](#quick-ratio-acid-test), [Working Capital](#working-capital)
- **Irrigation logs** — feeds [Water Usage Efficiency](#water-usage-efficiency)
- **Farm management systems** — feeds [Yield per Square Meter](#yield-per-square-meter), [Water Usage Efficiency](#water-usage-efficiency), [Energy Consumption per Square Meter](#energy-consumption-per-square-meter), [Crop Health Index](#crop-health-index), [Cost per Kilogram of Produce](#cost-per-kilogram-of-produce), [Profit Margin](#profit-margin), [Energy Cost per Unit of Light Delivered](#energy-cost-per-unit-of-light-delivered), [Predictive Maintenance Cost Savings](#predictive-maintenance-cost-savings)
- **Harvest logs** — feeds [Yield per Square Meter](#yield-per-square-meter), [Labor Cost per Kilogram of Produce](#labor-cost-per-kilogram-of-produce)
- **Crop monitoring systems** — feeds [Yield per Square Meter](#yield-per-square-meter), [Crop Health Index](#crop-health-index)
- **Accounting Software** — feeds [Gross Profit Margin](#gross-profit-margin), [Operating Margin (EBIT)](#operating-margin-ebit), [Net Profit Margin](#net-profit-margin), [Cost per Kilogram of Produce](#cost-per-kilogram-of-produce), [Profit Margin](#profit-margin)
- **Financial statements** — feeds [Current Ratio](#current-ratio), [Quick Ratio (Acid Test)](#quick-ratio-acid-test), [Gross Profit Margin](#gross-profit-margin), [Operating Margin (EBIT)](#operating-margin-ebit), [Net Profit Margin](#net-profit-margin), [EBITDA Margin](#ebitda-margin), [Operating Cash Flow](#operating-cash-flow), [Revenue Growth Rate](#revenue-growth-rate), [Working Capital](#working-capital), [Days Sales Outstanding (DSO)](#days-sales-outstanding-dso), [Days Payable Outstanding (DPO)](#days-payable-outstanding-dpo), [Cash Conversion Cycle](#cash-conversion-cycle), [Monthly Burn Rate](#monthly-burn-rate), [Cash Runway](#cash-runway)
- **HR records** — feeds [Headcount (FTE)](#headcount-fte), [Labor Cost per Kilogram of Produce](#labor-cost-per-kilogram-of-produce)
- **Payroll records** — feeds [Net Profit Margin](#net-profit-margin), [Operating Margin (EBIT)](#operating-margin-ebit), [Labor Cost per Kilogram of Produce](#labor-cost-per-kilogram-of-produce), [Cost per Kilogram of Produce](#cost-per-kilogram-of-produce)
Further reading: [Catalog consumption](/open-core/catalog-consumption/) · [Pipeline governance helpers](/open-core/pipeline/)
---
_Generated from ambient-core ref `fc353f3` (digest `2fa4ebc79e445a83`). Regenerate: `npm run sync:catalog-wiki`._
---
## index.md
# Start Here
Public technical wiki for **ambient-core** (open source) and the Ambient Systems **Command Centre** (platform). Read the orientation pages under this section when a topic spans both. Use Integrator or Operator only when the content belongs to one lane.
## Choose your path
- **Orientation (this section)** - Compare open-source core and hosted platform without mixing ownership. Start with [Foundation vs full product](/open-core/core-vs-platform/), then the Work cycles pages, then [Ambient Core in the platform](/platform/ambient-core/).
- **Open Source Integrator** - Pin [ambient-core](https://github.com/Ambient-Team/ambient-core), validate contracts, and embed catalog and pipeline libraries in your own stack. Start with [Usage](/open-core/usage/) and [Integrating](/open-core/integrating/). Metric equations and data-option definitions live only under Integrator (open-source core and reference catalog).
- **Platform Subscriber** - Hosted Command Centre guides for invitation-only or local setup (not a self-serve signup funnel). Start with [Using the platform](/platform/architecture/) and [Platform features](/platform/features/). Operator pages show product behavior and demos; they link to Integrator for formulas and pack definitions.
- **Site ops** - Marketing-site capture and outbound runbooks (Wix Forms → Contacts). Start with [Site ops](/ops/) then [Outbound capture](/ops/outbound-capture-runbook/).
Open-source core and catalog pages are synced from [ambient-core](https://github.com/Ambient-Team/ambient-core) at pinned refs recorded during site build. Operator platform, workspace demo, and site-ops pages are maintained in this wiki.
## Download full Docs
Every documentation page includes a bottom download bar for the versioned customer package (Markdown and PDF). The site footer also lists Downloads.
- Package version includes the build date and the pinned ambient-core ref (see the download bar).
- Files: `/docs/downloads/ambient-systems-docs-latest.md` and `/docs/downloads/ambient-systems-docs-latest.pdf` (also versioned filenames beside them).
---
## open-core/assurance-lifecycle.md
# Assurance lifecycle: core vs platform
**Assurance** is the work cycle that asks whether a metric can be **defended**: correct under a fixed definition, supported by evidence, traceable through lineage, and aligned between operational signals and financial outcomes. It is distinct from [benchmarking](/docs/open-core/benchmarking-lifecycle/) (who is better than whom) and from [investor disclosure](/docs/open-core/investor-disclosure-lifecycle/) (whether mandates for capital access are met)—though disclosed and benchmarked numbers should ideally pass the same assurance bar.
ambient-core defines **what** is measured and **how** Gold products are shaped; a **paid platform** runs control workflows, sign-off, and attestation packaging.
Index of all cycles: [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md).
## End-to-end flow
```mermaid
flowchart LR
subgraph core [ambient_core_OSS]
Catalog[catalog_methodology_calc]
QualityContract[quality_v1]
BridgeContract[operational_financial_bridge_v1]
Lineage[pipeline_lineage_rules]
end
subgraph platform [paid_platform]
Controls[control_packs]
Evidence[signoff_and_evidence]
DQViews[dq_and_variance_UI]
Attest[assurance_exports]
end
Catalog --> Controls
Lineage --> Evidence
QualityContract --> DQViews
BridgeContract --> DQViews
Evidence --> Attest
```
## Phase mapping
### 1. Control scope and definitions
- **Core** — Catalog `methodology`, `industry.segment.slug` keys, and [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md); contract schemas that define required columns and consumption rules.
- **Platform** — Control objectives per org and lens; mapping catalog metrics and contracts to control assertions; `assurance_framework` or `control_pack_id` in run metadata.
### 2. Evidence and ingestion
- **Core** — Bronze lineage enforcement (`enforce_bronze_lineage`), [catalog input field policy](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/input_field_policy.yaml), PHI denylist; plain-text extract boundary per [governed-data.md](/docs/open-core/governed-data/).
- **Platform** — Upload approvals, immutable evidence store, who certified which period, restatement policy.
### 3. Data quality measurement
- **Core** — [quality-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/quality-v1.yaml) shape: completeness, accuracy, anomaly counts, overall score, BCBS 239–oriented lineage fields on the governed scorecard and pipeline audit products.
- **Platform** — DQ dashboards, thresholds, escalation when grades fall below policy.
### 4. Operational–financial reconciliation
- **Core** — [operational-financial-bridge-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/operational-financial-bridge-v1.yaml) (alignment flag, variance counts, bridge mapping records); [bridge_rules.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/bridge_rules.yaml) and `metricBridgeHints.js` for narrative links between operational names and financial metrics (energy, NOI, DSCR themes).
- **Platform** — Reconciliation UI, ticketed variances, covenant “watermelon KPI” guards described in contract consumption notes.
### 5. Attestation and audit trail
- **Core** — [observability-pipeline-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/observability-pipeline-v1.yaml) audit and performance event shapes for pipeline observability.
- **Platform** — Assurance packs for external reviewers, read-only auditor portals, period close sign-off matrices.
## What core will not do
- Issue audit opinions or SOC reports.
- Replace GRC, SOX, or IT general-control tools.
- Store control testing workflows or sample selections.
The **`auditor` agent profile** in [../AGENTS.md](https://github.com/Ambient-Team/ambient-core/blob/main/AGENTS.md) validates contract YAML and summarizes governance observations in a plan-execute run—it is **not** the assurance product described here.
## REIT illustration (alignment, not ranking)
For a real-estate or listed REIT org, assurance often requires showing that **energy and property operations** tie to **financial outcomes**: energy consumption data options in [real_estate.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/real_estate.yaml), NOI and cap-rate semantics in the same pack, and bridge hints for energy versus opex and NOI. Assurance succeeds when operational extracts and financial close reconcile under one definition—not when the REIT beats a peer on NOI margin ([benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/)).
## Related
- [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md)
- [benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/)
- [investor-disclosure-lifecycle.md](/docs/open-core/investor-disclosure-lifecycle/)
- [CANONICAL_SCOPE.md](https://github.com/Ambient-Team/ambient-core/blob/main/CANONICAL_SCOPE.md)
- [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md)
- [quality-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/quality-v1.yaml)
---
*Canonical source: `ambient-core` at `docs/assurance-lifecycle.md` (sync ref `fc353f3`).*
---
## open-core/benchmarking-lifecycle.md
# Benchmarking lifecycle: core vs platform
Ambient Core is designed to support **benchmarking-style** FP&A and operational intelligence: fixed KPI definitions, peer-appropriate metrics within an [analysis lens](/docs/open-core/governed-data/#analysis-lens-and-multi-org-tenancy), and guardrail bands—not the full commercial loop from peer comparison through gap decomposition to managed improvement. That second half lives in a **paid multi-tenant platform** (for example [ambient-systems-platform](https://github.com/Ambient-Team/ambient-systems-platform)) on top of governed Gold data.
Practitioner benchmarking separates two phases that must not be conflated: a **performance-comparison** phase (levels, gaps, pace-setters) and a **practice-improvement** phase (what to change, whether it is transferable, and how to sustain gains). Core ships the measurement vocabulary and contracts; the platform ships population comparison, normalization policy, structural-vs-improvable decomposition, and action workflows.
## End-to-end flow
```mermaid
flowchart LR
subgraph core [ambient_core_OSS]
Catalog[catalog_metrics_calc]
Bench[benchmarks_yaml]
Codes[industryCodes_ISIC_NAICS]
Calc[ambient_calc]
BridgeContract[operational_financial_bridge_v1]
end
subgraph platform [paid_platform]
Peers[peer_cohort_actuals]
Norm[normalization_policy]
Gap[gap_and_waterfall_UI]
Improve[opportunity_workflows]
end
Catalog --> Calc
Bench --> Gap
Codes --> Peers
Calc --> BridgeContract
Peers --> Gap
Norm --> Gap
Gap --> Improve
```
## Phase mapping
### 1. Scope and comparability
- **Core** — Industry packs in [catalog/packs.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/packs.yaml); [analysis lens terminology](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md#terminology); official **ISIC / NAICS / NACE / GICS** tags on each pack (`industryCodes` in `pack.yaml`, exported in manifest v3). Coverage gaps: [catalog-industry-coverage.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog-industry-coverage.md).
- **Platform** — `peer_group_id` and org matching rules (sector, size band, geography, capital structure); optional `reporting_group_id` for holding-company rollup UI only. See recommended metadata in [catalog-consumption.md](/docs/open-core/catalog-consumption/#analysis-lens-and-metric-filtering).
### 2. Metric selection
- **Core** — Metrics carry `type` (Financial / Operational), `segment`, and `fpaWorkflow`; operating drivers sit beside `*.core.*` close metrics in each pack (for example Real Estate NOI and cap rate in [real_estate.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/real_estate.yaml); listed REIT investor metrics under `financial_services.reits.*` in [financial_services.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/financial_services.yaml)).
- **Platform** — Curated benchmark packs per tenant org; effectiveness versus efficiency groupings in the product UI.
### 3. Operational definitions
- **Core** — `methodology`, stable keys `industry.segment.slug`, and machine-readable `calc` blocks (`expr` + `inputs`) or `input: true` per [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md). [lib/ambient_calc](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_calc/__init__.py) evaluates declared formulas deterministically; core does not run ad-hoc peer comparison math.
- **Platform** — Upload mapping enforcement, harmonized recomputation when filers use different FFO or NOI boundaries, versioned study or disclosure files.
### 4. Normalization
- **Core** — Intensity-style metrics where authored (per available seat-km, per megawatt, per share, per ton-mile). Normalization **policy** (FX, mix indices, unlevered views) is not computed in this repository.
- **Platform** — Applies normalization before gaps are asserted; frontier methods such as DEA for large peer sets are platform analytics, not OSS.
### 5. Gap analysis (pace-setter vs focal)
- **Core** — Per-vertical `catalog/industries//benchmarks.yaml` supplies **healthy bands** linked via `benchmarkKey` on metrics (guardrails for planning, not peer rankings). Sector profiles indicate which metrics typify a business model for comparison design.
- **Platform** — Stores peer actuals, computes gap versus pace-setter, ranked displays, optional composite scores with declared weights and sensitivity analysis.
### 6. Decomposition: improvable vs structural
This is the main **paid** insight after benchmarking: users need to see which parts of a gap they can influence versus which reflect structure they should not misread as poor management.
**Core enablers (not the product):**
- **`calc.inputs` and metric dependencies** — Show which levers are mathematically part of a KPI (numerator, denominator, and upstream metrics resolved by `ambient_calc`). The platform can walk this graph when building bridges; core does not label slices “structural” or “improvable.”
- **[operational-financial-bridge-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/operational-financial-bridge-v1.yaml)** — Governed alignment between operational telemetry and financial metrics (variance counts, bridge mapping records). This guards “watermelon KPIs”; it is not a full waterfall chart product.
- **[bridge_rules.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/bridge_rules.yaml)** and generated `metricBridgeHints.js` — Narrative hints linking operational names to financial outcomes.
**Platform (paid):**
- Bridge or waterfall charts that split a headline gap into **structural** slices (documented portfolio mix, geography, asset age, climate, one-offs) and an **improvable** residual tied to operating or financing discipline.
- Linking improvable residuals to actions, owners, and monitoring.
### 7. Improvement and practice transfer
- **Core** — `fpaWorkflow` strings on catalog metrics guide where improvement effort maps.
- **Platform** — Post-benchmark improvement plans, ROI estimates, workflows, ticketing, and sustainment—commercial product scope.
## How the platform should use catalog mechanics
When showing “what is improvable,” the platform should:
1. Resolve the focal metric’s `calc` block and dependency chain from the manifest or YAML.
2. Compare focal and pace-setter values **per input or sub-metric** where data exists, using the same operational definitions.
3. Attribute remaining gap to **documented structural factors** stored in platform metadata (not invented in core).
4. Surface `fpaWorkflow` and bridge hints for interpretation when recommendations are generated.
Core will **not** store peer time series, draw waterfall UI, or classify gap slices without platform logic.
## Illustrative REIT paired comparison (sketch)
This sketch mirrors a rigorous paired benchmark design (comparability screen, fixed definitions, normalization, gap, decomposition). **Empirical figures and primary sources belong in external research materials**; ambient-core supplies the metric definitions and methodology strings below.
**Setup.** Two comparable listed data-centre REITs in the same market and disclosure regime, compared under a Real Estate / REIT investor lens. Each is a **tenant org** on the platform with the same `peer_group_id`, not a single legal entity picker.
**Definitions (core).**
- Occupancy — portfolio rate with a fixed numerator/denominator boundary in upload mapping (platform enforces parity across filers).
- NOI margin — aligns with Real Estate pack semantics (net operating income relative to revenue); see Real Estate NOI methodology in the catalog.
- Investor metrics — `financial_services.reits.funds_from_operations`, `financial_services.reits.ffo_payout_ratio`, `financial_services.reits.same_store_noi_growth` where the org is modeled on the REIT investor segment.
- Leverage and coverage — use `*.core.*` and REIT-appropriate financial metrics; platform reads disclosed gearing and interest coverage under harmonized definitions.
**Normalization (platform).** Common currency for cross-listing comparisons; per-megawatt energy intensity when MW and cost lines are harmonized; mix index for colocation versus hyperscale weighting.
**Gap (platform).** Pace-setter identified per metric; absolute and percentage gaps computed after normalization.
**Decomposition (platform).** Example narrative for a large NOI margin gap: portion attributed to **structural** portfolio mix or non-comparable cost boundaries; residual attributed to **improvable** operating discipline (for example power usage effectiveness and procurement) where operational inputs exist. A distribution-per-unit gap may be decomposed through occupancy and same-store NOI, operating cost intensity, and financing structure—each sub-metric tied to catalog keys or declared inputs.
**Improvement (platform).** Improvable slices become opportunities with confidence scores; practices are assessed for fit before transfer, consistent with theory-aware benchmarking (visible results depend on underlying systems, not copy-paste KPIs).
## Future use cases (same lifecycle)
- Widen REIT compare to a **peer set** with frontier efficiency methods at platform scale.
- Insurance LOB segments (`property_casualty`, `life`, …) with official industry codes and peer cohorts per org lens.
- Aviation network carriers on CASM, RASM, and load factor versus `aviation_network_carrier` profile peers.
- Multimodal transportation orgs on `road_freight` versus `maritime_shipping` profiles without mixing modal definitions.
Optional future core enhancements (not required for the lifecycle doc): export calc dependency graphs in `manifest.json`; a neutral `benchmark-gap-v1` contract if gap tables should be governed in git.
## Related
- [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md) — hub for benchmarking, assurance, and disclosure cycles
- [governed-data.md](/docs/open-core/governed-data/) — catalog vs contracts; analysis lens and tenancy
- [catalog-consumption.md](/docs/open-core/catalog-consumption/) — manifest, segment filtering, metadata conventions
- [CORE_VS_PLATFORM.md](/docs/open-core/core-vs-platform/) — what is not in OSS
- [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md) — metric to Gold product links
- [AGENTS.md](https://github.com/Ambient-Team/ambient-core/blob/main/AGENTS.md) — one analysis lens per agent run
- [catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md) — benchmarks.yaml and terminology
---
*Canonical source: `ambient-core` at `docs/benchmarking-lifecycle.md` (sync ref `fc353f3`).*
---
## open-core/catalog-consumption.md
# Catalog consumption (integrators)
Authoring and generator commands live in [catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md). This page explains **how to read** catalog output in apps, jobs, and agents. For contracts and shared env vars, see [governed-data.md](/docs/open-core/governed-data/). When **authoring** YAML, use catalogue keys and ids per [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md).
## When to use what
- **List or resolve KPI definitions** — generated **manifest** via `ambient_contracts.catalog_manifest.load_manifest()` → `catalog/manifest.json`. The loader parses JSON once and returns a typed **`CatalogManifest`** (`ambient_contracts.manifest_models`); use `manifest.metrics`, `manifest.resolve_metric(id)`, or `CatalogMetric.to_tool_dict()` when you need the same camelCase objects as the raw file.
- **Agent tools `catalog_list_metrics` / `catalog_resolve_metric`** — same manifest; see [lib/ambient_cli/tools.py](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_cli/tools.py)
- **Upload column mapping, data-option templates, bronze field rules** — industry YAML under `catalog/industries//` via `ambient_pipeline.catalog_loader.load_data_option()` (falls back to `manifest.json` for expanded shared options)
- **Front-end industry picker, metric browser, enrichment** — generated JS in `catalog/runtime/*.js` (e.g. `catalogIndustries.js`)
- **Link a catalog metric to a governed Gold contract** — [catalog/crosswalk.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/crosswalk.yaml); see [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md)
The manifest is the **stable JSON export** for machines; industry YAML is the **editable source** for vertical-specific metrics and `dataOptions`. Generated **`catalog/runtime/*.js`** mirrors the same semantics for front-end bundlers — see [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md#choosing-a-format). After YAML edits, run `ambient-catalog-generate` so `manifest.json` and `runtime/` stay in sync.
## Path resolution
Set `AMBIENT_CATALOG_DIR` to a directory that contains `manifest.json`, or run from a full ambient-core checkout. `AMBIENT_CORE_ROOT` also enables discovery via [lib/ambient_contracts/paths.py](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_contracts/paths.py).
Wheel-only pip installs include bundled **contracts**, not the full catalog tree — submodule or `AMBIENT_CATALOG_DIR` is required for manifest-driven features.
## Manifest glossary
Top-level keys in [catalog/manifest.json](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/manifest.json):
- **`version`** — manifest format version
- **`industries`** — registered verticals (`value`, `label`, `pack` filename)
- **`metrics`** — expanded metric records (one row per vertical metric)
Common fields on each **metric** object:
- **`id`** — numeric metric id (stringified when passed to `catalog_resolve_metric`)
- **`catalogMetricKey`** — stable string key from the generator (legacy keys may appear until retired; new YAML uses `industry.segment.slug` per [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md))
- **`name`** — display name
- **`industry`** — vertical label (e.g. `Real Estate`)
- **`methodology`** — human-readable definition
- **`type`** — e.g. `Financial`, `Operational`
- **`unit`** — display unit
- **`frequency`** — calculation / reporting cadence for the KPI (for example `monthly`, `quarterly`)
- **`requiredSources`** — list of data options with `catalogOptionKey`, `name`, `fields` (field names)
- **`calc`** — the machine-readable formula (`expr` + declared `inputs`), or `null` for directly-reported metrics
- **`directlyReported`** — `true` when the metric value is uploaded directly (`input: true`, no `calc`)
- **`inputs`** — the input-coverage recipe (see below)
- **`inputCoverage`** — one-word summary of how feedable the metric is (see below)
Use `id` for agent resolve and OLAP joins; use `catalogMetricKey` for crosswalk entries and stable keys across regenerations when ids are reassigned only through controlled generator changes.
## From data options to KPIs (input coverage)
Definitions tell you *what* a metric is; the **input-coverage recipe** tells you *what to upload so `calc` actually runs*. For every metric the generator resolves each required input to the data option(s) that supply it and records the result on the metric object.
Each entry in **`inputs`** has:
- **`name`** — the input variable used by `calc.expr` (or the metric's own slug for directly-reported metrics)
- **`kind`** — `measured` (a value you supply) or `derived` (computed from another catalog metric)
- **`covered`** — whether a linked data option can supply it
- **`satisfiedBy`** — the supplying data option(s), each with `catalogOptionKey`, `name`, and a `via`:
- **`field`** — the input is an explicit, mappable column on that data option (map this column)
- **`upload`** — the input comes from that option's document/template contents rather than an enumerated field (upload that document). Accounting aggregates and ratios are intentionally not enumerated as fields — see [catalog/input_field_policy.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/input_field_policy.yaml).
The metric-level **`inputCoverage`** summarizes feedability:
- **`complete`** — every measured input is an explicit mappable field
- **`upload`** — feedable, but at least one input comes from a linked upload's document/template
- **`none`** — no data option references this metric; it cannot be fed as currently wired
- **`derived`** — computed only from other metrics (nothing to upload directly)
- **`unspecified`** — the metric declares neither `calc` nor `input`
Operator flow, then, is: pick the metric, read its `inputs`, upload each `satisfiedBy` data option (mapping `via: field` columns and attaching `via: upload` documents), run the pipeline, and the KPI computes. Run [scripts/check_metric_inputs.py](https://github.com/Ambient-Team/ambient-core/blob/main/scripts/check_metric_inputs.py) for a per-industry coverage report (which metrics are `complete` / `upload` / `none`); it is informational and does not block CI. The reverse direction (**which metrics a data option feeds**) is on each `dataOptions[].metricIds`.
## Data options: typed fields and two frequencies
Each **`dataOptions[]`** row in manifest version **3** includes:
- **`fields`** — objects `{ name, type, … }` where `type` is a catalog enum (`decimal`, `date`, `string`, …). Optional **`unit`** (for example `USD`, `seat-km`) and **`description`** (authoring hint for and integrators). YAML may still list legacy string field names; the generator normalizes them at export time. **`dummyFields` is retired** — typed `fields` is the only schema surface for uploads and Bronze mapping.
- **`fieldCoverage`** — `upload` (document/financial statement path; measured inputs via upload policy) or `enumerated` (column-mapped exports; strict validation applies). Inferred at generate time when omitted; persisted by [`scripts/harden_catalog_data_options.py`](https://github.com/Ambient-Team/ambient-core/blob/main/scripts/harden_catalog_data_options.py).
- **`collectionFrequency`** — how often the org should refresh or upload data for this template (for example `monthly`). Same concept as *source frequency* or *required upload cadence*; the YAML key is `collectionFrequency` for manifest stability.
- **`grain`** — row-level expectation for Bronze tables (`transaction`, `day`, `week`, `month`, `quarter`).
Metric **`frequency`** is the **calculation / reporting** cadence. Collection can be finer than calculation (daily feeds, monthly KPIs); the generator warns when `collectionFrequency` is coarser than the strictest linked metric `frequency`.
Generator **measured-input** checks default to **warnings** on legacy packs. **`fieldCoverage: enumerated`** options are validated strictly when you pass `--strict-data-option-inputs` (CI uses this after hardening). Run `python scripts/harden_catalog_data_options.py --write` across packs before enabling strict locally.
Bronze coercion reads manifest field types when mapping uploads — see [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md). Refresh the gap report with [scripts/audit_data_option_fields.py](https://github.com/Ambient-Team/ambient-core/blob/main/scripts/audit_data_option_fields.py) (`--markdown --report docs/catalog-input-field-gaps.md`).
## JavaScript runtime vs JSON only
- **JSON / Python backends** — `manifest.json` or `load_manifest()` (typed `CatalogManifest`) is enough for list/resolve and server-side mapping.
- **Browser or Node UI** — import generated modules from `catalog/runtime/` so industry resolution and metric keys match the generator (single bridge module in your app re-exporting from the pinned core submodule is a common pattern). Prefer JSON manifest for APIs; prefer generated `.js` when the app already bundles ES modules from core.
Hand-edit only `catalog/runtime/catalogEnrichment.js` when documented in catalog README; other `runtime/` files are generator output.
## Analysis lens and metric filtering
The core agent tool **`catalog_list_metrics`** filters manifest rows by **`industry`** (the pack display label, for example `Banking`), not by metric `segment`. For a business-line tenant org, your platform should further filter the manifest (or industry YAML) by **segment** and by **`industryCodes`** from each pack’s `pack.yaml` / manifest industry row so users only see KPIs for that org’s lens. Peer comparison should use the same official code cohort, not the legal entity’s marketing name. See [catalog-industry-coverage.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog-industry-coverage.md).
### Recommended `AgentRunContext.metadata` keys (platform convention)
Core does not validate these; document them in your worker so synthesis and logging stay consistent:
- **`org_id`** — tenant organization (required for production attribution).
- **`catalog_industry`** — resolved pack label for this org’s lens.
- **`industry_code_system`** — optional: `isic` | `naics` | `nace` | `gics` (which taxonomy the tenant treats as primary for cohorting).
- **`industry_code_primary`** — optional primary code from the pack’s manifest `industryCodes` block for that system.
- **`peer_group_id`** — platform-defined cohort for benchmarking.
- **`assurance_framework`** or **`control_pack_id`** — assurance scope.
- **`disclosure_mandate_id`** — investor or exchange mandate set.
- **`investor_audience`** — coarse audience (listed, LP, lender, internal).
- **`plan_version_id`** — budget or forecast version for variance.
- **`scenario_id`** — plan scenario label.
- **`reporting_group_id`** — optional link to a legal or group holding company for rollup UI only; does not change catalog resolution in core.
See [governed-data.md](/docs/open-core/governed-data/#analysis-lens-and-multi-org-tenancy), [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md), and [catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md#terminology).
## Related
- [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md) — metric → contract links
- [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md) — catalogue keys and formats
- [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md) — bronze mapping using catalog loaders
- [INTEGRATING.md](/docs/open-core/integrating/) — pin and env vars in monorepos
---
*Canonical source: `ambient-core` at `docs/catalog-consumption.md` (sync ref `fc353f3`).*
---
## open-core/core-vs-platform.md
# Foundation vs full product
What you get from **this repository alone** versus what belongs in a **separate application repository** (UI, deploy, tenancy, operator secrets). Ecosystem context: [ECOSYSTEM.md](https://github.com/Ambient-Team/ambient-core/blob/main/ECOSYSTEM.md).
## With only this repository
- Validate and load **data-product contracts** (`validate-contracts`, `ambient_contracts`).
- Author and generate the **reference catalog** (`ambient-catalog-generate`, `catalog/manifest.json`, `catalog/runtime/` JS).
- Run the **free Colab / pandas** path ([Colab entry](https://colab.research.google.com/drive/1RUficLuL14xLSozVPBjpSeBKT6_wGxG2), `ambient_pipeline/colab_smoke.py`) with samples from the website zip ([ambient-core-demo-samples-v1.zip](https://ambientsystems.ai/downloads/ambient-core-demo-samples-v1.zip)) — **storage = none** in this repo (`data/raw/.gitkeep` only). [Drive](https://drive.google.com/drive/folders/1YTmpKrb5J2hqdiD3GJI2cGmFA2cRA1Ne) remains a runnable SSOT for development. This pack is not for scale testing; enterprise deployments run scalable tests separately.
- Optionally use **Spark/Delta** helpers under `lib/ambient_pipeline/` when you install `.[pipeline]` and provide the same external CSVs.
- Fork or integrate contracts and catalog semantics without shipping a full SaaS stack.
## Not in this repository (typical downstream / commercial platform)
- **Consumption UI** (web or mobile clients), API gateways tied to a specific vendor OLTP.
- **Managed lakehouse deploy** (Databricks Asset Bundles, scheduled workspace jobs, Unity Catalog materialization).
- **App-specific pipeline glue** (Firestore sync, tenant sync IDs, cloud storage conventions)—may live beside imported `ambient_pipeline` in the consumer repo.
- **Customer-facing AI / inference / model hosting** — not shipped from this repository. Future proprietary AI/ML, if any, belongs only in the commercial platform application.
- **Business-line organizations** — splitting a conglomerate into multiple tenant orgs, each with its own catalog industry, contracts, uploads, and peer set; optional holding-company rollup is platform analytics, not a second catalog industry in core.
- **Benchmark gap decomposition and improvement workflows** — peer actuals storage, structural versus improvable waterfall/bridge UI, normalization policy, and post-benchmark action tracking on top of core metrics and contracts; see [benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/).
- **Assurance and attestation workflows** — control packs, evidence sign-off, DQ and bridge reconciliation UI, external reviewer exports; see [assurance-lifecycle.md](/docs/open-core/assurance-lifecycle/).
- **Investor disclosure and fundraising workflows** — mandate mapping, gap-to-requirement, data-room and remediation narratives; see [investor-disclosure-lifecycle.md](/docs/open-core/investor-disclosure-lifecycle/).
- **Planning and variance workflows** — plan versions, scenarios, and variance bridges vs actuals; see [planning-variance-lifecycle.md](/docs/open-core/planning-variance-lifecycle/).
- Operator secrets, billing UI, and end-to-end tests against a live multi-tenant deployment.
## Source of truth
- **Contract YAML** — `contracts/` here; bundled under `lib/ambient_contracts/bundled/` for wheels.
- **Catalog YAML** — `catalog/` here; generated JSON manifest and JS via `ambient-catalog-generate`.
- **Plain text first** — definitions and semantics live in git as YAML (and generated JSON); binary uploads and live databases are precursors or forward stores, not a second SSOT ([CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md)).
- Consumers should **not** maintain a second editable copy of `contracts/` or `catalog/`; pin a tag and use submodule checkout or `AMBIENT_CORE_ROOT` ([INTEGRATING.md](/docs/open-core/integrating/)).
- **Platform deployments** wire precursor OLTP/Bronze and forward lakehouse **instances**; core still owns the YAML definitions those stores implement.
## `commercial-usage-v1.yaml`
A **data contract** describing metering and usage shapes for BI or finance exports—not a statement that this OSS repo is a commercial product SKU.
## Read next
- [ECOSYSTEM.md](https://github.com/Ambient-Team/ambient-core/blob/main/ECOSYSTEM.md) — components and priorities
- [USAGE.md](/docs/open-core/usage/) — quick start
- [INTEGRATING.md](/docs/open-core/integrating/) — pin a release in another repo
- [CONTRIBUTING.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONTRIBUTING.md) — releases and consumer follow-up
- [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md) — naming, formats, and storage
---
*Canonical source: `ambient-core` at `docs/CORE_VS_PLATFORM.md` (sync ref `fc353f3`).*
---
## open-core/examples-pipeline.md
# Pipeline examples
## minimal_governed_data.py
Validates all contracts, loads the catalog manifest, and prints a sample metric plus the tenant-metrics contract product name and table. No Spark required.
```bash
cd ambient-core
pip install -e .
# Optional but recommended when core is a submodule:
# export AMBIENT_CORE_ROOT="$PWD"
python examples/pipeline/minimal_governed_data.py
```
For bronze mapping, provenance, and Spark validation, see [docs/pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/docs/pipeline.md), [docs/governed-data.md](/docs/open-core/governed-data/), [contracts/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md), and [docs/CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/docs/CONVENTIONS.md). Tests live under `tests/pipeline/`.
---
*Canonical source: `ambient-core` at `examples/pipeline/README.md` (sync ref `fc353f3`).*
---
## open-core/governed-data.md
# Governed data: catalog and contracts
This guide answers how **catalog** and **contracts** are used in practice and how to build on top of them without duplicating SSOT in your application repository.
Naming, integer ids, serialization formats, and where databases sit relative to git are defined in [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md). This page focuses on consumption and the end-to-end data flow.
For catalog YAML authoring, see [catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md). For contract file layout in this repo, see [contracts/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md).
## Plain text SSOT and data flow
Ambient Core owns the **middle** layer: human-authored **YAML** for contracts and catalog semantics, and machine-generated **JSON** (`catalog/manifest.json`, JSON Schemas, bronze mapping payloads) and **JavaScript** (`catalog/runtime/*.js` from `ambient-catalog-generate`). Do not maintain a second editable copy of those trees in a consumer repo — pin a tagged checkout or submodule ([INTEGRATING.md](/docs/open-core/integrating/), [CANONICAL_SCOPE.md](https://github.com/Ambient-Team/ambient-core/blob/main/CANONICAL_SCOPE.md)).
Operational databases and lakehouse Bronze are **precursors**: data is extracted to plain text (typically **CSV/TSV** or **JSON**) at the upload boundary before governance runs. Silver → Gold and similar **forward** stores are Parquet/Delta or service SQL in deployment; their shapes are still defined by YAML in `contracts/`. Details: [CONVENTIONS.md — Data formats and storage](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md#data-formats-and-storage).
```mermaid
flowchart LR
precursor[Precursor_OLTP_or_Bronze]
extract[Plain_text_extract_CSV_or_JSON]
yaml[YAML_contracts_and_catalog_in_git]
forward[Forward_Parquet_Delta]
precursor --> extract --> yaml --> forward
```
Medallion job steps that implement this path are in [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md).
## Two layers
- **Catalog** — reference KPIs, industries, data-source templates, benchmarks (semantic intent, not physical tables). SSOT: authored **YAML** under `catalog/` → generated **`manifest.json`** (JSON) and `catalog/runtime/*.js`.
- **Contracts** — governed **data-product** interfaces: schema, lineage, quality, consumption rules. SSOT: **YAML** in `contracts/` (bundled in wheels as `ambient_contracts.bundled`).
Catalog metrics do **not** replace contracts. A metric may exist in the catalog long before a Gold product is defined. Optional links are recorded in [crosswalk.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/crosswalk.yaml) — see [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md).
### Catalog fields → contracts
Manifest **v3** typed `fields` and data-option `fieldCoverage` govern **what uploads may contain** and how Bronze mapping coerces columns. **Contracts** govern **what may be written** to Silver and Gold: required columns, bronze lineage, and product governance. Typical path: catalog-mapped Bronze → [tenant-metrics-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/tenant-metrics-v1.yaml) (Silver) → vertical Gold products (`finance-*-v1`, healthcare, life sciences). Diagram and product groupings: [contracts/README.md — How catalog and contracts connect](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md#how-catalog-and-contracts-connect).
## Analysis lens and multi-org tenancy
**Catalog industry and segment** describe an **analysis lens** (which KPIs and peer comparisons apply), not the legal entity’s self-classification. **ambient-core** supplies the taxonomy: industry packs in [catalog/packs.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/packs.yaml) with `industryCodes` on each pack, metrics, benchmarks, and contracts. A **multi-tenant platform** (not in this repo) supplies `org_id`, entitlements, which catalog pack and Gold contract bind to each org, and peer cohort membership.
A single banking group on a paid platform is often modeled as **several tenant organizations**—for example owned branch real estate (Real Estate lens), consumer depository banking (Banking lens), C&I and commercial CRE lending (Commercial Finance lens), residential mortgage lender book (Consumer Finance `residential_mortgage` segment), unsecured cards (Consumer Finance `consumer_lending`), pooled or advised fund books (**Funds** lens), listed REIT or trust **vehicle** reporting (**Trusts** lens), and investment banking or fintech SaaS (Financial Services lens). Each org is compared to peers in **that** lens. Consolidated equity may move because real estate is revalued; that driver should be analyzed with real estate KPIs on the RE org, not by stretching banking metrics across the whole group. Do **not** use a legacy “REITs” industry class or `reits` segment—vehicle FFO and payout belong on **Trusts**; property NOI and vacancy belong on **Real Estate**.
**Risk and payments** are not separate catalog industries or standalone `finance-risk-v1` / payments contracts. Credit, liquidity, market, and payment-volume metrics live on the existing pack and matching `finance-*-v1` Gold product for that economic engine (for example NPL on Commercial Finance, VaR on investment banking, card volume on Consumer Finance). Institution-wide liquidity and stress metrics stay on Banking. Macro peer share and HHI across the market belong in platform benchmarking, not per-org Gold schema.
Upload fields such as `entity_segment` on some catalog data options support **segmented extracts** within a lens; they do not assert that the tenant org “is” a bank or insurer in the legal sense. Core does **not** validate tenancy or lens choice. Platform boundaries: [CORE_VS_PLATFORM.md](/docs/open-core/core-vs-platform/). Terminology: [catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md#terminology).
For **product work cycles** on the same governed metrics—**benchmarking**, **assurance**, **investor disclosure**, and **planning and variance**—core supplies definitions and contracts; the paid platform supplies workflows and UI. See [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md) and the child lifecycle docs linked from that hub.
## Path resolution
Python and CLIs resolve paths via [lib/ambient_contracts/paths.py](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_contracts/paths.py):
- **`AMBIENT_CORE_ROOT`** — repo root (submodule or clone)
- **`AMBIENT_CONTRACTS_DIR`** — override contracts directory (default: `contracts/` under root, or wheel bundle)
- **`AMBIENT_CATALOG_DIR`** — catalog tree containing `manifest.json`
**Wheel-only installs** ship bundled contracts; catalog tools and `load_manifest()` need a full checkout or `AMBIENT_CATALOG_DIR` pointing at a tree with `manifest.json`.
Set these in CI before `validate-contracts` and `ambient-catalog-generate --check` when core is a submodule — see [INTEGRATING.md](/docs/open-core/integrating/).
## How each consumer uses the same SSOT
```mermaid
flowchart TB
subgraph ssot [ambient-core SSOT]
C[contracts/*.yaml]
M[manifest.json]
end
UI[Web app / JS]
Jobs[Spark / lakehouse jobs]
UI --> M
UI --> runtime[catalog/runtime/*.js]
Jobs --> C
Jobs --> M
```
### UI and planning (JavaScript or JSON)
- Import generated modules from `catalog/runtime/` (industries, metrics, enrichment) or read `catalog/manifest.json` directly.
- Use catalog for **labels, methodology, required sources** — not for asserting warehouse table shapes.
- Field-level manifest guidance: [catalog-consumption.md](/docs/open-core/catalog-consumption/).
### Pipelines and notebooks (Python)
- **Contracts:** `ContractLoader` from `ambient_contracts` — load YAML, `assert_required_columns()` on Spark DataFrames, `enforce_bronze_lineage()` before Silver/Gold writes.
- **Catalog:** `load_manifest()` for metric lists; `ambient_pipeline.catalog_loader.load_data_option()` for upload-mapping rules tied to industry YAML; manifest v3 field types feed `coerce_mapped_columns()` in bronze mapping ([pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md)).
- **Governance helpers** (git checkout, not full wheel): `ambient_pipeline` — provenance stamping, PII pseudonymization, bronze→tenant-metrics mapping. See [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md).
Default execution is local Spark/Delta via `notebooks/` or `scripts/run_oss_bronze_silver_smoke.py`. Managed schedules, Databricks jobs, and Firestore sync live in **your application repository**; core supplies contracts, catalog semantics, reusable helpers, and the OSS demo.
## CI gates
From a core checkout:
```bash
validate-contracts
python scripts/harden_catalog_data_options.py --check
python scripts/generate_reference_catalog.py --check --strict-data-option-inputs
```
## Data-product inventory
**Silver** tenant snapshots ([tenant-metrics-v1](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/tenant-metrics-v1.yaml)), **Gold** vertical rollups (`finance-*-v1`, healthcare, life sciences, org-kpi), and **platform** products (quality, operational–financial bridge, commercial usage, pipeline observability) are defined as YAML under `contracts/`.
Full grouped inventory with scope notes: [contracts/README.md — Current data products](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md#current-data-products). Open each YAML for table names, required columns, and consumption rules. `validate-contracts` checks structural keys (`product`, `schema`, `lineage`, `governance`); deeper semantics are enforced in pipeline code and tests.
## Crosswalk
See [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md) for field definitions, the in-repo DSCR example, and maintainer workflow.
## Build on top (checklist)
1. Pin a tagged `ambient-core` release — [INTEGRATING.md](/docs/open-core/integrating/).
2. Set `AMBIENT_CORE_ROOT` / contract and catalog dirs in CI.
3. Gate merges with `validate-contracts`, catalog hardening `--check`, and `ambient-catalog-generate --check` (with strict enumerated-field validation in CI).
4. Jobs: load contracts and catalog rules in Python; do not copy YAML into app-only trees.
5. UI: consume `manifest.json` or `catalog/runtime/` from the pinned checkout.
Try the minimal Python walkthrough: [examples/pipeline/minimal_governed_data.py](https://github.com/Ambient-Team/ambient-core/blob/main/examples/pipeline/minimal_governed_data.py).
## Anti-patterns
- Maintaining a second editable `contracts/` or generated `manifest.json` outside the pinned core checkout.
- Encoding KPI definitions only in ad hoc prompts instead of catalog + contracts.
- Using `ContractLoader` with user-supplied paths without basename checks in **your** API layer.
## Related
- [catalog-consumption.md](/docs/open-core/catalog-consumption/) — manifest vs YAML vs JS runtime
- [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md) — metric → contract links
- [USAGE.md](/docs/open-core/usage/) — install recipes
- [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md) — bronze → contract flow with `ambient_pipeline`
- [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md) — catalogue keys, contract versions, formats and storage
- [CANONICAL_SCOPE.md](https://github.com/Ambient-Team/ambient-core/blob/main/CANONICAL_SCOPE.md) — what must change only here
- [CORE_VS_PLATFORM.md](/docs/open-core/core-vs-platform/) — foundation vs full product repo
---
*Canonical source: `ambient-core` at `docs/governed-data.md` (sync ref `fc353f3`).*
---
## open-core/integrating.md
# Integrating a tagged release
Use this when you embed **ambient-core** in a monorepo, fork, or product application. There is **one** canonical tree: a tagged release of **this** repository. All updates to contracts, catalog, and shared pipeline code happen here first.
Scope: [CANONICAL_SCOPE.md](https://github.com/Ambient-Team/ambient-core/blob/main/CANONICAL_SCOPE.md).
## 1. Pick a version
Choose a release tag `vX.Y.Z` from this repo’s **Releases** (or tags). Record the same tag everywhere you depend on core (pip, submodule, container build args).
## 2. Python install (required for CLIs and libraries)
```bash
pip install "ambient-core[pipeline,postgres] @ git+@vX.Y.Z"
```
Replace `` with the HTTPS git URL of **this** repository (or your fork if you maintain one). Extras: `pipeline`, `postgres`, `dev`, `all` — see [USAGE.md](/docs/open-core/usage/).
Editable install for core development:
```bash
git clone
cd ambient-core
pip install -e ".[all]"
```
## 3. Full tree (catalog JS, on-disk contracts, pipeline tests)
For repos that import `catalog/runtime/*.js` or validate against checkout paths:
```bash
git submodule add ambient-core
cd ambient-core
git fetch --tags
git checkout vX.Y.Z # detached HEAD at release tag
cd ..
git add ambient-core
```
Pin the submodule SHA in the parent commit; avoid tracking `branch = main` if you need reproducible builds.
## 4. Environment variables (monorepo)
When the parent repo is not the core repo root:
```bash
export AMBIENT_CORE_ROOT="$PWD/ambient-core"
export AMBIENT_CONTRACTS_DIR="$PWD/ambient-core/contracts"
export AMBIENT_CATALOG_DIR="$PWD/ambient-core/catalog"
```
Set these in CI before `validate-contracts` and `ambient-catalog-generate --check` so validation uses the submodule tree, not only wheel bundled data.
## 5. Verify after import or upgrade
From the core checkout (submodule or clone):
```bash
validate-contracts
ambient-catalog-generate --check
pytest # optional; Spark tests need Java and AMBIENT_SPARK_TESTS=1
```
Run your application repository’s CI as well.
## 6. Upgrade loop
1. Merge changes in **this** repository; tag `vX.Y.Z` on `main`.
2. In each consumer repo:
- Bump `ambient-core @ git+…@vX.Y.Z` in dependency files.
- `cd ambient-core && git fetch --tags && git checkout vX.Y.Z`.
- Set `AMBIENT_CORE_ROOT` in CI if used.
3. Regenerate catalog if YAML changed: `ambient-catalog-generate` (or a thin wrapper script in the consumer).
4. Run consumer CI; merge.
## Appendix A — Consumer checklist (after a core release)
- [ ] Dependency pin — `ambient-core[…] @ git+…@vX.Y.Z` matches the new tag.
- [ ] Submodule — `ambient-core/` checked out at the **same** tag SHA; parent commit records the pointer.
- [ ] CI — `AMBIENT_CORE_ROOT` (and catalog/contracts dirs) set before contract/catalog validation.
- [ ] No mirrors — no `contracts/*.yaml` or `catalog/manifest.json` outside the `ambient-core/` checkout (stub README pointers are fine).
- [ ] Authoring rules — read [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md) before changing catalog keys, contract major versions, or ingestion formats; do not use binary spreadsheets or PDFs as SSOT in the consumer repo (extract to CSV/JSON/YAML at the boundary).
- [ ] Catalog JS — import from `ambient-core/catalog/runtime/` (single bridge module in the app is a common pattern).
- [ ] Notebooks and jobs — resolve contracts under `ambient-core/contracts/`.
- [ ] Pipeline — shared modules from `ambient-core/lib`; app-only glue stays in the consumer repo.
Follow-up details: [CONTRIBUTING.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONTRIBUTING.md#consumer-follow-up-after-a-release).
## Product work cycles (platform)
If you ship workflows on governed KPIs, pin ambient-core for catalog metrics, per-pack `benchmarks.yaml`, industry packs (`industryCodes`), `ambient_calc`, and contracts (`quality-v1`, `operational-financial-bridge-v1`, and others). Implement tenancy, UI, and cycle-specific logic in your application repository:
- **Benchmarking** — peer actuals, normalization, waterfalls, improvement; [benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/).
- **Assurance** — control packs, evidence, DQ and bridge reconciliation, attestation exports; [assurance-lifecycle.md](/docs/open-core/assurance-lifecycle/).
- **Investor disclosure / fundraising** — mandate mapping, gap-to-requirement, data room; [investor-disclosure-lifecycle.md](/docs/open-core/investor-disclosure-lifecycle/).
- **Planning and variance** — budgets, scenarios, variance bridges; [planning-variance-lifecycle.md](/docs/open-core/planning-variance-lifecycle/).
Overview and metadata conventions: [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md).
---
*Canonical source: `ambient-core` at `docs/INTEGRATING.md` (sync ref `fc353f3`).*
---
## open-core/investor-disclosure-lifecycle.md
# Investor disclosure and fundraising lifecycle: core vs platform
**Investor disclosure** (and related **fundraising** readiness) is the work cycle that asks whether an organization meets **stakeholder mandates** for reporting—so capital remains available from listed markets, limited partners, sponsors, or lenders with climate or sustainability expectations. It is not the same as [benchmarking](/docs/open-core/benchmarking-lifecycle/) (peer performance) or [assurance](/docs/open-core/assurance-lifecycle/) (defensibility of numbers)—but published metrics should be traceable through assurance, and operational definitions should match those used in benchmarks.
ambient-core supplies **metric vocabulary** and contract shapes; the **paid platform** maps mandates, computes gap-to-requirement, and supports remediation narratives and data rooms.
Index of all cycles: [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md).
This document is **not legal or securities advice**; it describes product architecture only.
## End-to-end flow
```mermaid
flowchart LR
subgraph core [ambient_core_OSS]
Catalog[catalog_RE_and_REIT_metrics]
EnergyOpts[energy_data_options]
OpportunityShape[opportunity_v1]
end
subgraph platform [paid_platform]
Mandates[disclosure_mandate_mapping]
Boundary[GHG_and_scope_policy]
ReqGap[gap_vs_requirement]
DataRoom[fundraising_and_data_room]
end
Catalog --> Mandates
EnergyOpts --> Boundary
Mandates --> ReqGap
ReqGap --> DataRoom
OpportunityShape --> DataRoom
```
## Phase mapping
### 1. Audience and mandate mapping
- **Core** — Analysis lens per org ([governed-data.md](/docs/open-core/governed-data/)); industry packs and benchmark guardrails for comparison **design**, not legal obligation lists.
- **Platform** — `disclosure_mandate_id`, `investor_audience` (listed exchange, LP, sponsor, lender); checklist per jurisdiction or fund policy (for example exchange sustainability reporting expectations for listed real estate, portfolio-level carbon disclosure demanded by institutional LPs). Map mandates to catalog metric ids and contract products.
### 2. Metric pack selection
- **Core** — Real Estate operating metrics (NOI, cap rate, occupancy where defined); listed REIT investor metrics under `financial_services.reits.*` in [financial_services.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/financial_services.yaml); energy consumption fields on Real Estate data options (`energy_consumed`, `energy_cost`). Bridge rules link energy signals to financial impact narratives.
- **Platform** — Curated “investor pack” per mandate; effectiveness metrics (growth, distributions) versus efficiency and environmental intensity grouped for disclosure schedules.
**Catalog gap (v1):** There is no dedicated `sustainability` segment or native GHG metrics in core yet. Intensity-style environmental KPIs (for example per megawatt, PUE) are expected to be platform-normalized or added in a future catalog band—not invented in prompts.
### 3. Boundaries and harmonization
- **Core** — Documented methodologies and `calc` boundaries per metric; intensity metrics where authored in catalog.
- **Platform** — GHG scope boundaries, tenant versus landlord energy, currency and period alignment, restatement and versioned disclosure files.
### 4. Gap versus requirement
- **Core** — Per-industry `catalog/industries//benchmarks.yaml` healthy bands are **planning guardrails**, not exchange or LP thresholds.
- **Platform** — Required versus actual versus prior period; optional peer percentile for **narrative** only when mandate references market practice. Success criterion is **compliance or mandate gap**, not pace-setter rank.
### 5. Remediation, fundraising, and data room
- **Core** — `fpaWorkflow` hints on metrics guide where remediation recommendations map.
- **Platform** — CapEx and retrofit roadmaps, sustainability action owners, data-room exports, equity or debt storytelling tied to catalog metric keys.
## Overlap: benchmark cycle vs disclosure cycle on the same org
Run **benchmarking** when the user needs peer context and improvable decomposition (for example NOI margin versus another data-centre REIT). Run **disclosure** when the user must satisfy a **named mandate** (exchange, fund, lender) even if peers are strong or weak. The same tenant org may run both in one quarter; use separate metadata (`peer_group_id` vs `disclosure_mandate_id`) and do not treat mandate compliance as “winning” a benchmark.
Listed issuers may face **regulatory or exchange** sustainability disclosure pressure; **private** capital may impose parallel portfolio-level reporting on the same assets through LP agreements. Platform modeling as separate mandates on the same or sibling orgs under one `reporting_group_id` matches [analysis lens](/docs/open-core/governed-data/#analysis-lens-and-multi-org-tenancy) patterns.
## Illustrative data-centre REIT sketch
**Setup.** A listed data-centre REIT org under Real Estate / REIT investor lenses; a related mandate from an LP portfolio policy on energy and carbon transparency.
**Definitions (core).** Occupancy and NOI margin semantics from Real Estate pack; FFO and payout from `financial_services.reits.*`; energy uploads from Real Estate data options where available.
**Mandates (platform).** Exchange-style sustainability schedule plus fund policy fields not fully enumerated in core.
**Gap (platform).** Missing intensity metrics or undisclosed PUE where mandate requires them—gap to **requirement**, not to a peer REIT.
**Remediation (platform).** Efficiency and procurement initiatives tracked in the platform. Empirical filings and figures remain in external research or issuer disclosures.
## Related
- [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md)
- [benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/)
- [assurance-lifecycle.md](/docs/open-core/assurance-lifecycle/)
- [governed-data.md](/docs/open-core/governed-data/)
- [catalog-consumption.md](/docs/open-core/catalog-consumption/)
---
*Canonical source: `ambient-core` at `docs/investor-disclosure-lifecycle.md` (sync ref `fc353f3`).*
---
## open-core/overview.md
# Integrator overview
Docs for embedding [ambient-core](https://github.com/Ambient-Team/ambient-core) (MIT): contracts, catalog metrics and data options, and pipeline helpers. Product Command Centre how-to lives under **Operator**.
## In this section
- [Using ambient-core](/open-core/usage/) - install, extras, and quick recipes (start here for a clone or pin).
- [Integrating a tagged release](/open-core/integrating/) - pin a core tag in another repository.
- [Governed data: catalog and contracts](/open-core/governed-data/) - how catalog YAML and contracts relate.
- [Pipeline governance helpers](/open-core/pipeline/) - `ambient_pipeline` helpers and Silver/Gold order.
- [Catalog consumption](/open-core/catalog-consumption/) - load packs and map data options in code.
- [Pipeline examples](/open-core/examples-pipeline/) - worked examples.
## Reference catalog
- [Reference catalog](/catalog/) - all eighteen industry packs (ISIC, metric and data-option counts).
- [Core metrics layer](/catalog/core-metrics/) - shared templates expanded into every pack.
- [Industries](/catalog/industries/) - pack landing; open a vertical from the sidebar.
Foundation vs full product orientation: [Core vs platform](/open-core/core-vs-platform/) (under **Start Here**).
---
## open-core/pipeline.md
# Pipeline governance helpers
Ambient Core does **not** ship a medallion job runner or Databricks bundle. It ships **contracts**, **catalog** semantics, and Python modules under `lib/ambient_pipeline/` that your lakehouse jobs import. Schedules, notebooks, and deploy glue belong in your application repository.
For catalog vs contracts and path env vars, see [governed-data.md](/docs/open-core/governed-data/). Product inventory and catalog linkage: [contracts/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md). For pinning core in a monorepo, see [INTEGRATING.md](/docs/open-core/integrating/). Bronze uploads use **CSV/TSV** at the ingestion boundary; governed Gold output is typically **Parquet/Delta** in your lakehouse — see [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md#data-formats-and-storage).
**Boundary:** the **catalog** (manifest v3 and data options) defines upload field names, types, and mapping rules; **contracts** define the publishable Silver/Gold product shape that jobs must satisfy before write.
## What lives where
**In core:** `contracts/*.yaml`; `catalog/` + `manifest.json`; `ambient_pipeline` helpers; `validate-contracts` and the catalog generator CLIs.
**In your app repo:** job definitions, DABs, orchestration; tenant upload UX and entitlements; Firestore sync, OLAP queries, commercial APIs; CI that calls the same CLIs.
[observability-pipeline-v1.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/observability-pipeline-v1.yaml) describes pipeline health products and may reference SQL, bundles, or notebooks that are maintained **downstream** — treat it as the interface contract, not as code in this repo.
## Install and test
```bash
git clone
cd ambient-core
pip install -e ".[pipeline,dev]"
set AMBIENT_SPARK_TESTS=1 # Windows; use export on Unix
pytest tests/pipeline/
```
Java 17+ is required for Spark tests.
**Packaging note:** The published wheel includes `ambient_contracts`, `ambient_cli`, and `ambient_calc`. **`ambient_pipeline` requires a git checkout** (tests use `pythonpath = lib` in `pyproject.toml`). Import it from `lib/ambient_pipeline` in notebooks and jobs pinned to the same core tag.
## Typical job flow (Bronze → Silver tenant-metrics)
The steps below implement precursor → plain-text extract → YAML-governed → forward store for **Silver** [`tenant-metrics-v1.yaml`](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/tenant-metrics-v1.yaml). Gold vertical products are a separate step — see [Silver → Gold](#silver-gold-catalog-calc-and-vertical-contracts).
```mermaid
flowchart LR
Upload[Bronze CSV upload]
Map[map and coerce]
Unpivot[unpivot long metrics]
Stamp[lineage stamp]
Validate[SilverValidator optional]
Contract[ContractLoader assert]
Gold[Gold vertical tables]
Upload --> Map
Map --> Unpivot
Unpivot --> Stamp
Stamp --> Validate
Validate --> Contract
Contract --> Gold
```
**Canonical order:** map → coerce → **unpivot** → stamp → (optional validate) → contract assert → write Silver.
**Anti-pattern:** stamping provenance on **wide** mapped rows **before** unpivot. `unpivot_to_tenant_metrics` uses `stack()` and does not carry `_bronze_*` columns from a wide frame — stamp **after** unpivot (or call [`bronze_to_tenant_metrics`](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_pipeline/bronze_catalog_map.py) which encodes this order).
1. **Resolve contract** — `ContractLoader.load("tenant-metrics-v1.yaml")`. Call `enforce_bronze_lineage()` before writes that depend on bronze provenance columns.
2. **Map uploads to catalog shape** — `apply_column_mapping`, then `coerce_mapped_columns` with manifest v3 types from `catalog_types_for_option()` ([catalog_field_rules.py](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_pipeline/catalog_field_rules.py)).
3. **Unpivot to long metrics** — `unpivot_to_tenant_metrics` turns numeric catalog fields into `name` / `value` rows with stable `metric_id`.
4. **Stamp lineage** — `stamp_lineage_columns` (or `BronzeProvenanceStamper` on the long DataFrame) sets `_bronze_org_id` from `org_id`, `_bronze_row_hash`, and mapping metadata ([provenance.py](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_pipeline/provenance.py)).
5. **Validate Silver quality (optional)** — `SilverValidator` applies ISO 8000–style checks ([validation.py](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_pipeline/validation.py)).
6. **Assert schema** — `ContractLoader.assert_required_columns()` on the column set before publish.
**Orchestration helper:** `bronze_to_tenant_metrics(...)` runs steps 2–4 in order. See [tests/pipeline/test_bronze_to_tenant_metrics_contract.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_bronze_to_tenant_metrics_contract.py).
Platform-only (optional): `fetch_firestore_data_source` / `append_firestore_lineage_event` in `bronze_catalog_map.py` require Firebase secrets — not part of the OSS default path.
## Silver → Gold (catalog, calc, and vertical contracts)
Open-Source Core **does not** ship Spark jobs that write `finance-*-v1` or healthcare Gold tables. Recommended platform pattern:
1. Read Silver long metrics from `tenant-metrics-v1` shape (or query your lakehouse Silver table).
2. Evaluate catalog formulas with [`ambient_calc`](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_calc/__init__.py) (`compute_all` on manifest metrics + measured inputs).
3. Use [`catalog/crosswalk.yaml`](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/crosswalk.yaml) and [`gold_contract_map`](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_pipeline/gold_contract_map.py) to relate manifest metric keys to Gold contract columns.
4. Pivot or join into the target product schema (for example [`finance-banking-v1.yaml`](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/finance-banking-v1.yaml)), then `ContractLoader.assert_required_columns()` on that product before write.
Details: [contracts/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md), [crosswalk.md](https://github.com/Ambient-Team/ambient-core/blob/main/crosswalk.md).
Public re-exports from `ambient_pipeline`: `ContractLoader`, `BronzeProvenanceStamper`, `PiiPseudonymizer`, `SilverValidator`, plus `bronze_to_tenant_metrics`, `MappingSpec`, and mapping helpers ([`__init__.py`](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_pipeline/__init__.py)).
## Walkthrough by test module
Use these as executable recipes (run with `AMBIENT_SPARK_TESTS=1` where Spark is involved):
- [test_contracts.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_contracts.py) — load tenant-metrics contract; bronze lineage enforcement; required columns
- [test_bronze_catalog_map.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_bronze_catalog_map.py) — mapping JSON, CSV header validation, stable metric ids, coercion
- [test_bronze_to_tenant_metrics_contract.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_bronze_to_tenant_metrics_contract.py) — map → unpivot → stamp → tenant-metrics contract assert
- [test_catalog_sample_csv_bronze.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_catalog_sample_csv_bronze.py) — end-to-end bronze CSV against catalog field rules
- [test_catalog_manifest.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_catalog_manifest.py) — manifest loading in pipeline context
- [test_validation.py](https://github.com/Ambient-Team/ambient-core/blob/main/tests/pipeline/test_validation.py) — Silver validation rules
## Minimal example (no Spark)
From a core clone with `pip install -e .`:
```bash
set AMBIENT_CORE_ROOT=%CD%
python examples/pipeline/minimal_governed_data.py
```
See [examples/pipeline/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md).
## Agents and pipelines
Core agents read **metadata** via `catalog_*` and `contracts_*` tools; they do not run Spark jobs. To let an agent trigger a pipeline or read live Gold, register tools in your worker — [AGENTS.md](https://github.com/Ambient-Team/ambient-core/blob/main/AGENTS.md).
## Related
- [USAGE.md](/docs/open-core/usage/) — recipe 4 (pipeline pytest)
- [governed-data.md](/docs/open-core/governed-data/) — catalog + contracts consumption
- [contracts/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/contracts/README.md) — SSOT products and catalog → contract flow
- [catalog-consumption.md](/docs/open-core/catalog-consumption/) — manifest field rules for Bronze mapping
- [CONVENTIONS.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONVENTIONS.md) — formats, bronze boundary, forward stores
- [CORE_VS_PLATFORM.md](/docs/open-core/core-vs-platform/) — scope split
---
*Canonical source: `ambient-core` at `docs/pipeline.md` (sync ref `003ceb1`).*
---
## open-core/planning-variance-lifecycle.md
# Planning and variance lifecycle: core vs platform
**Planning and variance** asks how **actuals** compare to the organization’s own **plan**—budget, forecast, or board case—and what explains the gap. The baseline is internal intent, not a peer ([benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/)).
**FP&A close** on [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md) is the recurring rhythm (close calendar, board packs); this cycle is the **plan-vs-actual analytical product** built on the same catalog metrics.
Index: [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md).
## End-to-end flow
```mermaid
flowchart LR
subgraph core [ambient_core_OSS]
Catalog[fpaWorkflow_and_core_metrics]
Calc[ambient_calc_inputs]
end
subgraph platform [paid_platform]
Plans[plan_versions_and_scenarios]
Variance[variance_bridges]
Accountability[owners_and_commentary]
end
Catalog --> Plans
Calc --> Variance
Plans --> Variance
Variance --> Accountability
```
## Phase mapping
### 1. Metric and calendar alignment
- **Core** — `*.core.*` close metrics (margins, growth, working capital, cash flow); segment operational metrics per analysis lens; `fpaWorkflow` strings describing typical FP&A use on each row in catalog YAML.
- **Platform** — Fiscal calendar, plan version locking, mapping actuals period to plan period; metadata `plan_version_id`, optional `scenario_id` (base, upside, downside).
### 2. Plan storage and scenarios
- **Core** — No plan SSOT in ambient-core; plans are tenant data in the platform OLTP or lakehouse.
- **Platform** — Versioned budgets and forecasts at catalog metric id granularity (or mapped account trees); scenario comparison UI.
### 3. Variance computation and decomposition
- **Core** — `calc.expr` and `calc.inputs` define how a KPI is built from components; platform uses the same graph for variance bridges (price vs volume vs mix) where inputs exist.
- **Platform** — Variance waterfalls, commentary, accountability by department; not peer-ranked.
### 4. Close integration
- **Core** — Assurance and bridge products may explain why actuals moved before variance is finalized.
- **Platform** — Tie variance cycle to close status, reforecast triggers, board deck export.
## Distinct from benchmarking
Benchmarking diagnoses performance versus **external** pace-setters and improvable structural gaps. Planning variance diagnoses performance versus **yesterday’s plan**. The same metric (for example `operating_margin`) can run through both cycles in one quarter with different metadata (`peer_group_id` vs `plan_version_id`).
## Examples
- **Any lens:** Quarterly actual `revenue_growth` and `ebitda_margin` vs annual budget using `industry.core.*` metrics after catalog expansion.
- **Aviation network carrier org:** Actual CASM/RASM vs operating plan using `aviation.network_carrier.*` definitions; variance on fuel and load factor inputs.
- **Retail org:** Same-store sales growth actual vs plan using `retail.operations.same_store_sales_growth`.
## Related
- [work-cycles.md](https://github.com/Ambient-Team/ambient-core/blob/main/work-cycles.md)
- [benchmarking-lifecycle.md](/docs/open-core/benchmarking-lifecycle/)
- [catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md#terminology)
- [lib/ambient_calc](https://github.com/Ambient-Team/ambient-core/blob/main/lib/ambient_calc/__init__.py)
---
*Canonical source: `ambient-core` at `docs/planning-variance-lifecycle.md` (sync ref `fc353f3`).*
---
## open-core/usage.md
# Using ambient-core
Quick start for contracts, catalog, and governance helpers. For embedding in another repo, see [INTEGRATING.md](/docs/open-core/integrating/). Foundation vs full product: [CORE_VS_PLATFORM.md](/docs/open-core/core-vs-platform/).
## Install
**From a git clone (recommended for catalog + pipeline tests):**
```bash
git clone
cd ambient-core
py -3.12 -m venv .venv
# Windows: .venv\Scripts\activate
pip install -e ".[all]"
```
**From a pinned git URL (downstream apps):**
```bash
pip install "ambient-core[dev] @ git+@v0.3.0"
```
PyPI is **not** the documented distribution path unless publishing is added later.
**Extras:** `.[pipeline,dev]` (Spark tests, Java 17) · `.[postgres]` · `.[all]` (pipeline + postgres + dev)
## Recipes
**1. Contracts only** — validate and load data-product YAML.
```bash
pip install -e .
validate-contracts
```
- Edit `contracts/`; sync `lib/ambient_contracts/bundled/` before release (CI enforces).
- Wheel-only installs use `ambient_contracts.bundled`; override with `AMBIENT_CONTRACTS_DIR` or `AMBIENT_CORE_ROOT` (`lib/ambient_contracts/paths.py`).
**2. Catalog** — author YAML and regenerate manifest/runtime.
```bash
pip install -e .
ambient-catalog-generate
ambient-catalog-generate --check
```
- Edit `catalog/shared/` and `catalog/industries//` ([catalog/README.md](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/README.md)).
- Use `manifest.json` for pipelines; `catalog/runtime/` for JS apps.
- Set `AMBIENT_CATALOG_DIR` or run from a full checkout (`resolve_catalog_root()` in `paths.py`).
**3. Pipeline governance (Spark)** — pytest with governance modules.
```bash
pip install -e ".[pipeline,dev]"
set AMBIENT_SPARK_TESTS=1
pytest
```
- Needs Java 17+ for Spark tests.
- End-to-end narrative: [pipeline.md](https://github.com/Ambient-Team/ambient-core/blob/main/pipeline.md).
## Contributing and releases
[CONTRIBUTING.md](https://github.com/Ambient-Team/ambient-core/blob/main/CONTRIBUTING.md) — scope, workflows, tagging, consumer follow-up.
---
*Canonical source: `ambient-core` at `docs/USAGE.md` (sync ref `fc353f3`).*
---
## ops/crm-wix-dashboard.md
# CRM mutations: use Wix Dashboard
Contact CSV import, promote-from-CSV (add contacts), and member invite are **not** available on the ambientsystems.ai members CRM (`/members/crm/`). That page is a read/update board for INTERNAL operators (left contacts list with Funnel/source/STP/sequence filters, middle funnel columns, outreach tracking via the CRM BFF).
Do these in the **Wix Dashboard** instead:
- **Contacts** — import CSV / add contacts
- **Members** — invite members; set-password / roles HITL as needed
- **Roles & permissions** — Admin vs Member access (never grant Admin from the site CRM)
Site forms (Lead / Contribute) still capture into Contacts with Funnel: Leads. See [Outbound capture runbook](/ops/outbound-capture-runbook/) and [CRM operator SOP](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/CRM-OPERATOR-SOP.md).
## Account (Company) backfill (optional)
The members CRM resolves Account on load/save from native `company`, then `as_company_norm` / `as_account_domain`, then work-email host when STP left company empty. Saving the drawer writes the resolved value into native Company. A Dashboard pass is only needed if you want every empty Company filled without opening contacts in the CRM.
Repo mirror: `docs/ops/crm-wix-dashboard.md`.
---
## ops/index.md
# Site ops
Operator runbooks for the **ambientsystems.ai** marketing site (Wix Headless Forms + Contacts). These pages are wiki-authored under `wiki/docs/ops/`. Matching SSOT prose also lives in the repo under `docs/` for git-facing edits.
Command Centre product guides stay under [Operator → platform](/platform/architecture/). Do not mix product UI how-to with site capture wiring.
## In this section
- [Outbound sequence SOP](/ops/outbound-sequence-sop/) — tool roles, STP 142 filter, Funnel labels, ATP gate
- [Outbound capture runbook](/ops/outbound-capture-runbook/) — form upsert → Funnel: Leads, smoke scripts, thank-you + Make webhook HITL
- [CRM — Wix Dashboard](/ops/crm-wix-dashboard/) — CSV import, promote, and member invite (not on site CRM)
## Related (repo, not wiki)
- [CRM operator SOP](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/CRM-OPERATOR-SOP.md) — INTERNAL `/members/crm/` + Wix-hosted CRM BFF
- [Inbox and outreach](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/INBOX-AND-OUTREACH.md) — forms, UTM, outreach glue
- [docs/ README](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/README.md) — full operator file index
---
## ops/outbound-capture-runbook.md
# Outbound capture runbook (Wix Forms → Contacts)
Operator SSOT for wiring Lead ("Leave a note") and Contribute form submits into Wix Contacts with **Funnel: Leads**, then ATP-gated handoff to Make / lemlist / Instantly.
Related: [Outbound sequence SOP](/ops/outbound-sequence-sop/), [CRM operator SOP](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/CRM-OPERATOR-SOP.md), [Inbox and outreach](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/INBOX-AND-OUTREACH.md).
Repo mirror: `docs/OUTBOUND-CAPTURE-RUNBOOK.md`.
## Capture path (smallest reliable)
1. Browser submits via Headless Forms SDK (`ContactForm.astro` → `submitLeadToWixForms`).
2. Form `postSubmissionTriggers.upsertContact` creates/updates the Wix Contact (email + name mapping).
3. Upsert applies labels:
- Lead form: `website-note` + **Funnel: Leads**
- Contribute form: `website-contribute` + **Funnel: Leads**
4. INTERNAL board at `/members/crm/` shows the contact under Leads (CRM BFF).
5. Optional enrich: set **AS source channel** = `web-form` (form upsert does not write AS_* extended fields).
6. Ability to pay: operator judgment in **AS outreach notes** (and Funnel move to Qualified when cleared). Do not invent ATP from the form.
Canonical form IDs (also in `src/config/wix.ts` / `scripts/wix-site-policy.mjs`):
- Lead: `eff382b4-4245-4ce7-aee6-39c9b25db6dc`
- Contribute: `e10a9a3e-6ecb-4986-b4ef-dbf3c34fa574`
Site forms must stay **enabled**. Site env: `PUBLIC_LEAD_FORM_ENABLED=true` (never ship disabled commercial forms without an explicit operator decision). Never put `WIX_API_KEY` in `PUBLIC_*`.
## Scripts (this repo)
Auth: GitHub / Cursor secret `WIX_API_KEY` (preferred), or `wix login` then CLI token. Never put the key in `PUBLIC_*` or commit it to `.env`.
```bash
# Idempotent: ensure Funnel + website-* labels exist; patch both forms' upsertContact
npm run wix:outbound-capture:ensure
# Dry-run
node scripts/wix-outbound-capture-ensure.mjs --dry-run
# Verify form wiring (enabled + required labels)
npm run wix:outbound-capture:smoke
# After a real test submit, confirm the contact
node scripts/wix-outbound-capture-smoke.mjs --email=you+test@example.com
# Set AS source channel = web-form when empty (dry-run default)
npm run wix:outbound-capture:enrich
node scripts/wix-outbound-capture-enrich.mjs --apply --limit=25
# Pure helper self-test (no Wix auth)
npm run test:outbound-capture
```
Form create scripts (`wix-create-lead-form.mjs`, `wix-create-opensource-form.mjs`) should leave upsertContact labels non-empty after ensure; re-run ensure after recreating a form.
### Ivan HITL — when Cursor / agent lacks `WIX_API_KEY`
Agents without the secret cannot call Forms/Contacts admin APIs. **Do not** compensate by blasting many production form submits. Prefer the API smoke path below on a machine that has the key (local shell, Actions, or Cursor env secret for site `0b498e2e-d8ea-4bec-9d56-1d4b74845393`).
```bash
cd /path/to/ambientsystems.ai
export WIX_API_KEY='…' # same secret as CI Deploy Wix / CRM BFF bake
npm run wix:outbound-capture:ensure
npm run wix:outbound-capture:smoke
# Expect both forms: enabled true, ok true, Funnel: Leads label present
# Optional — one controlled UI submit, then:
node scripts/wix-outbound-capture-smoke.mjs --email=you+capture-test@example.com
# Expect hasFunnelLeads: true
```
Also add `WIX_API_KEY` to the Cursor Cloud environment secrets for this repo so future agents can run ensure/smoke without HITL.
## Smoke checklist (confirm Funnel: Leads)
1. Confirm home still exposes the form: `data-use-wix-forms="true"` and a non-empty `data-wix-form-id` on `https://www.ambientsystems.ai/`.
2. Run `npm run wix:outbound-capture:smoke` — both forms `ok: true`, `enabled: true`, labels include `custom.funnel-leads` (or the live Funnel: Leads key).
3. Submit a unique test email on home (Leave a note) or product Contribute. Wait until the UI shows success. **Do not spam** production forms — one controlled submit per verification.
4. Run `node scripts/wix-outbound-capture-smoke.mjs --email=` — expect `hasFunnelLeads: true`.
5. Optional: Dashboard Contacts or INTERNAL `/members/crm/` — contact appears under **Leads**.
6. Optional: `node scripts/wix-outbound-capture-enrich.mjs --email= --apply` — **AS source channel** becomes `web-form`.
7. ATP: leave blank / note "ATP unclear" until an operator clears ability to pay; only then move to Qualified and allow sequencer export.
Local browser submit (forms only, not label check): `npm run test:contact-form` against a running `astro` / `astro dev`.
## Wix Automations HITL — thank-you + Make webhook
**No `wix:outbound-capture:ensure` for thank-you mail.** Automations V2 REST exists (`/automations-service/v2/automations`), but wiring a send-email thank-you needs verified sender, email template/body mapping, `SCOPE.CRM.SETUP-AUTOMATIONS`, and Validate-before-activate — none of that is in the existing form/label scripts. **Do not** add a half-baked ensure script here. Author thank-you + Make in the Wix Dashboard (**Automations**) until an operator deliberately scopes an Automations ensure. Keep scenario URLs and secrets in hub local notes (`commercial/local/`) / 1Password, never in `PUBLIC_*` or marketing copy.
Form schema `automationId` (printed by smoke) is the Forms app association — it is **not** proof a thank-you email automation exists.
Dashboard: https://manage.wix.com/dashboard/0b498e2e-d8ea-4bec-9d56-1d4b74845393/triggers
### A — Thank-you email (submitter confirmation)
Do this first. It does **not** require ATP and must not enroll sequencers.
1. Wix Dashboard → **Automations** (link above) → create or edit automation for **Wix Forms** submission on Lead and/or Contribute (form IDs above). Prefer one automation per form if the UI forces a single form trigger.
2. **Trigger:** Form submitted / `wix_form_app-form_submitted` filtered to the Lead or Contribute form id.
3. **Action:** Send email (Wix Emails / verified sender domain) to the submitter.
4. **Copy:** short confirmation only (received + next step is human review). No pricing, no pilot claims, no "we will enroll you in outreach."
5. **From:** company verified sender (Settings → Emails). Confirm domain authentication before relying on deliverability.
6. **Test:** one disposable submit → inbox receive. Check spam once. Confirm no second automation also sends a duplicate thank-you.
7. **Record:** automation name + ID in hub local notes.
### B — Form submission → Make (capture fan-out, HITL)
1. Create Make scenario in the **company** workspace (not a personal throwaway). Webhook module first; store URL in 1Password / hub local.
2. Wix Automations → trigger on the same form submit (or sibling automation).
3. **Action:** Webhook POST to Make. Map payload: email, form id / name, submission id, contact id if present, label keys, timestamp.
4. **Make filter (required):** continue only if contact has **Funnel: Leads** (or `website-note` / `website-contribute`). Drop honeypot / empty email / obvious spam.
5. **Downstream (default off):** log to a sheet or notify Slack/email for INTERNAL review. Do **not** auto-create lemlist/Instantly leads from Stub B until ATP is cleared.
6. **HITL gate:** operator reviews Make (or CRM board) before any sequencer action. Document who owns the review in hub local.
7. **Test:** one disposable email; confirm Make receives payload; confirm sequencer remains empty.
### C — ATP gate → lemlist or Instantly
- **Trigger:** Make schedule or Wix contact label change to **Funnel: Qualified** (ATP cleared), not raw form submit.
- **Filter:** AS source / STP bucket acceptable; **AS outreach notes** show ATP cleared; cooldown empty or past.
- **Action:** Create/update lead in lemlist **or** Instantly campaign (company account only). Sequencer is not the funnel SSOT — mirror stage on Wix Funnel labels.
- **Do not:** auto-push every website-note into cold sequences.
### D — Stage change fan-out (optional)
- **Trigger:** Contact label updated (Funnel:*).
- **Action:** Make webhook → update sequencer status / pause on Parked / Closed.
### Operator checklist (thank-you + Make)
Use this as the close-out list after form capture smoke is green:
1. [ ] Thank-you automation exists for Lead form; verified sender; one test receive OK
2. [ ] Thank-you automation exists for Contribute form (or shared rule covers both); no duplicate sends
3. [ ] Make scenario created in company workspace; webhook URL stored in hub local / 1Password (not git)
4. [ ] Wix Automations webhook attached to form submit; payload maps email + form id + labels
5. [ ] Make filter requires Funnel: Leads (or website-* labels); spam path drops
6. [ ] Default Make path stops at notify / log — **no** lemlist/Instantly enroll until Qualified + ATP note
7. [ ] Qualified → sequencer path (Stub C) documented separately; ATP still operator judgment
8. [ ] Concrete automation + Make scenario IDs recorded only in hub local notes
9. [ ] Forms remain **enabled** on production home / product after testing
## Anti-patterns
- Cloudflare Workers CRM path (retired)
- `WIX_API_KEY` in `PUBLIC_*` or browser bundles
- Auto-enrolling form leads into lemlist/Instantly without ATP
- Disabling home Lead / Contribute forms without an explicit operator decision
- Inventing weekly reply metrics or throwaway demo accounts
- Shipping thank-you copy that promises outreach enrollment or pricing
---
## ops/outbound-sequence-sop.md
# Outbound sequence SOP
Operator SSOT for Ambient Systems outreach on the marketing site stack. No fake weekly metrics. No invented account creation. Ability to pay before launch is the commercial filter.
Related: [Outbound capture runbook](/ops/outbound-capture-runbook/), [CRM operator SOP](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/CRM-OPERATOR-SOP.md), [Inbox and outreach](https://github.com/Ambient-Team/ambientsystems.ai/blob/main/docs/INBOX-AND-OUTREACH.md). Hub pack: `commercial/contacts-stp/` (live A = 142 finance FP&A overlap; people_master ~7k is not the refill pool).
Repo mirror: `docs/OUTBOUND-SEQUENCE-SOP.md`.
## Tool roles (do not blur)
- **Wix (Headless site + Contacts + Forms)** — Capture, CRM board, warm email/call task labels, webhook fan-out when Automations are wired. Browser never gets `WIX_API_KEY` in `PUBLIC_*`. Same-origin CRM BFF (`/api/crm/*`) is the Contacts path for INTERNAL members.
- **lemlist or Instantly + Make** — ATP-qualified cold/warm email and LinkedIn sequences only after ability-to-pay / STP qualification. Export or sync from Wix Contacts (or hub STP CSVs) into the sequencer; do not treat the sequencer as the system of record for funnel stage.
- **X (Twitter)** — Manual only. Track handle on `as_x_handle` when known; no bulk API automation required for v1.
- **Hub local** — Pre-lead staging, STP CSVs, and operator notes stay outside public git (hub `commercial/local/`, `contacts-stp/`).
Do not create throwaway Wix / lemlist / Instantly accounts for demos. Use the existing company accounts and Cursor env secrets only.
## Who to work
1. **Primary:** STP A overlap (HubSpot ∩ campaign) — live **A = 142** finance FP&A contacts.
2. **Filter:** Ability to pay before launch (operator judgment + notes). Park or nurture when ATP is unclear.
3. **Do not:** Refill sequences from the ~7k people_master just to keep volume up.
4. **Pilot cadence:** Run **10–20 of the 142** at a time for STP sequencing. Expand only after reply / meeting quality is visible.
## Funnel label mapping (Wix Contacts)
INTERNAL board columns use Contact labels:
- **Funnel: Leads** — In pool; not yet in active validation conversation
- **Funnel: Validation** — Discovery / validation thread live
- **Funnel: Qualified** — ATP cleared for a bounded next step
- **Funnel: Closed** — Won / customer / subscriber outcome
- **Funnel: Parked** — Drop-off, cooldown after Professional Breakup, or churned
Cadence days (1 / 3 / 4 / 6 / 8 / 10 / 14) live on **AS sequence step**, not as extra funnel columns. After breakup / exit: set **AS cooldown until** (last touch + 90 days), then re-engagement or nurture — never the same Day 1–14 without a new hook.
Admin-labeled contacts are operators, not outreach rows.
## Sequence sketch (ATP-qualified only)
1. Confirm STP source / bucket and ATP notes on the Wix contact.
2. Push or sync into lemlist|Instantly (+ Make if bridging LinkedIn tasks).
3. Run Day 1–14 steps; stop on reply or meeting (`AS outcome`).
4. Mirror stage moves on the INTERNAL Funnel board.
5. X touches stay manual; log channel on **AS last channel** when used.
6. Warm email / call tasks that must stay inside Wix: use Automations or operator HITL — do not invent a second CRM.
## Day-by-day copy templates (paste into lemlist / Instantly)
Draft text for ATP-qualified STP contacts only. Personalize `{{firstName}}`, `{{company}}`, and one concrete FP&A pain from research. Do not invent metrics, customers, or pricing. Stop the sequence on reply or meeting. Do not create throwaway sequencer accounts - paste into the company lemlist / Instantly workspace after HITL login.
### Day 1 - Email
- **Subject:** Contract-backed Gold for FP&A at `{{company}}`
- **Body:**
```
{{firstName}} -
Reworking board and close numbers after the lakehouse was supposed to be authoritative is the failure mode we fix.
Ambient ships contract-backed Gold for FP&A and ops: ODCS-shaped contracts, Unity Catalog governance, consumption adapters. Gold does not leave without a contract. Ambient Core (MIT) is inspectable on GitHub.
If ability to pay before launch is real for a bounded validation, reply with a work email and the metric set you defend today. If not a fit, say so and I will close the thread.
Ivan Damnjanovic
Ambient Systems
https://www.ambientsystems.ai/
```
### Day 3 - LinkedIn (connection or note)
```
{{firstName}} - short note on contract-backed Gold for FP&A (lineage + ODCS contracts, not another dashboard). Happy to share the public Ambient Core contracts if useful. No pitch deck required.
```
### Day 4 - Email (bump)
- **Subject:** Re: Contract-backed Gold for FP&A at `{{company}}`
- **Body:**
```
{{firstName}} -
Quick bump. If you already have a governed Gold path you trust under audit, ignore this.
If rework after close is still eating calendar, the next step is a short validation conversation - ability to pay before launch is the filter, not a price sheet. Ambient Core contracts stay public either way: https://github.com/Ambient-Team/ambient-core
Ivan
```
### Day 6 - Call task (Wix / operator)
- **Goal:** 5-minute ATP screen, not a demo dump.
- **Opener:** "Calling about FP&A Gold contracts - is rework after close still a live problem for `{{company}}`?"
- **If yes:** Confirm buyer / budget path and book a validation note (Members for approved accounts).
- **If unclear ATP:** Park / nurture. Do not push into lemlist Day 8+.
- **If no:** Professional Breakup path; set **AS cooldown until** (+90 days).
- **Log:** AS last channel = call; update Funnel label.
### Day 8 - LinkedIn (value, no ask spam)
```
{{firstName}} - one concrete detail: we keep Agency / Advisory (cash, controls, TCO, audit review) as a separate SKU from product Gold. If your need is advisory-only, say so and I will route that instead of a platform validation.
```
### Day 10 - Email (breakup foreshadow)
- **Subject:** Close the loop?
- **Body:**
```
{{firstName}} -
I will close this thread after one more note unless validation is useful.
What we offer: invitation-only review of contract-backed Gold for FP&A, scoped to ability to pay before launch. What we do not offer: public list pricing, Canada/Serbia/memoir framing, or dashboard-agency staffing pitches.
Reply "interested" with context, or "not now" and I will stop.
Ivan
```
### Day 14 - Email (Professional Breakup)
- **Subject:** Closing the thread
- **Body:**
```
{{firstName}} -
Closing the outreach thread on my side. If FP&A Gold contracts become relevant later, leave a note at https://www.ambientsystems.ai/contact/index.html or reply here.
Ivan Damnjanovic
Ambient Systems
```
After Day 14: set **Funnel: Parked**, **AS cooldown until** = last touch + 90 days. Never restart Day 1–14 without a new hook.
## Webhooks
Prefer Wix Automations → Make (or equivalent) for form capture and stage change fan-out. Keep secrets in CI / Cursor env, never in `PUBLIC_*`. Document concrete Make scenarios in hub local notes — not in public marketing copy.
Operational capture (form → Contacts **Funnel: Leads**, thank-you + Make HITL, smoke checklist): [Outbound capture runbook](/ops/outbound-capture-runbook/). Run `npm run wix:outbound-capture:ensure` then `npm run wix:outbound-capture:smoke`.
## Anti-patterns
- Merging Agency / Advisory consulting into the product Gold hero
- Canada / Serbia / memoir framing on company surfaces
- Fake weekly dashboards or invented reply rates
- Cloudflare Workers CRM path (retired; Wix-hosted `dist-server` only)
- Shipping empty form IDs or disabling commercial forms without an explicit operator decision
- Putting `WIX_API_KEY` in `PUBLIC_*` or auto-pushing form leads into lemlist/Instantly before ATP
## Post-deploy checks (site)
```bash
curl -sI -L https://www.ambientsystems.ai/agency | head -20
curl -sI -L https://www.ambientsystems.ai/agency/ | head -20
curl -sI -L https://www.ambientsystems.ai/advisory | head -20
curl -sI -L https://www.ambientsystems.ai/advisory/ | head -20
curl -sI -L https://www.ambientsystems.ai/product | head -20
curl -sI -L https://www.ambientsystems.ai/enterprise | head -20
curl -sI -L https://www.ambientsystems.ai/zh-hk/ | head -20
curl -sI -L https://www.ambientsystems.ai/docs/ops/outbound-sequence-sop/ | head -20
curl -sI -L https://www.ambientsystems.ai/docs/ops/outbound-capture-runbook/ | head -20
curl -sL https://www.ambientsystems.ai/sitemap-index.xml | head -40
curl -sL https://www.ambientsystems.ai/robots.txt | head -40
```
Expect HTML (pretty URL 302 → `…/index.html` via dist-server when CDN strip-slash applies), same pattern as `/product`. `/enterprise` and `/zh-hk` must resolve to real HTML (not JSON `not_found`). Ops wiki pages should return **200**.
If `/robots.txt` or `/sitemap.xml` still show Wix SEO Tools "pricing-plans" stubs, that is HITL in the Wix Robots.txt / Sitemap editor — code-owned discovery remains `/sitemap-index.xml` and `/sitemap-0.xml`.
---
## platform/agents-in-workspace.md
# Agents in the workspace
Ambient Systems does **not** ship customer-facing AI or agent panels in the workspace today. Internal engineering may use Cursor Agent / IDE for development only.
Future patented proprietary AI/ML, if any, would ship in the commercial platform application — not in MIT ambient-core, and not as resale of third-party models.
## Related
- [Using the platform](/platform/architecture/)
- [Platform features](/platform/features/)
---
## platform/ambient-core.md
# Ambient Core in the platform
The Command Centre is built on a **tag-pinned** [ambient-core](https://github.com/Ambient-Team/ambient-core) release: contracts, reference catalog, and shared pipeline libraries. The platform adds multi-tenant OLTP, lakehouse automation, and hosted services—it does not fork or mirror core trees in duplicate.
Metric equations and pack definitions are documented only under **Integrator** ([Reference catalog](/catalog/), [Core metrics](/catalog/core-metrics/)). This Operator page describes how the product consumes that pin.
## What comes from open-source core
- **Catalog** — Industry packs, metrics, data options—onboarding and Data library (definitions: [Reference catalog](/catalog/))
- **Contracts** — Governed data product schemas validated in CI and at runtime
- **Pipeline libraries** — Shared medallion and contract-loading helpers in analytical jobs
Customer-facing AI is not shipped from MIT ambient-core or as a current platform product feature.
## Upgrade discipline
Category 1 operators coordinate core tag bumps with contract validation, catalog regeneration, and deploy. Integrators follow [Integrating](/open-core/integrating/) in their own repositories.
## Related
- [Core vs platform](/open-core/core-vs-platform/)
- [Catalog consumption](/open-core/catalog-consumption/)
- [Using the platform](/platform/architecture/)
---
## platform/architecture.md
# Using the platform
Guides for **operators and power users** with access to the Ambient Command Centre. Metric equations live under **Integrator**; this section covers product behavior.
## In this section
- [Using the platform](/platform/architecture/) - this overview (after-login map and data flow below).
- [Platform features](/platform/features/) - feature index and guide status.
- [Organizations and member roles](/platform/organizations-and-roles/)
- [Hosted pipeline](/platform/hosted-pipeline/)
- [Overview dashboards](/platform/overview-dashboards/)
- [FP&A workspace](/platform/fpa-workspace/)
- [Data hub](/platform/data-hub/)
- [Managed connectors](/platform/managed-connectors/)
- [Governed metrics in the app](/platform/governed-metrics-in-app/)
- [Reporting and exports](/platform/reporting-and-exports/)
- [Usage gates](/platform/usage-gates/)
- [Bridge and optimization](/platform/bridge-and-optimization/)
- [Lineage and compliance](/platform/lineage-and-compliance/)
- [Agents in the workspace](/platform/agents-in-workspace/)
- [Workspace demos](/use-cases/) - screenshot walkthroughs by industry.
Open-Source Core pin in the product: [Ambient Core in the platform](/platform/ambient-core/) (under **Start Here**).
## What you see after login
Each **organization** (tenant) has its own governed workspace. During onboarding you choose an **industry pack** from the Ambient Core catalog - that vertical sets default KPIs, suggested **data options** (dataset templates), and FP&A workspace lenses.
Typical areas in the Command Centre:
- **Onboarding** - confirm organization profile, industry pack, and initial data connections.
- **Overview** - executive snapshot of tracked metrics and recent activity.
- **FP&A Workspace** - planning, variance, and industry-specific KPI views for your pack.
- **Data hub** - map catalog **data options** to uploads, track fulfillment status, and open source detail.
## From data options to KPIs
Catalog **metrics** and **data options** are defined under **Integrator** ([Reference catalog](/catalog/)). Operator docs do not restate equations. In the app, metrics label what Overview and FP&A show; data options are the dataset templates you fulfill in Data hub.
Typical path for a derived KPI:
1. Pick the **data option** your pack expects (see [Reference catalog](/catalog/) and the pack Data options section).
2. Upload or enter data in the **Data hub** and complete field mapping for your organization.
3. The **hosted pipeline** validates against governed products and publishes **Gold** outputs for your org.
4. **Overview** and **FP&A Workspace** read those governed results (Core calc expressions run in the pipeline - not redefined here).
If a KPI stays empty, confirm the linked data option is fulfilled and pipeline status is healthy - see [Data hub](/platform/data-hub/) and [Hosted pipeline](/platform/hosted-pipeline/).
## How data flows (conceptual)
```mermaid
flowchart LR
uploads[Your uploads and connectors]
processing[Governed processing]
gold[Governed Gold products]
mirror[In-app mirror]
ui[Command Centre]
uploads --> processing --> gold --> mirror --> ui
```
1. **Upload or connect** - files and connector feeds are scoped to your organization.
2. **Processing** - governed jobs validate and transform data into analytical products.
3. **Gold products** - curated metrics and tables your organization is allowed to consume.
4. **In-app mirror** - low-latency views for Overview, FP&A, and Data hub.
5. **External BI** (optional) - approved sharing paths for Tableau, Power BI, or similar.
## Three planes (do not conflate them)
- **Reference catalog** - KPI definitions, methodologies, calc expressions, and data options (Integrator SSOT). Touch via onboarding, Data hub, and [Reference catalog](/catalog/).
- **Contracts** - Governed data products (schemas, lineage, SLAs). Touch via pipeline status, org data panels, assurance workflows.
- **Gold** - Computed analytical outputs. Touch via Overview, FP&A Workspace, external BI when enabled.
Changing a catalog metric definition is not the same as changing a Gold value - catalog drives templates and labels; Gold holds computed results for your org.
## Open-Source Core vs this product
Integrators embed [ambient-core](https://github.com/Ambient-Team/ambient-core) (MIT) in their own stacks. The commercial Command Centre adds multi-tenant hosting, the medallion pipeline, and workspace features on top of the same catalog and contracts story. Comparison: [Core vs platform](/open-core/core-vs-platform/).
---
## platform/bridge-and-optimization.md
# Bridge and optimization
**Operational–financial bridge** and **optimization** Gold products connect operational signals to financial KPIs and advanced planning scenarios. Availability depends on your industry pack and commercial entitlements—not the limited hosted evaluation tier.
## Who can use it
Finance and operations leaders on full platform tiers; not included in severely scoped open evaluation.
## How to
:::note[Instructions coming soon]
Bridge dashboards and optimization workflows will be documented from demos.
:::
- [ ] Confirm entitlements in organization settings when hosted limits apply
- [ ] Open bridge or optimization views when enabled
- [ ] Relate outputs to [Optimization lifecycle](https://github.com/Ambient-Team/ambient-core/blob/main/docs/optimization-lifecycle.md) concepts
## Related
- [FP&A workspace](/platform/fpa-workspace/)
- [Using the platform](/platform/architecture/)
- [Core vs platform](/open-core/core-vs-platform/)
---
## platform/data-hub.md
# Data hub
The **Data hub** connects catalog **data options** to what your organization actually supplies: CSV uploads, manual entry, mapping, and **fulfillment status** before Gold metrics appear.
## Who can use it
Members who manage operational data; admins may configure which data options are in scope for the org.
## How to
:::note[Instructions coming soon]
Upload flows, field mapping, and fulfillment badges will be documented from demos.
:::
- [ ] Identify required data options for your pack ([Reference catalog](/catalog/))
- [ ] Upload or enter data and complete mapping
- [ ] Confirm fulfillment before expecting KPI updates
## Related
- [Using the platform](/platform/architecture/)
- [Hosted pipeline](/platform/hosted-pipeline/)
- [Managed connectors](/platform/managed-connectors/)
---
## platform/features.md
# Platform features
These guides explain **how to use** hosted Command Centre capabilities. Pages marked as coming soon will be filled from product demos.
| Feature | Guide |
| --- | --- |
| Organizations and member roles | [Organizations and roles](/platform/organizations-and-roles/) |
| Hosted Bronze–Silver–Gold pipeline | [Hosted pipeline](/platform/hosted-pipeline/) |
| Overview dashboards | [Overview dashboards](/platform/overview-dashboards/) |
| FP&A workspace | [FP&A workspace](/platform/fpa-workspace/) |
| Data hub | [Data hub](/platform/data-hub/) |
| Managed connector setup | [Managed connectors](/platform/managed-connectors/) |
| Governed metrics in the app | [Governed metrics in the app](/platform/governed-metrics-in-app/) |
| Reporting and exports | [Reporting and exports](/platform/reporting-and-exports/) |
| Usage gates and pipeline triggers | [Usage gates](/platform/usage-gates/) |
| Operational–financial bridge and optimization | [Bridge and optimization](/platform/bridge-and-optimization/) |
| Lineage audit and compliance pack | [Lineage and compliance](/platform/lineage-and-compliance/) |
| Agents in the workspace | [Agents in the workspace](/platform/agents-in-workspace/) |
Start with [Using the platform](/platform/architecture/) for the end-to-end data and KPI flow.
---
## platform/fpa-workspace.md
# FP&A workspace
The **FP&A Workspace** extends Overview with planning-oriented views: KPI tracking, goals, variance context, and early-access forecast features for your vertical pack.
## Who can use it
Workspace users in finance and operations roles; some forecast features may be gated by product tier.
## How to
:::note[Instructions coming soon]
Goals, forecast panels, and pack-specific lenses will be documented from demos.
:::
- [ ] Open FP&A Workspace from the main navigation
- [ ] Align KPIs with your industry pack from onboarding
- [ ] Set or review goals where enabled
## Related
- [Overview dashboards](/platform/overview-dashboards/)
- [Planning and variance lifecycle](/open-core/planning-variance-lifecycle/)
- [Using the platform](/platform/architecture/)
---
## platform/governed-metrics-in-app.md
# Governed metrics in the app
Workspace screens read **contract-backed Gold** through an in-app consumption layer—low-latency mirrors of analytical products your org is entitled to see. Values are not ad hoc queries against raw warehouse tables.
## Who can use it
All workspace users consume governed metrics through Overview, FP&A, and Data hub; entitlements follow your commercial pack.
## How to
:::note[Instructions coming soon]
Refresh behavior, stale indicators, and lineage shortcuts will be documented from demos.
:::
- [ ] Confirm pipeline published Gold for the metric
- [ ] Compare catalog definition ([Reference catalog](/catalog/)) with displayed values
- [ ] Use reporting or exports where enabled
## Related
- [Hosted pipeline](/platform/hosted-pipeline/)
- [Governed data](/open-core/governed-data/)
- [Using the platform](/platform/architecture/)
---
## platform/hosted-pipeline.md
# Hosted pipeline
The commercial platform runs a **hosted medallion pipeline** that validates uploads against governed contracts and publishes **Gold** products your workspace can read. You trigger and monitor runs from the Command Centre—not from a separate analytics console.
## Who can use it
Organization members with data permissions can see pipeline status tied to their org. Admins typically manage triggers and usage limits.
## How to
:::note[Instructions coming soon]
Run history, retry, and status panels will be documented from demos.
:::
- [ ] Confirm data hub fulfillment for required data options
- [ ] Trigger or wait for scheduled pipeline processing
- [ ] Verify Gold availability in Overview and FP&A Workspace
## Related
- [Using the platform](/platform/architecture/)
- [Data hub](/platform/data-hub/)
- [Governed metrics in the app](/platform/governed-metrics-in-app/)
- [Governed data](/open-core/governed-data/)
---
## platform/lineage-and-compliance.md
# Lineage and compliance
The **enterprise compliance pack** adds **full lineage audit** visibility from catalog definitions through pipeline stages to Gold consumption—supporting assurance and disclosure workflows.
## Who can use it
Enterprise-tier organizations; assurance and compliance roles. Not part of minimal evaluation scopes.
## How to
:::note[Instructions coming soon]
Lineage explorers and compliance exports will be documented from demos.
:::
- [ ] Open lineage views for a metric or data product
- [ ] Export audit evidence where enabled
- [ ] Pair with [Assurance lifecycle](/open-core/assurance-lifecycle/) playbooks
## Related
- [Governed metrics in the app](/platform/governed-metrics-in-app/)
- [Governed data](/open-core/governed-data/)
---
## platform/managed-connectors.md
# Managed connectors
**Managed connector setup** is request-based: your team asks Ambient to configure governed feeds into Bronze. The Command Centre does **not** offer live OAuth connector self-serve for all sources.
## Who can use it
Organization admins and data owners typically submit connector requests; members may see resulting connection status in Data hub.
## How to
:::note[Instructions coming soon]
Request forms, expected timelines, and status tracking will be documented from demos.
:::
- [ ] List data options that need a managed connector
- [ ] Submit a setup request with required metadata
- [ ] Track fulfillment alongside CSV and manual paths
## Related
- [Data hub](/platform/data-hub/)
- [Using the platform](/platform/architecture/)
---
## platform/organizations-and-roles.md
# Organizations and member roles
Multi-tenant **organizations** isolate governed data, pipeline runs, and workspace views. Members join an org with roles that control who can manage billing, data uploads, and admin settings.
## Who can use it
Organization **admins** invite members and manage commercial usage. **Members** use workspace features allowed for their role. Exact permission labels appear in the product profile and organization settings.
## How to
:::note[Instructions coming soon]
Step-by-step invites, role changes, and org switching will be added from product demos.
:::
- [ ] Create or select your organization after access is granted
- [ ] Invite members and assign roles
- [ ] Confirm pipeline and usage visibility for admins vs members
## Related
- [Using the platform](/platform/architecture/)
- [Usage gates](/platform/usage-gates/)
- [Platform features](/platform/features/)
---
## platform/overview-dashboards.md
# Overview dashboards
**Overview** is the Command Centre landing view: location-filtered **financial and operational metrics** sourced from governed Gold products for your industry pack.
## Who can use it
All organization members with workspace access can use Overview; metric visibility may depend on role and entitlements.
## How to
:::note[Instructions coming soon]
Filters, drill-down, and empty-state troubleshooting will be added from demos.
:::
- [ ] Select organization and location context
- [ ] Review KPI cards against your catalog pack
- [ ] Follow links to Data hub when metrics are missing inputs
## Related
- [Using the platform](/platform/architecture/)
- [FP&A workspace](/platform/fpa-workspace/)
- [Reference catalog](/catalog/)
---
## platform/reporting-and-exports.md
# Reporting and exports
**Standard reporting and exports** let you download **PDF** and **CSV** views of governed metrics and tables you can access in the workspace.
## Who can use it
Members with export permissions for their org; some reports may require admin or enterprise entitlements.
## How to
:::note[Instructions coming soon]
Export entry points, formats, and limits will be documented from demos.
:::
- [ ] Open the view or report to export
- [ ] Choose PDF or CSV
- [ ] Store exports according to your org’s data policy
## Related
- [Overview dashboards](/platform/overview-dashboards/)
- [FP&A workspace](/platform/fpa-workspace/)
---
## platform/usage-gates.md
# Usage gates
**Commercial usage gates** tie hosted pipeline runs and certain features to **credits** and plan entitlements. Admins see usage and limits in organization settings.
## Who can use it
Organization **admins** manage billing-related usage; members may see when actions are blocked by limits.
## How to
:::note[Instructions coming soon]
Credit balances, trigger rules, and upgrade paths will be documented from demos.
:::
- [ ] Review usage in organization admin panels
- [ ] Understand which actions consume credits or triggers
- [ ] Adjust entitlements via organization admin or invitation terms when hosted limits apply
## Related
- [Organizations and roles](/platform/organizations-and-roles/)
- [Hosted pipeline](/platform/hosted-pipeline/)
---
## use-cases/demo-provenance.md
# Demo provenance
This page records how industry demo screenshots under [Use cases](/use-cases/) were produced. **ambientsystems.ai** owns demo scenarios, mock/marketing fixtures, screenshots, and recordings used on the public site and docs.
## Capture source
- **Owner:** ambientsystems.ai (`content/industry-demos.manifest.json` is SSOT)
- **Hosted App URL:** https://ambient-fintech-platform.web.app
- **Last capture from this repo (UTC):** not yet re-captured from this repo
- **Last wiki/public sync (UTC):** 2026-09-02T22:04:19.824Z
- **Viewport:** 1440×900
## Capture environment
- Signed in as a real demo user against the **hosted** Command Centre (not a local emulator seed)
- Credentials: `DEMO_APP_EMAIL` / `DEMO_APP_PASSWORD` (operator secrets; never invent users against prod)
- Refresh from this repo: `npm run capture:demos` then `npm run import:demos`
## Imported files
- **Binary count (PNG + WebM):** 68
- **Content fingerprint (SHA-256 prefix):** `312314587a8c7d6f`
Static files live under `wiki/static/img/platform-demos/` (also mirrored to `public/collateral/demos/`) and are served at `/docs/img/platform-demos/` on the public site.
`npm run import:demos` only embeds screenshot/video markdown for binaries that exist on disk. Industries without captures keep a catalog link and a pending-capture note (no invented PNGs).
## Legacy platform import (historical)
Earlier binaries were imported from ambient-systems-platform before site ownership of demos.
- **Legacy platform git ref:** `5ec8949`
- **Legacy platform MANIFEST date:** 2026-07-03
## How to refresh
1. Ensure `DEMO_APP_EMAIL` and `DEMO_APP_PASSWORD` are set (see `.env.example` / docs/DEMO-CAPTURE.md).
2. Run `npm run capture:demos` — Playwright captures against `PUBLIC_APP_URL` or the Hosting fallback and writes PNG/WebM under `public/collateral/demos/`.
3. Run `npm run import:demos` — mirrors into wiki static, regenerates industry pages and this provenance block from the site manifest.
4. Review the diff, then commit updated binaries, wiki pages, and `content/industry-demos.manifest.json`.
`ambient-systems-platform` is commercial-only for demos. Do **not** clone it or set `PLATFORM_ROOT` to refresh marketing fixtures. Doc markdown sync (`npm run sync:docs`) remains orthogonal and may still use a platform checkout when configured.
---
## use-cases/index.md
# Use cases - workspace demos
Command Centre screenshots for each Ambient Core catalog vertical (hosted App demo). This section is the demo gallery; pack definitions (metrics, data options, and calc logic) live once in the [Reference catalog](/catalog/). [Demo provenance](/use-cases/demo-provenance/) records the hosted App capture metadata and fingerprint.
## Industry workspace demos
- [Banking (depository)](/use-cases/industries/banking/)
- [Financial Services](/use-cases/industries/financial-services/)
- [Funds](/use-cases/industries/funds/)
- [Trusts](/use-cases/industries/trusts/)
- [Insurance](/use-cases/industries/insurance/)
- [Credit Granting](/use-cases/industries/credit-granting/)
- [Software (SaaS)](/use-cases/industries/software-saas/)
- [Retail](/use-cases/industries/retail/)
- [Real Estate (commercial)](/use-cases/industries/real-estate/)
- [Manufacturing](/use-cases/industries/manufacturing/)
- [Transportation (freight)](/use-cases/industries/transportation/)
- [Passenger Transit](/use-cases/industries/passenger-transit/)
- [Aviation](/use-cases/industries/aviation/)
- [Healthcare](/use-cases/industries/healthcare/)
- [Life Sciences](/use-cases/industries/life-sciences/)
- [Restaurants](/use-cases/industries/restaurants/)
- [Vertical Farming](/use-cases/industries/vertical-farming/)
## Related
- [Reference catalog](/catalog/) - pack definitions, metrics, and data options.
- [Catalog consumption](/open-core/catalog-consumption/) - data options to KPIs.
- [Platform features](/platform/features/) - hosted Command Centre capabilities.
- [Foundation vs full product](/open-core/core-vs-platform/) - orientation under Start Here.
---
## use-cases/industries/aviation.md
# Aviation
Screenshots show the Ambient Systems Command Centre after onboarding with the **Aviation** catalog pack. The illustrative organization **SkyBridge Airways** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/aviation/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/aviation/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/aviation.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/aviation.yaml)
---
## use-cases/industries/banking.md
# Banking (depository)
Screenshots show the Ambient Systems Command Centre after onboarding with the **Banking (depository)** catalog pack. The illustrative organization **First Meridian Bank** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/banking/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/banking/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/banking.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/banking.yaml)
---
## use-cases/industries/credit-granting.md
# Credit Granting
The illustrative organization **SwiftLend Finance** is a demo persona only, not a customer reference. Pack definitions live in the Reference catalog; workspace screenshots for this vertical are pending site-owned capture.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/credit_granting/) · [Catalog consumption](/open-core/catalog-consumption/)
## Screenshots
Command Centre screenshots for this vertical are not in site collateral yet (no invented placeholders). Capture them with `npm run capture:demos` once `DEMO_APP_*` secrets are set — see [Demo provenance](/use-cases/demo-provenance/). Until then, see a captured vertical such as [Banking](/use-cases/industries/banking/) or the [Reference catalog](/catalog/industries/credit_granting/).
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/credit_granting/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/credit_granting.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/credit_granting.yaml)
---
## use-cases/industries/financial-services.md
# Financial Services
Screenshots show the Ambient Systems Command Centre after onboarding with the **Financial Services** catalog pack. The illustrative organization **Atlas Capital Partners** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/financial_services/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/financial_services/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/financial_services.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/financial_services.yaml)
---
## use-cases/industries/funds.md
# Funds
Screenshots show the Ambient Systems Command Centre after onboarding with the **Funds** catalog pack. The illustrative organization **Horizon Growth Fund** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/funds/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/funds/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/funds.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/funds.yaml)
---
## use-cases/industries/healthcare.md
# Healthcare
Screenshots show the Ambient Systems Command Centre after onboarding with the **Healthcare** catalog pack. The illustrative organization **Riverdale Health System** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/healthcare/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Screen recording
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/healthcare/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/healthcare.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/healthcare.yaml)
---
## use-cases/industries/index.md
# Industry demos
Command Centre screenshots for each Ambient Core catalog vertical (hosted App demo). Pack definitions (metrics, data options, and calc) live in the [Reference catalog](/catalog/).
See [Use cases](/use-cases/) for the full demo gallery and [Demo provenance](/use-cases/demo-provenance/) for capture metadata and fingerprint.
---
## use-cases/industries/insurance.md
# Insurance
Screenshots show the Ambient Systems Command Centre after onboarding with the **Insurance** catalog pack. The illustrative organization **Guardian Mutual Insurance** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/insurance/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/insurance/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/insurance.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/insurance.yaml)
---
## use-cases/industries/life-sciences.md
# Life Sciences
Screenshots show the Ambient Systems Command Centre after onboarding with the **Life Sciences** catalog pack. The illustrative organization **NovaGen Therapeutics** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/life_sciences/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/life_sciences/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/life_sciences.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/life_sciences.yaml)
---
## use-cases/industries/manufacturing.md
# Manufacturing
Screenshots show the Ambient Systems Command Centre after onboarding with the **Manufacturing** catalog pack. The illustrative organization **Precision Parts Co** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/manufacturing/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/manufacturing/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/manufacturing.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/manufacturing.yaml)
---
## use-cases/industries/passenger-transit.md
# Passenger Transit
The illustrative organization **Metro Transit Authority** is a demo persona only, not a customer reference. Pack definitions live in the Reference catalog; workspace screenshots for this vertical are pending site-owned capture.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/passenger_transit/) · [Catalog consumption](/open-core/catalog-consumption/)
## Screenshots
Command Centre screenshots for this vertical are not in site collateral yet (no invented placeholders). Capture them with `npm run capture:demos` once `DEMO_APP_*` secrets are set — see [Demo provenance](/use-cases/demo-provenance/). Until then, see a captured vertical such as [Banking](/use-cases/industries/banking/) or the [Reference catalog](/catalog/industries/passenger_transit/).
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/passenger_transit/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/passenger_transit.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/passenger_transit.yaml)
---
## use-cases/industries/real-estate.md
# Real Estate (commercial)
Screenshots show the Ambient Systems Command Centre after onboarding with the **Real Estate (commercial)** catalog pack. The illustrative organization **Summit Properties Group** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/real_estate/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Screen recording
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/real_estate/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/real_estate.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/real_estate.yaml)
---
## use-cases/industries/restaurants.md
# Restaurants
Screenshots show the Ambient Systems Command Centre after onboarding with the **Restaurants** catalog pack. The illustrative organization **Harbor Bistro Group** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/restaurants/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/restaurants/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/restaurants.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/restaurants.yaml)
---
## use-cases/industries/retail.md
# Retail
Screenshots show the Ambient Systems Command Centre after onboarding with the **Retail** catalog pack. The illustrative organization **Urban Retail Collective** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/retail/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/retail/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/retail.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/retail.yaml)
---
## use-cases/industries/software-saas.md
# Software (SaaS)
The illustrative organization **Nimbus Apps** is a demo persona only, not a customer reference. Pack definitions live in the Reference catalog; workspace screenshots for this vertical are pending site-owned capture.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/software_saas/) · [Catalog consumption](/open-core/catalog-consumption/)
## Screenshots
Command Centre screenshots for this vertical are not in site collateral yet (no invented placeholders). Capture them with `npm run capture:demos` once `DEMO_APP_*` secrets are set — see [Demo provenance](/use-cases/demo-provenance/). Until then, see a captured vertical such as [Banking](/use-cases/industries/banking/) or the [Reference catalog](/catalog/industries/software_saas/).
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/software_saas/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/software_saas.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/software_saas.yaml)
---
## use-cases/industries/transportation.md
# Transportation (freight)
Screenshots show the Ambient Systems Command Centre after onboarding with the **Transportation (freight)** catalog pack. The illustrative organization **Northstar Logistics** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/transportation/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/transportation/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/transportation.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/transportation.yaml)
---
## use-cases/industries/trusts.md
# Trusts
Screenshots show the Ambient Systems Command Centre after onboarding with the **Trusts** catalog pack. The illustrative organization **Legacy Family Trust** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/trusts/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/trusts/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/trusts.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/trusts.yaml)
---
## use-cases/industries/vertical-farming.md
# Vertical Farming
Screenshots show the Ambient Systems Command Centre after onboarding with the **Vertical Farming** catalog pack. The illustrative organization **GreenTower Farms** is a demo persona only, not a customer reference.
Capture uses the **hosted** Command Centre at 1440×900 as a signed-in demo user. See [Demo provenance](/use-cases/demo-provenance/) for App URL and fingerprint.
[Full metric definitions](/catalog/industries/vertical_farming/) · [Catalog consumption](/open-core/catalog-consumption/)
## Onboarding
## Overview
## FP&A Workspace
## Data library
## Catalog reference
- [Full metric definitions and calc logic](/catalog/industries/vertical_farming/) — generated from ambient-core YAML.
- [Catalog consumption](/open-core/catalog-consumption/) — how industry YAML and manifest relate to the workspace.
- Pack source (ambient-core): [catalog/industries/vertical_farming.yaml](https://github.com/Ambient-Team/ambient-core/blob/main/catalog/industries/vertical_farming.yaml)
---