(SCHEMA) Update docs keywords for secret operation stdout schema

This change updates and extends the `markdownDescription` keyword
for the `secret` operation stdout schema, clarifying the expected
output conditions and validation.

Author: michaeltlombardi

schemas/src/extension/stdout/secret.yaml

@@ -10,11 +10,40 @@ markdownDescription: | # VS Code only
   [_Online Documentation_][00]
   ***
 
-  Represents the secret text returned by a DSC extension for a secret request. DSC expects the
-  extension to emit a single line containing only the secret value. An empty output indicates that
-  no secret is available. If multiple lines are emitted, DSC treats it as an error.
+  Represents the secret text returned by a DSC extension for a secret request. The output that
+  DSC expects from the extension depends on the result of retrieving the secret:
+
+  - If the extension successfully retrieves the secret, DSC expects the extension to:
+
+    1. Emit a single line containing only the secret value, not wrapped in quotation marks or a
+       JSON object, to stdout. DSC treats the literal text returned by the extension as the secret
+       value. If the emitted output contains any newlines, the output is invalid.
+    1. Exit with code `0` to indicate success.
+
+  - If the extension can't retrieve the secret because no secret with the given name was
+    discovered, DSC expects the extension to:
+
+    1. Emit _no output_ to stdout. If the extension emits any output to stdout, DSC interprets the
+       emitted text to be the secret value.
+    1. Optionally emit messages to stderr as [JSON Lines][01] to indicate the attempt to retrieve
+       the secret and noting that the secret doesn't exist. DSC surfaces emitted messages to the
+       caller depending on the message level.
+    1. Exit with code `0` to indicate success. For DSC, an extension not returning a secret value
+       because no secret with the given name exists is _not_ a failure.
+
+  - If the extension can't retrieve the secret for any other reason, such as requiring the vault
+    to be unlocked or encountering an API error, DSC expects the extension to:
+
+    1. Emit _no output_ to stdout.
+    1. Optionally emit detailed error messages to stderr as [JSON Lines][01] to provide contextual
+       information about how and why the retrieval failed. DSC always surfaces emitted error
+       messages to the caller.
+    1. Exit with a nonzero code to indicate failure. If the extension manifest defines the
+       [`exitCodes`][02] field, DSC surfaces the meaning of the exit code to the caller.
 
   [00]: <DOCS_BASE_URL>/reference/schemas/extension/stdout/secret?<DOCS_VERSION_PIN>
+  [01]: https://jsonlines.org/
+  [02]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/root?<DOCS_VERSION_PIN>#exitcodes
 
 type: string
 minLength: 0