docs: Clarify secret handling in configuration

The previous documentation for secret variables could be misleading. It
implied that adding a  tag to a value in the
file and saving it would cause the value to be encrypted.

This is not correct. Encryption is handled by the
command, not by a file-watching or editor-integration feature.

This commit updates the documentation to clarify that  is a
YAML tag used to mark already-encrypted values and that the correct way
to add and encrypt a new secret is to use the
command.

Author: kthhrv

docs/user-guide/01-configuration-file.md

@@ -109,15 +109,29 @@ environment_variables:
 
 #### A Secret Variable
 
-Use the `!secret` tag to mark a value as a secret. It will be encrypted before being saved.
+To handle secrets, `envars` uses the `!secret` YAML tag. This tag indicates that the value is encrypted.
+
+**Important:** You should not manually write plaintext secrets into your `envars.yml` file. The correct way to add a secret is with the `envars add` command and the `--secret` flag.
+
+```bash
+$ envars add API_KEY=super-secret-value --secret --env prod
+```
+
+When you run this command, `envars` will:
+1.  Encrypt "super-secret-value" using the configured KMS key.
+2.  Save the *encrypted ciphertext*, tagged with `!secret`, into your `envars.yml` file.
+
+The resulting `envars.yml` will look something like this:
 
 ```yaml
 environment_variables:
   API_KEY:
     description: "API key for the external service."
-    prod: !secret "super-secret-value"
+    prod: !secret "CiD...encrypted blob...=="
 ```
 
+The `!secret` tag tells `envars` that this value needs to be decrypted when you use commands like `envars output` or `envars exec`.
+
 #### A Variable with Location and Environment Overrides
 
 ```yaml