Vault documentation: added info about new policy flag (#16244)

* added info about new policy flag

* updated wording

website/content/docs/commands/index.mdx

@@ -85,6 +85,18 @@ $ vault write -output-curl-string  auth/userpass/users/bob password="long-passwo
 curl -X PUT -H "X-Vault-Request: true" -H "X-Vault-Token: $(vault print token)" -d '{"password":"long-password"}' http://127.0.0.1:8200/v1/auth/userpass/users/bob
 ```
 
+#### Print Policy Requirements
+
+To view the policy requirements to perform an operation, use the `-output-policy` flag after the subcommand.
+
+```
+$ vault kv put -output-policy kv/secret value=itsasecret
+
+path "kv/data/secret" {
+  capabilities = ["create", "update"]
+}
+```
+
 ## Command Help
 
 There are two primary ways to get help in Vault: [CLI help (`help`)](#cli-help)
@@ -208,9 +220,9 @@ does not support filenames with `=` in them.
 
 ## Mount flag syntax (KV)
 
-All `kv` commands can alternatively refer to the path to the KV secrets engine using a flag-based syntax like `$ vault kv get -mount=secret password` 
-instead of `$ vault kv get secret/password`. The mount flag syntax was created to mitigate confusion caused by the fact that for KV v2 secrets, 
-their full path (used in policies and raw API calls) actually contains a nested `/data/` element (e.g. `secret/data/password`) which can be easily overlooked when using 
+All `kv` commands can alternatively refer to the path to the KV secrets engine using a flag-based syntax like `$ vault kv get -mount=secret password`
+instead of `$ vault kv get secret/password`. The mount flag syntax was created to mitigate confusion caused by the fact that for KV v2 secrets,
+their full path (used in policies and raw API calls) actually contains a nested `/data/` element (e.g. `secret/data/password`) which can be easily overlooked when using
 the above KV v1-like syntax `secret/password`. To avoid this confusion, all KV-specific docs pages will use the `-mount` flag.
 
 ## Exit Codes

website/content/docs/concepts/policies.mdx

@@ -8,7 +8,7 @@ description: >-
 
 # Policies
 
-Everything in Vault is path based, and policies are no exception. Policies
+Everything in Vault is path-based, and policies are no exception. Policies
 provide a declarative way to grant or forbid access to certain paths and
 operations in Vault. This section discusses policy workflows and syntaxes.
 
@@ -169,7 +169,7 @@ corresponding path and capability - even Vault's internal core configuration
 endpoints live under the `"sys/"` path. Policies define access to these paths and
 capabilities, which controls a token's access to credentials in Vault.
 
-~> The policy rules that Vault applies are determined by the most-specific match
+~> **Note:** The policy rules that Vault applies are determined by the most-specific match
 available, using the priority rules described below. This may be an exact match
 or the longest-prefix match of a glob. If the same pattern appears in multiple
 policies, we take the union of the capabilities. If different patterns appear in
@@ -191,7 +191,7 @@ wildcard appears in the same place, both end in `*` and the latter has two wildc
 segments while the former has zero. So we end at rule (3), and give `"secret/+/+/foo/*"`
 _lower_ priority.
 
-!> The glob character referred to in this documentation is the asterisk (`*`).
+!> **Informational:**The glob character referred to in this documentation is the asterisk (`*`).
 It _is not a regular expression_ and is only supported **as the last character of the path**!
 
 When providing `list` capability, it is important to note that since listing
@@ -203,13 +203,12 @@ will sanitize request paths to be prefixes.
 Each path must define one or more capabilities which provide fine-grained
 control over permitted (or denied) operations. As shown in the examples above,
 capabilities are always specified as a list of strings, even if there is only
-one capability. The list of capabilities are:
+one capability.
 
-~> In the list below, the associated HTTP verbs are shown in parenthesis next to
-the capability. When authoring policy, it is usually helpful to look at the HTTP
-API documentation for the paths and HTTP verbs and map them back onto
-capabilities. While the mapping is not strictly 1:1, they are often very
-similarly matched.
+To determine the capabilities needed to perform a specific operation, the `-output-policy` flag can be added to the CLI subcommand. For an example, refer to the [Print Policy Requirements](/docs/commands#print-policy-requirements) document section.
+
+
+The list of capabilities include the following:
 
 - `create` (`POST/PUT`) - Allows creating data at the given path. Very few
   parts of Vault distinguish between `create` and `update`, so most operations
@@ -230,6 +229,12 @@ similarly matched.
   keys returned by a `list` operation are _not_ filtered by policies. Do not
   encode sensitive information in key names. Not all backends support listing.
 
+In the list above, the associated HTTP verbs are shown in parenthesis next to
+the capability. When authoring policy, it is usually helpful to look at the HTTP
+API documentation for the paths and HTTP verbs and map them back onto
+capabilities. While the mapping is not strictly 1:1, they are often very
+similarly matched.
+
 In addition to the standard set, there are some capabilities that do not map to
 HTTP verbs.
 
@@ -244,7 +249,7 @@ HTTP verbs.
 - `deny` - Disallows access. This always takes precedence regardless of any
   other defined capabilities, including `sudo`.
 
-~> Note that capabilities usually map to the HTTP verb, not the underlying
+~> **Note:** Capabilities usually map to the HTTP verb, and not the underlying
 action taken. This can be a common source of confusion. Generating database
 credentials _creates_ database credentials, but the HTTP request is a GET which
 corresponds to a `read` capability. Thus, to grant access to generate database
@@ -300,7 +305,7 @@ path "secret/metadata/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7
 }
 ```
 
-~> When developing templated policies, use IDs wherever possible. Each ID is
+~> **Note:** When developing templated policies, use IDs wherever possible. Each ID is
 unique to the user, whereas names can change over time and can be reused. This
 ensures that if a given user or group name is changed, the policy will be
 mapped to the intended entity or group.
@@ -336,7 +341,7 @@ path take precedence over permissions on parameters.
 
 ### Parameter Constraints
 
--> **Note:**: The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the version 2 kv store.
+~> **Note:**: The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the version 2 kv store.
 
 See the [API Specification](/api-docs/secret/kv/kv-v2) for more information.
 
@@ -487,7 +492,7 @@ path "secret/foo" {
 }
 ```
 
-Note: the only value that can be used with the `*` parameter is `[]`.
+~> **Note:** the only value that can be used with the `*` parameter is `[]`.
 
 ### Required Response Wrapping TTLs
 
@@ -620,7 +625,7 @@ $ curl \
   https://vault.hashicorp.rocks/v1/sys/policy
 ```
 
-~> You may also see the CLI command `vault policies`. This is a convenience
+~> **Note:** You may also see the CLI command `vault policies`. This is a convenience
 wrapper around reading the sys endpoint directly. It provides the same
 functionality but formats the output in a special manner.