Clarify KV 2 API docs (#12086)

* initial draft of changes

* address pr comments and add changelog

* remove changelog

website/content/api-docs/secret/kv/kv-v2.mdx

@@ -84,15 +84,17 @@ $ curl \
 {
   "data": {
     "cas_required": false,
-    "max_versions": 0,
-    "delete_version_after": "3h25m19s"
+    "delete_version_after": "3h25m19s",
+    "max_versions": 0
   }
 }
 ```
 
 ## Read Secret Version
 
-This endpoint retrieves the secret at the specified location.
+This endpoint retrieves the secret at the specified location. The metadata returned
+here ( `created_time, destroy,` and `version`) is version specific. It should not be
+confused with the response from the [metadata endpoint](/api/secret/kv/kv-v2#read-secret-metadata).
 
 | Method | Path                                         |
 | :----- | :------------------------------------------- |
@@ -146,11 +148,10 @@ have an ACL policy granting the `update` capability.
 
 - `options` `(Map: <optional>)` – An object that holds option settings.
 
-  - `cas` `(int: <optional>)` - Set the "cas" value to use a Check-And-Set
-    operation. If not set the write will be allowed. If set to 0 a write will
-    only be allowed if the key doesn’t exist. If the index is non-zero the
-    write will only be allowed if the key’s current version matches the
-    version specified in the cas parameter.
+- `cas` `(int: <optional>)` - This flag is required if cas_required is set
+  to true on either the secret or the engine's config. In order for a write
+  to be successful, cas must be set to the current version of the secret.
+  If cas is set to 0, the write will only be allowed if the key doesn't exist.
 
 - `data` `(Map: <required>)` – The contents of the data map will be stored and
   returned on read.
@@ -367,7 +368,7 @@ entries.
 ## Read Secret Metadata
 
 This endpoint retrieves the metadata and versions for the secret at the
-specified path.
+specified path. Metadata is version-agnostic.
 
 | Method | Path                     |
 | :----- | :----------------------- |
@@ -391,8 +392,10 @@ $ curl \
 ```json
 {
   "data": {
+    "cas_required": false,
     "created_time": "2018-03-22T02:24:06.945319214Z",
     "current_version": 3,
+    "delete_version_after": "3h25m19s",
     "max_versions": 0,
     "oldest_version": 0,
     "updated_time": "2018-03-22T02:36:43.986212308Z",
@@ -417,12 +420,10 @@ $ curl \
 }
 ```
 
-## Update Metadata
+## Create/Update Metadata
 
-This endpoint creates a new version of a secret at the specified location. If
-the value does not yet exist, the calling token must have an ACL policy granting
-the `create` capability. If the value already exists, the calling token must
-have an ACL policy granting the `update` capability.
+This endpoint creates or updates the metadata of a secret at the specified location.
+It does not create a new version.
 
 | Method | Path                     |
 | :----- | :----------------------- |