Document the SOPS secrets adapter

docs/commands/secrets.md

@@ -246,3 +246,36 @@ kamal secrets extract DB_PASSWORD <SECRETS-FETCH-OUTPUT>
 ```
 
 The passbolt adapter does not use the `--account` option, if given it will be ignored.
+
+## sops
+
+First, install and configure [sops](https://github.com/getsops/sops).
+
+sops decrypts a single encrypted file and resolves its own decryption key (age, AWS/GCP KMS, Azure Key Vault, PGP, etc.) from its configuration and environment, so no `--account` is needed. Pass the encrypted file with the `--from` option and name the keys to fetch as positional arguments. Nested keys are flattened into `parent/child` paths, and passing no keys fetches every key in the file.
+
+Use the adapter `sops`:
+
+```bash
+# Given an encrypted config/secrets.enc.yaml like:
+#   REGISTRY_PASSWORD: registry-secret
+#   database:
+#     DB_PASSWORD: db-secret
+#     host: db.example.com
+
+# Fetch specific keys
+kamal secrets fetch --adapter sops --from config/secrets.enc.yaml REGISTRY_PASSWORD database/DB_PASSWORD
+
+# Fetch every key in the file
+kamal secrets fetch --adapter sops --from config/secrets.enc.yaml
+
+# Fetch a whole nested section by its parent key (returns database/DB_PASSWORD and database/host)
+kamal secrets fetch --adapter sops --from config/secrets.enc.yaml database
+
+# Both of these will extract the secret
+kamal secrets extract DB_PASSWORD <SECRETS-FETCH-OUTPUT>
+kamal secrets extract database/DB_PASSWORD <SECRETS-FETCH-OUTPUT>
+```
+
+sops emits its decrypted output as JSON regardless of the source file format (YAML, JSON, or env), so nested structures are addressable with `/` and non-string values (numbers, booleans, lists) are returned as strings.
+
+The sops adapter does not use the `--account` option, if given it will be ignored.