diff --git a/packages/shared/src/config/parser/patch.ts b/packages/shared/src/config/parser/patch.ts
index 9ae6e58a4..941405889 100644
--- a/packages/shared/src/config/parser/patch.ts
+++ b/packages/shared/src/config/parser/patch.ts
@@ -129,6 +129,9 @@ export type Patch =
        * - `Record<string, fn>`: Patch specific named schemas
        * - `function`: Bulk callback receives `(name, schema)` for every schema
        *
+       * Both patterns support async functions for operations like fetching data
+       * from external sources or performing I/O.
+       *
        * @example
        * ```js
        * // Named schemas
@@ -160,6 +163,14 @@ export type Patch =
        *       `\n@version ${match[1]}.${match[2]}.${match[3]}`;
        *   }
        * }
+       *
+       * // Async example - fetch metadata from external source
+       * schemas: async (name, schema) => {
+       *   const metadata = await fetchSchemaMetadata(name);
+       *   if (metadata) {
+       *     schema.description = `${schema.description}\n\n${metadata.notes}`;
+       *   }
+       * }
        * ```
        */
       schemas?: