Docs v3: Rewrite start-free-with-cloud as overview + router page

docs/1-whats-recce/cloud-vs-oss.md

@@ -0,0 +1,125 @@
+---
+title: Cloud vs Open Source
+---
+
+# Cloud vs Open Source
+
+Validating data changes manually takes time and slows PR review. Recce is a data validation agent. Open Source gives you the core validation engine to run yourself, Cloud gives you the full Agent experience with automated validation on every PR.
+
+```mermaid
+flowchart LR
+    subgraph Cloud
+        direction LR
+        C1[You open PR] --> C2[Agent validates automatically]
+        C2 --> C3[Summary posted to PR]
+    end
+
+    subgraph OSS["Open Source"]
+        direction LR
+        O1[You open PR] --> O2[You run checks manually]
+        O2 --> O3[You copy results to PR]
+    end
+```
+
+## The Core Difference
+
+| | Cloud | Open Source |
+|--|-------|-------------|
+| **Experience** | Recce Agent works alongside you | You run validation manually |
+| **PR validation** | Agent validates automatically, posts summary | You run checks, copy results to PR |
+| **During development** | CLI + Agent assistance | CLI tools only |
+| **Learning curve** | Agent guides you through validation | Learn the tools, run them yourself |
+
+## Cloud
+
+Recce Cloud connects to your Git repository and data warehouse so the Recce Agent can validate your data changes automatically. When you open a PR, the Agent analyzes your changes, runs validation checks, and posts findings directly to your PR — no manual work required.
+
+**On pull requests:**
+
+The Agent runs automatically when you open a PR. It:
+
+- Analyzes your data model changes
+- Runs relevant validation checks
+- Posts a summary to your PR with findings
+- Updates as you push new commits
+
+**During development:**
+
+The Agent works with your CLI through [Recce MCP](/5-data-diffing/mcp-server/) (Model Context Protocol):
+
+- Answers questions about your changes
+- Suggests validation approaches
+- Helps interpret diff results
+
+**For your team:**
+
+- Define what "correct" means for your repo with preset checks that apply across all PRs
+- Share validation standards as institutional knowledge — everyone validates the same way
+- Developers and reviewers collaborate on validation, going back and forth until the change is verified
+
+**Pricing:**
+
+Recce Cloud is free to start. See [Pricing](https://www.reccehq.com/pricing) for plan details.
+
+**Choose Cloud when:**
+
+- You want automated validation on every PR
+- You want Agent assistance during development
+- Your team reviews data changes in PRs
+
+## Open Source
+
+Recce OSS is the core validation engine you run locally. You control when and how validation happens — run checks, explore results, and decide what to share. Everything stays on your machine unless you export it.
+
+You get:
+
+- Lineage Diff between branches
+- Data comparison (row count, schema, profile, value, top-k, histogram diff)
+- Query diff for custom validations
+- Checklist to track your checks
+
+**Choose OSS when:**
+
+- Exploring Recce before adopting Cloud
+- Working in environments without external connectivity
+- Contributing to Recce development
+
+## Feature Comparison
+
+| Feature | Cloud | OSS |
+|---------|-------|-----|
+| Lineage Diff | :white_check_mark: | :white_check_mark: |
+| Data diff<br> (row count, schema, profile, value, top-k, histogram diff) | :white_check_mark: | :white_check_mark: |
+| Query diff | :white_check_mark: | :white_check_mark: |
+| Checklist | :white_check_mark: | :white_check_mark: |
+| Recce Agent on PRs | :white_check_mark: | :x: |
+| Agent CLI assistance | :white_check_mark: | Manual |
+| Preset checks across PRs | :white_check_mark: | Manual |
+| Shared validation standards | :white_check_mark: | Manual |
+| Developer-reviewer collaboration | :white_check_mark: | Manual |
+| PR comments & summaries | :white_check_mark: | :x: |
+| LLM-powered insights | :white_check_mark: | :x: |
+
+## FAQ
+
+**Can I start with OSS and upgrade to Cloud later?**
+
+Yes. OSS and Cloud use the same validation engine. Your existing checklists and workflows carry over when you connect to Cloud.
+
+**Does Cloud require a different setup than OSS?**
+
+Cloud connects to your Git repository and data warehouse directly. You don't need to generate artifacts locally — the Agent handles that automatically.
+
+**What data does Recce Cloud access?**
+
+Recce Cloud accesses your dbt artifacts (manifest.json, catalog.json) and runs queries against your data warehouse to perform validation. Your data stays in your warehouse.
+
+## Getting Started
+
+- **Cloud:** [Start Free with Cloud](../2-getting-started/start-free-with-cloud.md)
+- **OSS:** [OSS Setup](../2-getting-started/oss-setup.md)
+
+## Related
+
+- [What the Agent Does](../5-what-the-agent-does/index.md) — How the Recce Agent validates your changes
+- [Data Developer Workflow](../3-using-recce/data-developer.md) — Using Recce throughout development

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)

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)