Trey edits

Author: treysp

docs/cloud/features/scheduler/scheduler.md

@@ -171,39 +171,57 @@ For fine-grained control, dependencies can be specified, pinned, or excluded usi
 
 ## Secret Manager
 
-Tobiko Cloud provides a way for you to provide environment variables that will
-be injected into the environment when running your python models. The values
-of these variables are encrypted at rest and only available in the environment
-of your running models.
+Tobiko Cloud provides a secrets manager where you can define environment variables for your project's Python models.
+
+These variables are most commonly used to provide sensitive information to Python models, such as API keys or other credentials.
+
+Secret values are encrypted at rest and only available in the environment of your running Python models.
 
 !!! note "Cloud Scheduler Only"
 
-    Secrets from the secret manager do not load into hybrid executors. They are
-    only used for cloud scheduler executors.
+    Secrets from the secret manager do not load into hybrid executors. They are only used for cloud scheduler executors.
 
-In your cloud instance you can find Secrets under the Settings section and will
-look like this:
+Secret names have two restrictions - they must:
 
-![secrets_panel](./scheduler/secrets.png)
+- Start with a letter or an underscore
+- Only include letters, numbers, and underscores (no spaces or other symbols)
+
+Secret values have no limits or restrictions. We recommend base64 encoding any secrets that contain binary data.
+
+### Defining secrets
 
-In this example, only one secret has been defined: `MY_SECRET`. From this panel
-you can create a new secret, edit the value of your secrets, or remove them. You
-can not view the value of any previously created secret.
+Define a secret on the Secrets page, accessible via the Settings section in Tobiko Cloud's left side navigation bar.
+
+The Secrets page has a single panel you use to create a new secret, edit the value of an existing secret, or remove an existing secret. You cannot view the value of any existing secret.
+
+In this example, only one secret has been defined: `MY_SECRET`. Update its value by entering a new value in the Secret field and clicking the `Update` button, or delete it by clicking the `Remove` button.
+
+![secrets_panel](./scheduler/secrets.png)
 
-Secret names must start with a letter or an underscore. They may only include
-letters, numbers and underscores (no spaces or other symbols). There are no
-limits or restrictions on the value of secrets. We recommend base64 encoding
-secrets if they contain binary data.
 
 ### Python Model Example
 
-```python
+This Python model demonstrates how to read the `MY_SECRET` secret from an environment variable.
+
+!!! danger "Protecting Secrets"
+
+    Only read environment variables from inside a Python model's `execute` function definition (not in the global scope).
+
+    If the variable is read in the global scope, SQLMesh will load the value from *your local system* when it renders the Python model instead of loading it at runtime on our executors.
+
+    This could expose sensitive information or embed an incorrect local value in the rendered model.
+
+```python linenums="1"
 import os
+import pandas as pd
 import typing as t
 from datetime import datetime
 
 from sqlmesh import ExecutionContext, model
 
+# DO NOT read environment variables here.
+# Only inside the `execute` function definition!
+
 @model(
     "my_model.name",
     columns={
@@ -220,12 +238,6 @@ def execute(
 
     # Read a secret from the MY_SECRET environment variable
     my_secret = os.environ["MY_SECRET"]
-```
 
-!!! warning "Protecting Secrets"
-
-    It's very important that you read environment variables from inside the models
-    `execute` function and not in the global scope. If the variable is loaded in the
-    global scope than the value will be read from your local system and saved
-    into the rendered version of this model, instead of loaded at runtime on our
-    executors.
+    ...
+```