DataRecce · doriwilson · Mar 6, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026
diff --git a/docs/2-getting-started/connect-git.md b/docs/2-getting-started/connect-git.md
@@ -0,0 +1,85 @@
+# Connect Your Repository
+
+**Goal:** Connect your GitHub or GitLab repository to Recce Cloud for automated PR data review.
+
+Recce Cloud supports GitHub and GitLab. Using a different provider? Contact us at support@reccehq.com.
+
+## Prerequisites
+
+- [x] Recce Cloud account (free trial at cloud.reccehq.com)
+- [x] Repository admin access (required to authorize app installation)
+- [x] dbt project in the repository
+
+## How It Works
+
+When you connect a Git provider, Recce Cloud maps your setup:
+
+| Git Provider | Recce Cloud |
+|--------------|-------------|
+| Organization | Organization |
+| Repository | Project |
+
+Every Recce Cloud account starts with one organization and one project. When you connect your Git provider, you select which organization and repository to link.
+
+**Monorepo support:** If you have multiple dbt projects in one repository, you can create multiple Recce Cloud projects that connect to the same repo.
+<!-- TODO: add link to monorepo section -->
+
+## Connect GitHub
+
+### 1. Authorize the Recce GitHub App
+
+Navigate to Settings → Git Provider in Recce Cloud. Click **Connect GitHub**.
+
+**Expected result:** GitHub authorization page opens.
+
+### 2. Select Organization and Repository
+
+Choose which GitHub organization to connect. This becomes your Recce Cloud organization.
+
+Then select the repository containing your dbt project. This becomes your Recce Cloud project.
+
+**Expected result:** Repository connected. Your Recce Cloud project is ready to use.
+
+![alt text](../assets/images/2-getting-started/connect-github.png){: .shadow}
+
+## Connect GitLab
+
+GitLab uses Personal Access Tokens (PAT) instead of OAuth.
+
+### 1. Create a Personal Access Token
+
+In GitLab: User Settings → Access Tokens → Add new token.
+
+**Required scopes:**
+
+- `api` - Full access (required for PR comments)
+- `read_api` - Read-only alternative (limited functionality)
+
+**Expected result:** Token string displayed (copy immediately).
+
+### 2. Add Token to Recce Cloud
+
+Navigate to Settings → Git Provider. Select GitLab, paste token.
+
+## Verify Success
+
+In Recce Cloud, navigate to your repository. You should see:
+
+- Connection status: "Connected"
+- Organization Project is linked to a git repository
+
+![alt text](../assets/images/2-getting-started/connect-gitlab.png){: .shadow}
+![alt text](../assets/images/2-getting-started/org-projects.png){: .shadow}
+
+## Troubleshooting
+
+| Issue | Solution |
+| --- | --- |
+| Repository not found | Ensure proper permissions are granted (GitLab: token access, GitHub: app authorized) |
+| Invalid token (GitLab) | Generate new token with `api` scope |
+| Cannot post PR comments (GitLab) | Regenerate token with `api` scope instead of `read_api` |
+
+## Next Steps
+
+- [Connect Data Warehouse](connect-to-warehouse.md)
+- [Add Recce to CI/CD](../7-cicd/ci-cd-getting-started.md)
diff --git a/docs/2-getting-started/connect-to-warehouse.md b/docs/2-getting-started/connect-to-warehouse.md
@@ -0,0 +1,107 @@
+# Connect Data Warehouse
+
+**Goal:** Connect your data warehouse to Recce Cloud to enable data diffing on PRs.
+
+Recce Cloud supports **[Snowflake](#connect-snowflake), [Databricks](#connect-databricks), [BigQuery](#connect-bigquery), and [Redshift](connect-redshift)**. Using a different warehouse? Contact us at support@reccehq.com.
+
+## Prerequisites
+
+- [x] Warehouse credentials with read access
+- [x] Network access configured (IP whitelisting if required)
+
+## Security
+
+Recce Cloud queries your warehouse directly to compare Base and Current environments. Recce encrypts and stores credentials securely. Read-only access is sufficient for all data diffing features.
+
+## Connect Snowflake
+
+### Option 1: Username/Password
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Account | Snowflake account identifier | `xxxxxx.us-central1.gcp` |
+| Username | Database username | `MY_USER` |
+| Password | Database password | `my_password` |
+| Role | Role with read access | `ANALYST_ROLE` |
+| Warehouse | Compute warehouse name | `WH_LOAD` |
+
+### Option 2: Key Pair Authentication
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Account | Snowflake account identifier | `xxxxxx.us-central1.gcp` |
+| Username | Service account username | `MY_USER` |
+| Private Key | PEM-formatted private key | `-----BEGIN RSA PRIVATE KEY-----...` |
+| Passphrase | Key passphrase (if encrypted) | `my_passphrase` |
+| Role | Role with read access | `ANALYST_ROLE` |
+| Warehouse | Compute warehouse name | `WH_LOAD` |
+
+## Connect Databricks
+
+### Option 1: Personal Access Token
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Host | Workspace URL | `adb-1234567890123456.7.azuredatabricks.net` |
+| HTTP Path | SQL warehouse path | `/sql/1.0/warehouses/abc123def456` |
+| Token | Personal access token | `dapiXXXXXXXXXXXXXXXXXXXXXXX` |
+| Catalog | Unity Catalog name (optional) | `my_catalog` |
+
+### Option 2: OAuth (M2M)
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Host | Workspace URL | `adb-1234567890123456.7.azuredatabricks.net` |
+| HTTP Path | SQL warehouse path | `/sql/1.0/warehouses/abc123def456` |
+| Client ID | Service principal client ID | `12345678-1234-1234-1234-123456789012` |
+| Client Secret | Service principal secret | `dose1234567890abcdef` |
+| Catalog | Unity Catalog name (optional) | `my_catalog` |
+
+
+> **Note**: OAuth M2M is auto-enabled in Databricks accounts. For setup details, see [dbt Databricks setup](https://docs.getdbt.com/docs/core/connect-data-platform/databricks-setup#oauth-machine-to-machine-m2m-authentication).
+
+## Connect BigQuery
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Project | GCP project ID | `my-gcp-project-123456` |
+| Service Account JSON | Full JSON key file contents | `{"type": "service_account", ...}` |
+
+
+> **Note**: For authentication, we currently provide support for service account JSON only. More details [here](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#service-account-json).
+
+## Connect Redshift
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Host | Cluster endpoint | `my-cluster.abc123xyz.us-west-2.redshift.amazonaws.com` |
+| Port | Database port | `5439` (Default) |
+| Database | Database name | `analytics_db` |
+| Username | Database user | `admin_user` |
+| Password | Database password | `my_password` |
+
+
+> **Note**: We currently support Database (Password-based authentication) only. More details [here](https://docs.getdbt.com/docs/core/connect-data-platform/redshift-setup#authentication-parameters).
+
+## Save Connection
+
+After entering your connection details, click **Save**. Recce Cloud runs a connection test automatically and displays "Connected" on success.
+
+## Verify Success
+
+Navigate to Organization Settings in Recce Cloud. Your data warehouse should appear.
+
+![alt text](../assets/images/2-getting-started/connect-dw.png){: .shadow}
+
+## Troubleshooting
+
+| Issue | Solution |
+| --- | --- |
+| Connection refused | Whitelist Recce Cloud IP ranges in your network configuration |
+| Authentication failed | Verify credentials and regenerate if expired |
+| Permission denied on table | Grant SELECT permissions on target schemas |
+
+## Next Steps
+
+- [Add Recce to CI/CD](../7-cicd/setup-ci.md)
+- [Run Your First Data Diff](../5-data-diffing/row-count-diff.md)
diff --git a/docs/2-getting-started/gitlab-pat-guide.md b/docs/2-getting-started/gitlab-pat-guide.md
diff --git a/docs/2-getting-started/start-free-with-cloud.md b/docs/2-getting-started/start-free-with-cloud.md
@@ -60,7 +60,7 @@ You can use the Recce Web Agent to help automate your setup. Currently it handle
 
 The agent covers common setups and continues to expand coverage. If your setup isn't supported yet, the agent directs you to the Setup Guide below for manual configuration. Need help? Contact us at support@reccehq.com.
 
-**Coming soon**: The agent will guide you through steps 1–3, including warehouse connection, Git connection, and CI/CD configuration.
+The agent will guide you through steps 1–3, including Git connection, data warehouse connection, and CI/CD configuration.
 
 ---
 
@@ -70,20 +70,20 @@ This guide explains each onboarding step in detail.
 
 First, go to [cloud.reccehq.com](https://cloud.reccehq.com) and create your free account.
 
-### 1. Connect Data Warehouse
-
-1. Select your data warehouse (e.g. Snowflake)
-2. Provide your read-only warehouse credentials
-
-> **Note**: This guide uses Snowflake. For supported warehouses, see [Connect to Warehouse](../5-data-diffing/connect-to-warehouse.md).
-
-### 2. Connect Git Provider
+### 1. Connect Git Provider
 
 1. Click **Connect GitHub**
 2. Authorize the Recce app installation
 3. Select the repositories you want to connect
 
-> **Note**: This guide uses GitHub. For GitLab setup, see [GitLab Personal Access Token](gitlab-pat-guide.md).
+> **Note**: This guide uses GitHub. For supported Git providers, see [Connect to Git](connect-git.md)
+
+### 2. Connect Data Warehouse
+
+1. Select your data warehouse (e.g. Snowflake)
+2. Provide your read-only warehouse credentials
+
+> **Note**: This guide uses Snowflake. For supported warehouses, see [Connect to Warehouse](connect-to-warehouse.md).
 
 ### 3. Add Recce to CI/CD