Add rewritten version Mikey

Author: Gijsreyn

schemas/src/extension/manifest.secret.yaml

@@ -35,12 +35,42 @@ properties:
       [_Online Documentation_][01]
       ***
 
-      Defines the name of the command to run. The value must be the name of a command discoverable
-      in the system's `PATH` environment variable or the full path to the command. A file extension
-      is only required when the command isn't recognizable by the operating system as an
-      executable.
+      DSC expects extensions implementing the `secret` capability to adhere to the
+      following contract:
+      
+        1. If the extension retrieves the secret, the extension must emit the secret
+          to stdout as a single line of plaintext and exit with code `0`. DSC
+          consumes the emitted output and makes the secret available in the
+          configuration document.
 
-      [01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/secret?<DOCS_VERSION_PIN>#executable
+          If the extension emits more than one line to stdout, DSC raises an error.
+        1. If the extension cannot retrieve the secret because the secret doesn't
+          exist, the extension must not emit any text to stdout and must exit with
+          code `0`. DSC interprets this result as the secret not existing in the
+          vault.
+        1. If the extension cannot retrieve the secret for any other reason, such
+          as invalid credentials or an API error, the extension should emit
+          a descriptive error message as a JSON Line to stderr and exit with a
+          nonzero exit code. DSC interprets the nonzero exit code as an operational
+          failure and surfaces that information and any emitted error messages to
+          the user.
+
+      When the exit code for the operation is `0`, DSC interprets the operation as
+      completing without errors. For extensions, failure to retrieve a secret
+      because it doesn't exist is _not_ an error. Failure to retrieve a secret
+      for any other reason _is_ an error and the extension should exit with a
+      nonzero code. For an improved user experience, the extension should define
+      the `exitCodes` field in the extension manifest to indicate what the nonzero
+      exit code means.
+      
+      For more information about how DSC validates the data for stdout, see
+      [Secret extension operation stdout][01]. For more information about defining
+      exit codes for the extension, see [`exitCodes`][02] in the extension manifest
+      schema reference.
+
+      [00]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/secret?<DOCS_VERSION_PIN>
+      [01]: <DOCS_BASE_URL>/reference/schemas/extension/stdout/secret?<DOCS_VERSION_PIN>
+      [02]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/root?<DOCS_VERSION_PIN>#exitcodes
   args:
     title: Arguments
     description: >-