docs(warehouse-native): document Fully & Hybrid modes and Data Sources (FT-2068)

.gitignore

@@ -12,6 +12,13 @@
 /docs/APIs-and-SDKs/SDK-API*.js
 /docs/Web-Console-API/*.js
 
+# Worktrees
+/.worktrees
+
+# Local dev/screenshot scratch (not site content)
+/.playwright-shots
+/docs/superpowers
+
 # Misc
 .DS_Store
 .env.local

docs/web-console-docs/warehouse-native/get-started.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 title: "Get Started with Warehouse Native"
 description: "Connect your data warehouse to ABsmartly and start running experiments on your own data."
 ---
@@ -10,6 +10,10 @@ import Image from "../../../src/components/Image";
 
 Warehouse Native lets you run experiments directly on data that lives in your own data warehouse. Instead of sending events to ABsmartly's collectors, you point ABsmartly at your existing tables — exposures, goals, and attributes — and it takes care of the rest.
 
+:::tip New to Warehouse Native?
+This guide covers connecting and configuring a data source. If you're deciding between **Hybrid** and **Fully** Warehouse Native first, read [Warehouse Native Modes](./modes).
+:::
+
 Getting started takes three steps:
 
 1. **[Connect to your data warehouse](#step-1-connect-to-your-data-warehouse)** — set up credentials and test the connection
@@ -22,6 +26,10 @@ Getting started takes three steps:
 
 To begin, navigate to **Settings → Data Sources** and click **Add data source**.
 
+:::note The default data source
+Every installation ships with a built-in **default** data source — ABsmartly's managed ClickHouse. In [Hybrid mode](./modes#hybrid-warehouse-native) you keep this default and add external data sources for your goals. In [Fully mode](./modes#fully-warehouse-native) your own warehouse becomes the default. Exposure events always come from the default data source, so which one is the default determines your mode.
+:::
+
 You'll see a form with two sections: general information about the data source, and the connection credentials specific to your warehouse type.
 
 ### General information
@@ -50,6 +58,10 @@ With your warehouse connected, the next step is to tell ABsmartly where your exp
 
 For each table, you can either use the **Column mapping** tab to select columns from a dropdown, or switch to the **SQL query** tab to write a custom query.
 
+:::note Which tables apply to your data source
+Exposures always come from the **[default data source](./modes#the-default-data-source)**, so the exposure mapping below matters most on whichever data source is your default. On an **external** (non-default) data source used in [Hybrid mode](./modes#hybrid-warehouse-native), you'll typically map only the **goals** table — exposures are brought in automatically through the [Exposures import](#step-4-configure-exposures-import-hybrid-only) setup rather than mapped here.
+:::
+
 ### Exposure table
 
 The exposure table tracks experiment assignments — which unit was exposed to which variant of which experiment, and when.
@@ -171,4 +183,27 @@ ABsmartly will show a preview of the computed schedule in both UTC and your loca
 Match the frequency to your actual ETL schedule. If your data lands once a day at 8 AM UTC, use **Daily at specific time** with a 480-minute offset. Querying more often than data arrives just adds unnecessary load to your warehouse.
 :::
 
-Save the data source, and you're done. ABsmartly will start querying your warehouse on the configured schedule and your experiment data will flow through automatically.
+Save the data source. If this is your **default** data source (a [Fully Warehouse Native](./modes#fully-warehouse-native) setup, or the standard managed ClickHouse), you're done — ABsmartly will start querying your warehouse on the configured schedule and your experiment data will flow through automatically. If you're connecting an **external** data source for [Hybrid mode](./modes#hybrid-warehouse-native), continue to Step 4.
+
+---
+
+## Step 4: Configure exposures import _(Hybrid only)_
+
+This step only applies to **external** (non-default) data sources — the setup used in [Hybrid Warehouse Native](./modes#hybrid-warehouse-native). If your warehouse is the default data source, you can skip it.
+
+In Hybrid mode, a goal can live in an external warehouse, but exposures come from the default data source (ABsmartly's managed ClickHouse). To compute metrics for such a goal, ABsmartly needs to make those exposures available to your external warehouse. It does this through an object store that you provide — you point ABsmartly at a storage location it can use, and your warehouse reads the exposures from there.
+
+The **Exposures import** section configures that storage location:
+
+| Field | Description |
+|---|---|
+| **Object store URL** | The bucket/prefix ABsmartly uses to stage exposures for your warehouse. The accepted scheme depends on your warehouse (for example, `gs://` for BigQuery, `s3://` for Redshift, and `s3://`, `gs://`, or `azure://` for Snowflake). |
+| **Credentials** | The access needed to read and write that location — an access key/secret for BigQuery and ClickHouse, a stage name for Snowflake, an IAM role ARN for Redshift. Databricks needs no extra credentials. |
+
+:::note
+Staged files are cached and reused for a short window, then cleaned up automatically — no manual cleanup is required. For defense in depth, you can also add a bucket lifecycle rule (e.g. "delete objects older than 1 day") as a backstop.
+:::
+
+Save the data source once the exposures import is configured. ABsmartly will then query your warehouse on the configured schedule, evaluating your externally-sourced goals against the exposures automatically.
+
+In [Fully Warehouse Native](./modes#fully-warehouse-native), your warehouse is the default and already holds the exposures, so this step doesn't apply.

docs/web-console-docs/warehouse-native/modes.mdx

@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+title: "Warehouse Native Modes"
+description: "Understand the two Warehouse Native modes — Hybrid and Fully — and choose the right one for your data and compliance needs."
+---
+
+import Image from "../../../src/components/Image";
+
+# Warehouse Native Modes
+
+ABsmartly supports two ways of running Warehouse Native, depending on how much of your experiment data you want to keep inside your own warehouse:
+
+- **Hybrid Warehouse Native** — ABsmartly handles assignment and exposures in its managed ClickHouse, while your **goals and metrics** can be computed against your own warehouse. This is set per goal, so you can mix goals that stay in ABsmartly's ClickHouse with goals sourced from your warehouse.
+- **Fully Warehouse Native** — your warehouse holds **everything** — exposures, goals, and attributes — and nothing user-level ever leaves your infrastructure.
+
+Both modes are built on the same foundation: **[data sources](./get-started)**. The mode you're in is determined by which data source is your **default**.
+
+## The default data source
+
+Every ABsmartly installation has exactly one **default data source**. Out of the box, that's ABsmartly's built-in, managed **ClickHouse** — the same engine that powers the standard cloud experience. You can then connect additional **external** data sources (BigQuery, Snowflake, Redshift, Databricks, or your own ClickHouse) for your goals and metrics.
+
+<Image maxWidth="48rem" centered img="warehouse-native/datasources-list.png" alt="Data Sources list showing the managed ClickHouse marked as Default alongside an external BigQuery data source" />
+
+The default data source is special: **exposure events can only come from the default data source.** This single rule is what separates the two modes.
+
+- In **Hybrid**, the default stays ABsmartly's managed ClickHouse, so exposures live there.
+- In **Fully**, your own warehouse becomes the default, so exposures live in your warehouse alongside everything else.
+
+## Hybrid Warehouse Native
+
+In Hybrid mode, you keep ABsmartly's managed ClickHouse as the default data source and attach one or more external warehouses that your **goals** can draw from.
+
+- **Assignment and exposures** are handled by ABsmartly and stored in the managed ClickHouse.
+- **Goals and metrics** are assigned a data source per goal. A goal can be sourced from an external warehouse — where your business data already lives, so results line up with what your BI and finance teams report — or from ABsmartly's managed ClickHouse. You can mix both: some goals stay in ClickHouse while others come from your warehouse.
+- When a goal is sourced from an external warehouse, ABsmartly makes the exposures that live in the default ClickHouse available to that warehouse so the two can be evaluated together. You enable this by pointing ABsmartly at an object store through the **[Exposures import](./get-started#step-4-configure-exposures-import-hybrid-only)** section on each external data source.
+
+Hybrid lets you bring metrics into your warehouse at your own pace: you keep ABsmartly's battle-tested assignment and exposure pipeline, and move as many (or as few) of your goals into your warehouse as you like.
+
+## Fully Warehouse Native
+
+In Fully mode, **your own warehouse is the default data source.** Exposures, goals, and attributes all live in your warehouse, and no user-level data is ever sent to ABsmartly's cloud. ABsmartly still handles experiment management, assignment logic, statistics, and metric governance — but the underlying data never leaves your environment.
+
+Because exposures come from the default data source, going Fully unlocks two things Hybrid can't offer:
+
+- **Filter exposures yourself.** You control the exposures table, so you can strip out bots, scrapers, internal traffic, or any other unwanted exposures before ABsmartly analyzes them — using your own logic in your own warehouse.
+- **Enrich exposures with your own attributes.** You can join in an external **attributes** table to add segmentation dimensions that ABsmartly never sees in Hybrid mode, then slice experiment results by those attributes.
+
+:::info Why the exposure source matters
+Exposure-side filtering (robots, scrapers, internal traffic) and attribute enrichment both operate on the exposure stream. Since exposures can only come from the default data source, these capabilities are only available when **your** warehouse is the default — that is, in **Fully Warehouse Native**. If you need either, choose Fully.
+:::
+
+## Choosing a mode
+
+| | Hybrid Warehouse Native | Fully Warehouse Native |
+|---|---|---|
+| **Default data source** | ABsmartly's managed ClickHouse | Your own warehouse |
+| **Where exposures live** | ABsmartly's managed ClickHouse | Your warehouse |
+| **Where goals & metrics are computed** | Per goal: ABsmartly's ClickHouse or your warehouse | Your warehouse |
+| **User-level data in ABsmartly cloud** | Exposures, plus any goals kept in ClickHouse | None |
+| **Filter exposures yourself (bots/scrapers/internal traffic)** | ❌ | ✅ |
+| **Enrich exposures with your own attributes table** | ❌ | ✅ |
+| **Setup effort** | Lower — keep ABsmartly's exposure pipeline | Higher — your warehouse owns exposures end to end |
+
+**Choose Hybrid** when you want some or all of your goals to draw from your warehouse data, but are happy to let ABsmartly manage assignment and exposures.
+
+**Choose Fully** when data residency requires that no user-level data leaves your infrastructure, or when you need to filter exposures or enrich them with your own attributes.
+
+## Next steps
+
+Whichever mode you're targeting, the setup starts the same way — by connecting a data source:
+
+- **[Get Started with Warehouse Native](./get-started)** — connect your warehouse, map your tables, and configure data freshness.
+- **[Connect your warehouse](./get-started#step-1-connect-to-your-data-warehouse)** — step-by-step guides for BigQuery, Snowflake, ClickHouse, Redshift, and Databricks.

docs/web-console-docs/warehouse-native/overview.mdx

@@ -24,6 +24,15 @@ With Warehouse Native, ABsmartly handles experiment assignment, management, stat
 
 You configure a **data source** that connects ABsmartly to your warehouse, map your tables to ABsmartly's expected schema, and set a refresh schedule. ABsmartly then queries your warehouse on that schedule to compute experiment results.
 
+## Two modes: Hybrid and Fully
+
+Warehouse Native comes in two flavors, depending on how much of your data you want to keep in your own warehouse:
+
+- **Hybrid Warehouse Native** — ABsmartly manages assignment and exposures in its managed ClickHouse, while your **goals and metrics** can be computed against your own warehouse. It's set per goal, so you can mix goals sourced from ABsmartly's ClickHouse with goals sourced from your warehouse.
+- **Fully Warehouse Native** — **everything** lives in your warehouse: exposures, goals, and attributes. No user-level data ever leaves your infrastructure, and you can filter exposures or enrich them with your own attributes.
+
+Which mode you're in is determined by which data source is your **default**. See **[Warehouse Native Modes](./modes)** for a full comparison and guidance on choosing.
+
 ### Supported warehouses
 
 | Warehouse | Status |
@@ -47,4 +56,4 @@ You configure a **data source** that connects ABsmartly to your warehouse, map y
 
 ## Next steps
 
-Ready to set up Warehouse Native? Head to the [Get Started guide](./get-started) to connect your warehouse, map your tables, and configure data freshness.
+New to Warehouse Native? Start by understanding the [two modes](./modes) — Hybrid and Fully — and which one fits your needs. When you're ready to set it up, head to the [Get Started guide](./get-started) to connect your warehouse, map your tables, and configure data freshness.