@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/assets/demo/orbit/wiki/global/orbit-dbt-exposures.md

@@ -0,0 +1,44 @@
+---
+summary: "dbt exposures declared in models/exposures.yml: three dashboards (Retention Executive, Executive Revenue, Growth Activation) with their upstream mart dependencies and owners."
+usage_mode: auto
+sort_order: 0
+tags:
+  - dbt
+  - exposures
+  - dashboards
+  - orbit
+sl_refs:
+  - mart_nrr_quarterly
+  - mart_retention_movement_breakout
+  - mart_arr_daily
+  - mart_revenue_daily
+  - mart_account_activity
+---
+
+# Orbit dbt Exposures
+
+Declared in `models/exposures.yml`. All exposures are type `dashboard` with maturity `high` or `medium`.
+
+## Retention Executive Dashboard
+
+- **URL:** https://orbit-demo.example.com/dashboards/retention
+- **Maturity:** high
+- **Owner:** Analytics (analytics@orbit-demo.example.com)
+- **Depends on:** `mart_nrr_quarterly`, `mart_retention_movement_breakout`
+- **Description:** Executive retention view covering NRR and movement breakout.
+
+## Executive Revenue Dashboard
+
+- **URL:** https://orbit-demo.example.com/dashboards/revenue
+- **Maturity:** high
+- **Owner:** Finance (finance@orbit-demo.example.com)
+- **Depends on:** `mart_arr_daily`, `mart_revenue_daily`
+- **Description:** Board reporting view for ARR and gross-to-net revenue.
+
+## Growth Activation Dashboard
+
+- **URL:** https://orbit-demo.example.com/dashboards/activation
+- **Maturity:** medium
+- **Owner:** Growth (growth@orbit-demo.example.com)
+- **Depends on:** `mart_account_activity`
+- **Description:** Activation policy comparison around the January 2026 workflow update.

package/assets/demo/orbit/wiki/global/orbit-dbt-project-overview.md

@@ -0,0 +1,54 @@
+---
+summary: "Overview of the kaelio_demo dbt project: connection, schema layout, model layers, and governed metrics."
+usage_mode: auto
+sort_order: 0
+tags:
+  - dbt
+  - orbit
+  - data-model
+  - governed-metrics
+sl_refs:
+  - stg_accounts
+  - stg_contracts
+  - stg_arr_movements
+  - mart_arr_daily
+  - mart_nrr_quarterly
+  - mart_revenue_daily
+  - mart_account_activity
+  - mart_procurement_activity
+  - mart_customer_health
+  - mart_account_segments
+---
+
+# Orbit dbt Project Overview
+
+**Project name:** `kaelio_demo`
+**dbt version:** 1.0.0
+**Profile target:** Postgres (`orbit_analytics` schema, `kaelio_demo` database)
+**Raw source schema:** `orbit_raw`
+**Analytics schema:** `orbit_analytics` (all models materialised as views by default)
+
+## Model Layers
+
+| Layer | Prefix | Purpose |
+|---|---|---|
+| Staging | `stg_` | 1-to-1 with `orbit_raw` tables; adds type-casting, column tests, enum constraints |
+| Intermediate | `int_` | Business-logic joins and rollups; not exposed to BI directly |
+| Mart | `mart_` | Board/dashboard-ready aggregates; each has a `governed_metric_key` and `owner_team` |
+
+## Governed Metrics (mart layer)
+
+| Mart | `governed_metric_key` | Owner | Notion |
+|---|---|---|---|
+| `mart_arr_daily` | `arr` | finance | `notion_page_arr_contract_reporting` |
+| `mart_nrr_quarterly` | `net_revenue_retention` | analytics | `notion_page_retention_policy_current` |
+| `mart_retention_movement_breakout` | `net_revenue_retention` | analytics | `notion_page_retention_policy_current` |
+| `mart_revenue_daily` | `net_revenue` | finance | `notion_page_revenue_reporting_policy` |
+| `mart_account_activity` | `activated_accounts` | growth | `notion_page_activation_policy_decision` |
+| `mart_procurement_activity` | `weekly_active_requesters` | product | `notion_page_procurement_instrumentation` |
+| `mart_customer_health` | `active_customers` | customer_success | `notion_page_customer_health_playbook` |
+| `mart_account_segments` | `segment` | sales_ops | `notion_page_sales_ops_segmentation` |
+
+## Raw Source Tables (`orbit_raw` schema)
+
+accounts, account_hierarchy, plans, contracts, subscriptions, contract_discount_terms, arr_movements, invoices, invoice_line_items, refunds, plan_segment_mapping, users, activation_events, sessions, purchase_requests, approval_events, suppliers, supplier_onboarding_events, purchase_orders, support_tickets, account_owners.

package/assets/demo/orbit/wiki/global/orbit-how-we-work.md

@@ -0,0 +1,75 @@
+---
+summary: "Orbit operating model: remote-first, written-first, weekly rhythm, decision process, escalation policy, and standing operating norms."
+usage_mode: auto
+sort_order: 0
+tags:
+  - policy
+  - orbit
+refs:
+  - orbit-company-overview
+  - customer-communication-policy
+---
+
+## How We Work
+
+**Source:** Notion - Orbit Demo Home / How We Work, last edited 2026-05-07
+
+---
+
+## Operating Model
+
+- Orbit is a **mostly remote, mostly written** company.
+- Meetings must serve a specific purpose: making a decision, unblocking a handoff, or building shared context that writing alone would be slower to achieve.
+- If a meeting does not meet one of those three purposes, default to async written communication.
+
+---
+
+## Weekly Rhythm
+
+| Day(s) | Focus |
+|---|---|
+| **Monday** | Commitments and dependency checks |
+| **Tuesday – Thursday** | Customer calls, product work, implementation, and building |
+| **Friday** | Closing loops - review what shipped, what slipped, and write down any decisions |
+
+Use this rhythm when scheduling work, meetings, or reviews. Do not schedule decision-making meetings on Fridays; use Friday to record decisions already made.
+
+---
+
+## Decision-Making Process
+
+1. **The person closest to the work writes the recommendation.**
+2. **Stakeholders who will live with the decision get to push back.**
+3. **The accountable lead makes the call** when a real tradeoff exists.
+4. **The result is written where the work is happening.** Decisions that exist only in Slack or a meeting are not considered durable.
+
+> A decision that isn't written down didn't happen.
+
+---
+
+## Standing Operating Norms
+
+These are explicitly codified rules Orbit has identified as recurring failure modes:
+
+- **Name the accountable person before work begins.** If no one is named, no one is accountable.
+- **Never let a quick sync be the only source of truth.** Write it down after.
+- **Bring a customer example when proposing product changes.** Abstract proposals without customer grounding are harder to evaluate.
+- **Involve affected teams before a plan is finalized.** Surprises in execution are more expensive than slower planning.
+- **Prefer a rough written decision today over a perfect recap that never gets written.** Done and documented beats polished and lost.
+
+---
+
+## Escalation Policy
+
+- **Escalations are coordination tools, not indicators of individual failure.** Escalating is the correct behavior when a problem exceeds the current team's ability to resolve it alone.
+- When escalating, the person escalating must:
+  1. Bring in the right people (those with authority or context to unblock).
+  2. Summarize current state clearly - what has been tried, what is blocked, and why.
+  3. Name the customer impact explicitly.
+  4. Keep updates moving until the risk is resolved or a workaround is established.
+- Escalations that stall because no one owns the next update are a process failure, not a customer failure.
+- An escalation is closed when the risk is resolved or a documented workaround is in place - not when the immediate noise stops.
+
+---
+
+See also: [[orbit-company-overview]], [[orbit-team-lanes-detail]], [[customer-communication-policy]]

package/assets/demo/orbit/wiki/global/orbit-known-product-gaps.md

@@ -0,0 +1,47 @@
+---
+summary: "Known Orbit product friction: approval routing for non-standard cases (weird supplier setups, split budgets, renewal changes) causes teams to fall back to side channels outside Orbit."
+usage_mode: auto
+sort_order: 0
+tags:
+  - product
+  - orbit
+  - customer-success
+refs:
+  - orbit-customer-stakeholder-needs
+  - orbit-product-review-checklist
+  - orbit-company-overview
+---
+
+## Known Product Gaps and Friction Points
+
+**Source:** Notion - Product & Customers (Notes from Recent Customer Calls), last edited 2026-05-07
+
+---
+
+## Primary Friction: Approval Routing for Exceptions
+
+The primary source of customer friction is **approval routing around non-standard cases**. When a procurement request does not fit the standard routing rules, teams fall back to side channels (email, Slack, spreadsheets) outside Orbit.
+
+### Specific Triggers
+
+| Trigger | Why It Causes Fallback |
+|---|---|
+| **Weird supplier setups** | Non-standard supplier configurations don't fit the default approval chain |
+| **Split department budgets** | Requests that span multiple budget owners require manual coordination not supported in the routing UI |
+| **Renewal changes** | Mid-term contract changes (scope, price, term) don't map cleanly to the new-request flow |
+
+## Impact
+
+- Teams that fall back to side channels for exceptions create a split record: part of the procurement history is in Orbit, part is not.
+- This undermines the supplier file completeness that Procurement requires (see [[orbit-customer-stakeholder-needs]]).
+- It also creates renewal risk because CS cannot see the full picture of what was agreed.
+
+## Status
+
+- This is a known, unresolved gap as of May 2026.
+- Treat as a standing assumption in roadmap and analysis decisions until a fix is shipped and validated.
+- Do not design analyses or reports that assume all procurement activity flows through Orbit for accounts with known exception patterns.
+
+---
+
+See also: [[orbit-customer-stakeholder-needs]], [[orbit-product-review-checklist]], [[orbit-company-overview]]

package/assets/demo/orbit/wiki/global/orbit-mart-account-activity.md

@@ -0,0 +1,49 @@
+---
+summary: "mart_account_activity: pre/post policy 30-day activation rates per policy_change_date. policy_change_date = 2026-01-15 is the Jan 2026 boundary. Rates are 0–1 ratios."
+usage_mode: auto
+sort_order: 0
+tags:
+  - activation
+  - policy
+  - mart
+  - orbit-analytics
+sl_refs:
+  - mart_account_activity
+tables:
+  - orbit_analytics.mart_account_activity
+---
+
+# mart_account_activity
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/63.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/101.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/106.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/107.json -->
+
+**Table:** `orbit_analytics.mart_account_activity`
+**Grain:** one row per `policy_change_date`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `policy_change_date` | date | The policy boundary date (primary value: `2026-01-15`) |
+| `pre_policy_30_day_activation_rate` | decimal | 30-day activation rate before the policy change (0–1 ratio) |
+| `post_policy_30_day_activation_rate` | decimal | 30-day activation rate after the policy change (0–1 ratio) |
+
+## Key measures (SL: `mart_account_activity`)
+
+- `avg_pre_policy_activation_rate` - `avg(pre_policy_30_day_activation_rate)`
+- `avg_post_policy_activation_rate` - `avg(post_policy_30_day_activation_rate)`
+
+## Common query patterns
+
+- **Policy comparison:** `WHERE policy_change_date = date '2026-01-15'`
+- **As percent:** `round(pre_policy_30_day_activation_rate * 100, 1)`
+- **Side-by-side:** UNION of pre and post rows with a `policy_window` label column
+
+## Business rules
+
+- The January 2026 activation policy change (`policy_change_date = 2026-01-15`) is the primary boundary. `policy_version` in upstream events splits into `pre_2026_01_15` and `post_2026_01_15` cohorts.
+- Rates are ratios (0–1); multiply by 100 for percentage display.
+- See [orbit-activation-policy-change-jan-2026](orbit-activation-policy-change-jan-2026) for full policy context.

package/assets/demo/orbit/wiki/global/orbit-mart-account-segments.md

@@ -0,0 +1,55 @@
+---
+summary: "mart_account_segments: account segmentation with contract ARR, plan codes, size_band, segment (self_serve/commercial/enterprise), and contract_status. One row per account_id."
+usage_mode: auto
+sort_order: 0
+tags:
+  - arr
+  - segmentation
+  - accounts
+  - mart
+  - orbit-analytics
+sl_refs:
+  - mart_account_segments
+tables:
+  - orbit_analytics.mart_account_segments
+---
+
+# mart_account_segments
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/69.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/100.json -->
+
+**Table:** `orbit_analytics.mart_account_segments`
+**Grain:** one row per `account_id`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `account_id` | text | Primary key |
+| `parent_account_id` | text | Parent account for hierarchy rollups |
+| `current_plan_code` | text | Raw plan code from billing system |
+| `normalized_plan_code` | text | Canonical plan code (`pro_plus` → `growth`) |
+| `size_band` | text | Company size band |
+| `segment` | text | Reporting segment: `self_serve`, `commercial`, `enterprise` |
+| `contract_arr_cents` | bigint | Contract ARR in cents |
+| `contract_status` | text | `active`, `churned`, etc. |
+
+## Key measures (SL: `mart_account_segments`)
+
+- `account_count` - `count(*)`
+- `total_contract_arr_cents` - `sum(contract_arr_cents)`
+- `active_contract_arr_cents` - `sum(contract_arr_cents)` where `contract_status = 'active'`
+- `active_contract_arr_millions` - active ARR in $M
+
+## Common query patterns
+
+- **ARR by segment:** `GROUP BY segment WHERE contract_status = 'active'`
+- **Top accounts:** `ORDER BY contract_arr_cents DESC` with `is_internal = false AND is_test = false` (join to `orbit_raw.accounts`)
+- **Unmapped segment:** `COALESCE(segment, 'unmapped')`
+
+## Business rules
+
+- `normalized_plan_code` maps `pro_plus` → `growth`. Always use `normalized_plan_code` for plan-based reporting. See [orbit-plan-segment-normalization](orbit-plan-segment-normalization).
+- `segment` is derived from `canonical_plan_code × size_band` via `stg_plan_segment_mapping`.
+- `contract_arr_cents` is the contract-first ARR value. See [orbit-arr-contract-first-definition](orbit-arr-contract-first-definition).

package/assets/demo/orbit/wiki/global/orbit-mart-arr-daily.md

@@ -0,0 +1,46 @@
+---
+summary: "mart_arr_daily: daily ARR snapshot with contract-first valuation, arr_cents and display columns, used for ARR trend and EoQ reporting."
+usage_mode: auto
+sort_order: 0
+tags:
+  - arr
+  - revenue
+  - mart
+  - orbit-analytics
+sl_refs:
+  - mart_arr_daily
+tables:
+  - orbit_analytics.mart_arr_daily
+---
+
+# mart_arr_daily
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/56.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/96.json -->
+
+**Table:** `orbit_analytics.mart_arr_daily`
+**Grain:** one row per `metric_date`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `metric_date` | date | Snapshot date |
+| `arr_cents` | bigint | ARR in cents (contract-first: active contract ARR takes precedence over subscription ARR) |
+| `display` | text | Human-readable ARR label (e.g. formatted dollar string) |
+
+## Key measures (SL: `mart_arr_daily`)
+
+- `total_arr_cents` - `sum(arr_cents)`
+- `arr_millions` - `round(sum(arr_cents) / 100000000.0, 3)` - ARR in $M
+
+## Common query patterns
+
+- **Current ARR:** filter `metric_date = current_date` (or latest available date)
+- **EoQ ARR:** filter `metric_date = date '2026-03-31'`
+- **ARR trend:** group by `metric_date`, plot `arr_cents`
+
+## Business rules
+
+- ARR is calculated contract-first: active contract ARR takes precedence over subscription ARR for any covered period. See [orbit-arr-contract-first-definition](orbit-arr-contract-first-definition).
+- `display` is a formatted label for UI rendering; use `arr_cents` for all arithmetic.

package/assets/demo/orbit/wiki/global/orbit-mart-nrr-quarterly.md

@@ -0,0 +1,55 @@
+---
+summary: "mart_nrr_quarterly: quarterly NRR by segment with net_revenue_retention ratio, expansion/contraction/churn ARR cents, and quarter_label. Enterprise is the primary reporting segment."
+usage_mode: auto
+sort_order: 0
+tags:
+  - nrr
+  - retention
+  - revenue
+  - mart
+  - orbit-analytics
+sl_refs:
+  - mart_nrr_quarterly
+tables:
+  - orbit_analytics.mart_nrr_quarterly
+---
+
+# mart_nrr_quarterly
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/58.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/98.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/103.json -->
+
+**Table:** `orbit_analytics.mart_nrr_quarterly`
+**Grain:** one row per `quarter_label` × `segment`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `quarter_start_date` | date | First day of the quarter |
+| `quarter_label` | text | Quarter identifier, e.g. `'2026-Q1'` |
+| `segment` | text | Customer segment: `enterprise`, `commercial`, `self_serve` |
+| `starting_arr_cents` | bigint | ARR at start of quarter in cents |
+| `expansion_arr_cents` | bigint | ARR added from expansions |
+| `contraction_arr_cents` | bigint | ARR lost from contractions (includes discount expirations) |
+| `churned_arr_cents` | bigint | ARR lost from churn |
+| `net_revenue_retention` | decimal | NRR ratio (e.g. `1.12` = 112%) |
+
+## Key measures (SL: `mart_nrr_quarterly`)
+
+- `avg_nrr` - `avg(net_revenue_retention)` across all rows
+- `avg_nrr_enterprise` - `avg(net_revenue_retention)` filtered to `segment = 'enterprise'`
+- `total_expansion_arr_cents`, `total_contraction_arr_cents`, `total_churned_arr_cents`
+
+## Common query patterns
+
+- **Q1 enterprise NRR:** `WHERE quarter_label = '2026-Q1' AND segment = 'enterprise'`
+- **NRR as percent:** `round(net_revenue_retention * 100, 1)`
+- **Trend by quarter:** `ORDER BY quarter_start_date`
+
+## Business rules
+
+- `net_revenue_retention` is a ratio, not a percentage. Multiply by 100 for display.
+- Contraction includes discount expirations (classified as contraction, not churn). See [orbit-nrr-discount-expiration-treatment](orbit-nrr-discount-expiration-treatment).
+- Enterprise is the primary executive reporting segment.

package/assets/demo/orbit/wiki/global/orbit-mart-procurement-activity.md

@@ -0,0 +1,47 @@
+---
+summary: "mart_procurement_activity: weekly active requester counts by contract_arr_threshold_cents. Standard threshold is 20000000 cents ($200k ARR). Used for golden-week procurement metrics."
+usage_mode: auto
+sort_order: 0
+tags:
+  - procurement
+  - mart
+  - orbit-analytics
+  - active-requesters
+sl_refs:
+  - mart_procurement_activity
+tables:
+  - orbit_analytics.mart_procurement_activity
+---
+
+# mart_procurement_activity
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/88.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/108.json -->
+
+**Table:** `orbit_analytics.mart_procurement_activity`
+**Grain:** one row per `week_start_date` × `contract_arr_threshold_cents`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `week_start_date` | date | Monday of the reporting week |
+| `week_end_date` | date | Sunday of the reporting week |
+| `contract_arr_threshold_cents` | bigint | ARR threshold filter applied (e.g. `20000000` = $200k) |
+| `active_requesters` | bigint | Count of qualifying active requesters for the week |
+
+## Key measures (SL: `mart_procurement_activity`)
+
+- `total_active_requesters` - `sum(active_requesters)`
+- `active_requesters_200k_threshold` - `sum(active_requesters)` where `contract_arr_threshold_cents = 20000000`
+
+## Common query patterns
+
+- **Golden week (week of 2026-03-23):** `WHERE week_start_date = date '2026-03-23' AND contract_arr_threshold_cents = 20000000`
+- **Weekly trend at $200k threshold:** `WHERE contract_arr_threshold_cents = 20000000 ORDER BY week_start_date`
+
+## Business rules
+
+- `active_requesters` counts non-internal, non-test requesters on large active contracts. See [orbit-procurement-qualifying-actions](orbit-procurement-qualifying-actions).
+- The standard threshold is `contract_arr_threshold_cents = 20000000` ($200k ARR).
+- Always filter by `contract_arr_threshold_cents` - the table contains rows for multiple threshold values.

package/assets/demo/orbit/wiki/global/orbit-mart-retention-movement-breakout.md

@@ -0,0 +1,55 @@
+---
+summary: "mart_retention_movement_breakout: quarterly ARR movement by segment, movement_type, and movement_reason. NRR waterfall source. Contraction includes discount expirations."
+usage_mode: auto
+sort_order: 0
+tags:
+  - nrr
+  - retention
+  - arr
+  - mart
+  - orbit-analytics
+sl_refs:
+  - mart_retention_movement_breakout
+tables:
+  - orbit_analytics.mart_retention_movement_breakout
+---
+
+# mart_retention_movement_breakout
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/105.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/115.json -->
+
+**Table:** `orbit_analytics.mart_retention_movement_breakout`
+**Grain:** one row per `quarter_label` × `segment` × `movement_type` × `movement_reason`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `quarter_start_date` | date | First day of the quarter |
+| `quarter_label` | text | Quarter identifier, e.g. `'2026-Q1'` |
+| `segment` | text | Customer segment: `enterprise`, `commercial`, `self_serve` |
+| `movement_type` | text | `expansion`, `contraction`, or `churn` |
+| `movement_reason` | text | Specific reason (e.g. `discount_expiration`) |
+| `parent_account_count` | bigint | Number of parent accounts in this bucket |
+| `expansion_arr_cents` | bigint | Expansion ARR in cents |
+| `contraction_arr_cents` | bigint | Contraction ARR in cents |
+| `churned_arr_cents` | bigint | Churned ARR in cents |
+
+## Key measures (SL: `mart_retention_movement_breakout`)
+
+- `total_expansion_arr_cents`, `total_contraction_arr_cents`, `total_churned_arr_cents`
+- `expansion_arr_millions`, `contraction_arr_millions`, `churned_arr_millions`
+- `parent_account_count`
+
+## Common query patterns
+
+- **Q1 enterprise waterfall:** `WHERE quarter_label = '2026-Q1' AND segment = 'enterprise'`
+- **Movement summary:** `GROUP BY movement_type ORDER BY movement_type`
+- **Discount expiration contraction:** `WHERE movement_reason = 'discount_expiration'`
+
+## Business rules
+
+- Contraction includes discount expirations, classified as contraction (not churn), tracked via `movement_reason`. See [orbit-nrr-discount-expiration-treatment](orbit-nrr-discount-expiration-treatment).
+- This table is the row-level source for `mart_nrr_quarterly` aggregations.
+- Only one of `expansion_arr_cents`, `contraction_arr_cents`, `churned_arr_cents` is non-zero per row.

package/assets/demo/orbit/wiki/global/orbit-mart-revenue-daily.md

@@ -0,0 +1,56 @@
+---
+summary: "mart_revenue_daily: daily gross-to-net revenue reconciliation with gross_revenue_cents, credits_cents, refunds_cents, net_revenue_cents, and reconciliation_check."
+usage_mode: auto
+sort_order: 0
+tags:
+  - revenue
+  - reconciliation
+  - mart
+  - orbit-analytics
+sl_refs:
+  - mart_revenue_daily
+tables:
+  - orbit_analytics.mart_revenue_daily
+---
+
+# mart_revenue_daily
+
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/57.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/97.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/102.json -->
+<!-- from: raw-sources/postgres-warehouse/metabase/2026-05-12-035303-local-metabase-3-114d957b-f564-4f46-8d4c-2770720a95be/cards/104.json -->
+
+**Table:** `orbit_analytics.mart_revenue_daily`
+**Grain:** one row per `revenue_date`
+
+## Columns
+
+| Column | Type | Notes |
+|---|---|---|
+| `revenue_date` | date | Revenue recognition date |
+| `gross_revenue_cents` | bigint | Gross invoice revenue in cents |
+| `credits_cents` | bigint | Credits applied in cents |
+| `refunds_cents` | bigint | Refunds issued in cents |
+| `net_revenue_cents` | bigint | Net revenue = gross − credits − refunds |
+| `reconciliation_check` | boolean | Must be `true` on every row; flags rows where net ≠ gross − credits − refunds |
+
+## Key measures (SL: `mart_revenue_daily`)
+
+- `total_gross_revenue_cents` - `sum(gross_revenue_cents)`
+- `total_credits_cents` - `sum(credits_cents)`
+- `total_refunds_cents` - `sum(refunds_cents)`
+- `total_net_revenue_cents` - `sum(net_revenue_cents)`
+- `net_revenue_millions` - `round(sum(net_revenue_cents) / 100000000.0, 3)`
+- `gross_revenue_millions` - `round(sum(gross_revenue_cents) / 100000000.0, 3)`
+
+## Common query patterns
+
+- **Q1 net revenue:** `WHERE revenue_date BETWEEN '2026-01-01' AND '2026-03-31'`
+- **February reconciliation:** `WHERE revenue_date BETWEEN '2026-02-01' AND '2026-02-28'`
+- **Monthly trend:** `GROUP BY date_trunc('month', revenue_date)`
+
+## Business rules
+
+- `reconciliation_check` must be `true` on every row. Any `false` row indicates a data quality issue.
+- Gross-to-net reconciliation: gross revenue − credits − refunds = net revenue. See [orbit-revenue-gross-to-net-reconciliation](orbit-revenue-gross-to-net-reconciliation).
+- All amounts are in cents; divide by 100 for USD, by 100,000,000 for $M.

package/assets/demo/orbit/wiki/global/orbit-metabase-sql-library-patterns.md

@@ -0,0 +1,71 @@
+---
+summary: "Metabase SQL Library collection (collection 7): reusable query patterns, the account_join snippet, and field-filter conventions used across Orbit Showcase cards."
+usage_mode: auto
+sort_order: 0
+tags:
+  - metabase
+  - sql-patterns
+  - orbit-showcase
+sl_refs:
+  - mart_account_segments
+  - mart_procurement_activity
+  - mart_customer_health
+  - mart_retention_movement_breakout
+  - mart_revenue_daily
+  - mart_nrr_quarterly
+---
+
+# Orbit Metabase SQL Library - Patterns & Conventions
+
+Collection **7 "SQL Library"** (parent: Orbit Showcase, collection 5) contains reference queries that demonstrate how to write Metabase native SQL against the Orbit analytics marts. Cards here are intentionally illustrative; several have `dashboardCount: 0` and are not embedded in live dashboards.
+
+## Reusable snippet: `account_join`
+
+Card 55 ("Large contract requesters") references `{{snippet: account_join}}`. The resolved SQL shows the canonical pattern for joining `orbit_analytics.mart_account_segments` to `orbit_raw.accounts`:
+
+```sql
+FROM orbit_analytics.mart_account_segments mart
+LEFT JOIN orbit_raw.accounts a
+     ON a.account_id = mart.account_id
+    AND a.is_internal = false
+    AND a.is_test = false
+```
+
+Key points:
+- The `is_internal = false AND is_test = false` guard is applied **in the JOIN condition**, not the WHERE clause, so it does not drop rows from `mart_account_segments` that have no matching account row.
+- The alias `mart` is used for `mart_account_segments` throughout the snippet.
+- This pattern is equivalent to the filter used in card 48 ("Top accounts by contract ARR"), which applies the same guards in the WHERE clause instead.
+
+## Field-filter conventions
+
+Cards in this collection use Metabase dimension field filters (`type: dimension`) for optional narrowing:
+- `segment` filter → maps to `mart_account_segments.segment` or `mart_retention_movement_breakout.segment`.
+- `date_range` filter → maps to `mart_procurement_activity.week_start_date`.
+- `quarter` filter → maps to `mart_nrr_quarterly.quarter_label`.
+
+These filters are **optional** (`[[ ... ]]` blocks in raw SQL); the resolved SQL drops them, leaving the unfiltered dataset. SL sources derived from these cards should not bake in the filter.
+
+## Hard-coded date anti-pattern
+
+Card 54 ("February credits drilldown") is explicitly documented as a **counter-example**: it hard-codes `revenue_date BETWEEN DATE '2026-02-01' AND DATE '2026-02-28'`. This card is not embedded in any dashboard and should not be used as a template. Use `mart_revenue_daily` directly with a runtime date filter instead.
+
+## Near-duplicate pair: cards 48 and 55
+
+Both cards query `mart_account_segments` + `orbit_raw.accounts` and project `account_name`, `contract_arr`, `segment`, `size_band`. They differ only in:
+- Card 48: no ARR floor filter, LIMIT 20, on 1 dashboard.
+- Card 55: `contract_arr_cents >= 20,000,000` ($200k floor), LIMIT 25, no dashboard.
+
+Card 48 is the canonical reference; card 55 is a filtered variant for large-contract analysis.
+
+## Cards and their mart sources
+
+| Card | Name | Mart | Dashboard count |
+|------|------|------|----------------|
+| 48 | Top accounts by contract ARR | mart_account_segments | 1 |
+| 49 | Procurement actions by week | mart_procurement_activity | 1 |
+| 50 | Accounts at risk | mart_customer_health | 1 |
+| 51 | ARR movement breakout | mart_retention_movement_breakout | 1 |
+| 52 | Revenue refund audit | mart_revenue_daily | 0 |
+| 53 | Enterprise NRR quarter breakout | mart_nrr_quarterly | 0 |
+| 54 | February credits drilldown | mart_revenue_daily | 0 |
+| 55 | Large contract requesters | mart_account_segments | 0 |