docs: Self review of doc pages

docs/vantage/secrets.md

@@ -10,54 +10,53 @@ External Secrets Operator.
 
 ## Groups and values
 
-A **group** is a named bundle `prod-db`, `registry`, `acme-api`. Inside it are
-key/value pairs.
+A **group** is a named bundle, such as `prod-db`, `registry` or `acme-api`.
+Inside it are key/value pairs.
 
-Group by consumer, not by type. A group is the unit a workflow step references
-and the unit ESO reads, so a group that matches one consumer is one reference;
-a group holding everything is over-sharing to every step that needs any of it.
+Group by who uses them rather than by what they are. A workflow step references
+a whole group, so a group that matches one job stays tidy, while a group holding
+everything hands all of it to every step that needs any of it.
 
 ## Managing them
 
 **Secrets → New group**, then add keys.
 
-Values are write-then-hidden. The list shows keys, never values. **Reveal** is a
-separate action on a separate endpoint, and it writes an audit event so
-looking at a secret is a recorded act.
+Once saved, a value is hidden. The list shows key names only. **Reveal** is a
+separate action, and it is written to the audit log.
 
 Deleting a single key and deleting the whole group are separate operations.
 
 ## Using secrets in workflows
 
-Add the group name to a step's `secret_refs`. At execution the group's pairs are
-injected into the step's environment:
+Add the group to a step's secret references. When the step runs, the group's
+pairs are available to it as environment variables:
 
 ```bash
-# secret_refs: ["registry"]
+# with the "registry" group attached to this step
 echo "$REGISTRY_PASSWORD" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin
 ```
 
-A workflow can also override `secret_refs` per step, without changing the
-library entry.
+A workflow can change which groups a step uses without changing the step in the
+library.
 
 :::warning A step can print its own secrets
-Injection puts values in the environment. If your script echoes them, or runs
-with `set -x`, they land in the run log which is stored on disk and readable
-in the UI. Vantage does not scrub step output.
+Values arrive as environment variables. If your script prints them, or runs with
+`set -x`, they end up in the run log, which anyone who can see the run can read.
+Vantage does not filter step output.
 :::
 
 ## Kubernetes External Secrets Operator
 
-`GET /api/secrets/:group/values` returns a group's pairs for ESO, authenticated
-with a **bearer token** rather than a session.
+Kubernetes can read a secret group directly, using a token rather than a
+sign-in.
 
-1. Generate the token at **Settings → Integrations**. It is shown once; only its
-   SHA-256 is stored.
+1. Generate the token at **Settings → Integrations**. It is shown once, and
+   Vantage stores only a fingerprint of it.
 2. Put it in a Kubernetes secret.
-3. Point an ESO `SecretStore` at the endpoint with that bearer token.
+3. Point an External Secrets Operator `SecretStore` at your Vantage address with
+   that token.
 
-The token is rotatable: generating a new one replaces the stored hash and
-invalidates the old one immediately.
+Generating a new token replaces the old one immediately.
 
 :::danger This token reads every group
 It is instance-wide, not scoped to one group. Treat it as a credential to the