Docs: Trey edits to hybrid deployment docs (#4122)

Author: treysp

docs/cloud/features/scheduler/hybrid_executors/hybrid-executors_standard-hybrid-deployment.png

@@ -1,38 +1,42 @@
 # Tobiko Cloud Hybrid Executors - Docker Compose Setup
 
-This Docker Compose configuration allows you to run Tobiko Cloud hybrid executors locally or on any server that supports Docker Compose. Hybrid executors enable your own infrastructure to connect to Tobiko Cloud for operations while keeping your data warehouse credentials within your environment.
+This Docker Compose configuration allows you to run Tobiko Cloud hybrid executors locally or on any server that supports Docker Compose.
 
-## What This Setup Provides
+Hybrid executors allow you to run operations on your own infrastructure while leveraging Tobiko Cloud for orchestration.
 
-The hybrid executors connect your data warehouse to Tobiko Cloud in a secure way:
+## What this setup provides
 
-- **Apply Executor**: Executes operations that change state, like creating and updating models
-- **Run Executor**: Runs read-only operations like planning and analysis
+This setup deploys two hybrid executors that pass work tasks from Tobiko Cloud to your data warehouse in a secure way:
+
+- **Apply Executor**: Handles applying changes to the data warehouse
+- **Run Executor**: Handles scheduled model execution
+
+Both executors must be properly configured with environment variables to connect to Tobiko Cloud and your data warehouse.
 
 ## Prerequisites
 
-- Access to a data warehouse (e.g., Postgres, Snowflake, BigQuery)
+- Access to a [data warehouse supported by Tobiko Cloud](../../../integrations/overview.md#execution-engines) (e.g., Postgres, Snowflake, BigQuery)
 - Docker and Docker Compose
-- A Tobiko Cloud account with client ID and client secret
+- A Tobiko Cloud account with [client ID and client secret](../single_sign_on.md#provisioning-client-credentials)
 
-![add_oath_client](./scheduler/add_oath_client.png)
-
-## Quick Start Guide
+## Quick start guide
 
 1. **Get docker-compose file**:
 
-   Download the [docker-compose file](https://raw.githubusercontent.com/TobikoData/sqlmesh/refs/heads/main/docs/cloud/features/scheduler/scheduler/docker-compose.yml) and [.env.example](https://raw.githubusercontent.com/TobikoData/sqlmesh/refs/heads/main/docs/cloud/features/scheduler/scheduler/.env.example) to a local directory.
+   Download the [docker-compose.yml](https://raw.githubusercontent.com/TobikoData/sqlmesh/refs/heads/main/docs/cloud/features/scheduler/scheduler/docker-compose.yml) and [.env.example](https://raw.githubusercontent.com/TobikoData/sqlmesh/refs/heads/main/docs/cloud/features/scheduler/scheduler/.env.example) files to a local directory.
 
 2. **Create your environment file**:
 
+   Copy the downloaded example environment file into a new `.env` file:
+
    ```bash
    cp .env.example .env
    ```
 
-3. **Edit the .env file** with your specific configuration:
+3. **Edit the .env file** with your project's configuration:
 
    - Set your Tobiko Cloud organization, project, client ID, and client secret
-   - Configure your database connection details
+   - Configure your gateway connection details
    - Adjust resource limits if needed
 
 4. **Start the executors**:
@@ -47,47 +51,48 @@ The hybrid executors connect your data warehouse to Tobiko Cloud in a secure way
    docker compose logs -f
    ```
 
-## Configuration Options
+## Configuration options
 
-### Database Configuration
+### Gateway configuration
 
-The default configuration is set up for Postgre, but you can use any supported database by adjusting the connection parameters in your `.env` file:
+The default configuration in the `docker-compose.yml` file uses Postgres, but you can use [any supported SQL engine](../../../integrations/overview.md#execution-engines) by adjusting the connection parameters in your `.env` file.
 
-### Multiple Gateways
+#### Multiple gateways
 
-To configure multiple gateways, edit the docker compose.yml file to add additional environment variables for each gateway:
+To configure multiple gateways, add additional environment variables for each gateway the `docker-compose.yml` file:
 
 ```yaml
 environment:
   # First gateway
   SQLMESH__GATEWAYS__GATEWAY_A__CONNECTION__TYPE: ${DB_TYPE:-postgres}
   # ... other GATEWAY_A configuration ...
-  
+
   # Second gateway
   SQLMESH__GATEWAYS__GATEWAY_B__CONNECTION__TYPE: snowflake
   SQLMESH__GATEWAYS__GATEWAY_B__CONNECTION__ACCOUNT: ${SNOWFLAKE_ACCOUNT}
   # ... other GATEWAY_B configuration ...
 ```
 
-## Health Checking
+## Health checking
 
-You can verify executor health by running:
+Verify the health of your executors by running these commands:
 
 ```bash
 docker compose exec apply-executor /app/pex executor apply --check
 docker compose exec run-executor /app/pex executor run --check
 ```
 
 Check for exit code 0 using `echo $?` to confirm the executors are healthy.
+
 Example successful output:
 
 ```bash
 > docker compose exec apply-executor /app/pex executor apply --check
 2025-04-09 21:24:49,873 - MainThread - httpx - INFO - HTTP Request: GET https://cloud.tobikodata.com/sqlmesh/<YOUR ORG>/<YOUR PROJECT>/api/state-sync/enterprise-version/upgrade "HTTP/1.1 200 OK" (_client.py:1025)
-2025-04-09 21:24:49,889 - MainThread - tobikodata.tcloud.installer - INFO - Executor is installed (installer.py:180
+2025-04-09 21:24:49,889 - MainThread - tobikodata.tcloud.installer - INFO - Executor is installed (installer.py:180)
 ```
 
-## Stopping the Executors
+## Stopping the executors
 
 To stop the executors:
 
@@ -102,10 +107,13 @@ If you encounter issues:
 1. Check the logs: `docker compose logs -f`
 2. Verify your connection settings in the `.env` file
 3. Ensure your client ID and client secret are correct
-4. Check that your database is accessible from the Docker containers
+4. Check that your SQL engine is accessible from the Docker containers
+
+## Security considerations
+
+!!! warning "Never commit .env to version control"
 
-## Security Considerations
+   The `.env` file contains sensitive information. Never commit it to version control.
 
-- The `.env` file contains sensitive information. Never commit it to version control.
 - Consider using Docker secrets or a secrets management solution in production environments.
-- For production deployments, consider using the Kubernetes Helm chart instead, which offers more robust reliability and secret management options. 
+- For production deployments, consider using the Kubernetes Helm chart instead, which offers more robust reliability and secret management options.