@postman/sdk-config 0.6.0 → 0.8.0

package/dist/sdk-config-ir/v1/index.js

@@ -32,140 +32,152 @@ var hashAlgorithmSchema = z.enum(["sha1", "sha256", "sha384", "sha512"]);
 var encodingSchema = z.enum(["base64", "hex"]);
 var payloadComponentSchema = z.enum(["body", "timestamp", "notification-url", "message-id"]);
 var payloadFormatSchema = z.strictObject({
-  components: z.array(payloadComponentSchema).min(1),
-  delimiter: z.string().optional(),
+  components: z.array(payloadComponentSchema).min(1).describe("Payload components concatenated in declaration order before signing."),
+  delimiter: z.string().optional().describe("The delimiter inserted between payload components."),
   /**
    * Set when the body is a form-encoded parameter map that must be canonicalized before signing:
    * keys sorted, each key's values deduped and sorted, concatenated as key-value pairs.
    */
-  bodySort: z.literal("alphabetical").optional()
+  bodySort: z.literal("alphabetical").optional().describe("Canonicalizes form body keys and values alphabetically before signing.")
 });
 var timestampSchema = z.strictObject({
-  header: nonEmptyStringSchema,
-  format: z.enum(["unix-seconds", "unix-millis", "iso8601"]).optional(),
+  header: nonEmptyStringSchema.describe("The request header containing the signing timestamp."),
+  format: z.enum(["unix-seconds", "unix-millis", "iso8601"]).optional().describe("The timestamp format used in the signature payload."),
   /** Replay window in seconds. */
-  tolerance: z.number().positive().optional()
+  tolerance: z.number().positive().optional().describe("The maximum accepted timestamp age, in seconds.")
 });
 var bodyHashLocationSchema = z.discriminatedUnion("type", [
   z.strictObject({
-    type: z.literal("query-parameter"),
-    name: nonEmptyStringSchema
+    type: z.literal("query-parameter").describe("Reads the body hash from a query parameter."),
+    name: nonEmptyStringSchema.describe("The query parameter containing the body hash.")
   })
 ]);
 var bodyHashBindingSchema = z.strictObject({
-  algorithm: hashAlgorithmSchema,
-  encoding: encodingSchema.optional(),
-  location: bodyHashLocationSchema
+  algorithm: hashAlgorithmSchema.describe("The hash algorithm applied to the raw request body."),
+  encoding: encodingSchema.optional().describe("The encoding used for the body hash."),
+  location: bodyHashLocationSchema.describe("Where the expected body hash is read from.")
 });
 var urlNormalizationSchema = z.strictObject({
   /** Try the URL with and without an explicit default port. */
-  portVariants: z.boolean().optional(),
+  portVariants: z.boolean().optional().describe("Whether verification tries URLs with and without an explicit default port."),
   /** Try the URL with the pre-RFC3986 query encoding (`+` for space, unescaped `*`). */
-  legacyQueryEncoding: z.boolean().optional()
+  legacyQueryEncoding: z.boolean().optional().describe("Whether verification also tries legacy form-style query encoding.")
 }).refine(
   ({ portVariants, legacyQueryEncoding }) => portVariants === true || legacyQueryEncoding === true,
   { message: "url normalization must enable at least one variant" }
 );
 var webhookSignatureSchema = z.discriminatedUnion("type", [
   z.strictObject({
-    type: z.literal("hmac"),
+    type: z.literal("hmac").describe("Identifies HMAC webhook signature verification."),
     /** Request header carrying the signature. */
-    header: nonEmptyStringSchema,
-    algorithm: hashAlgorithmSchema.optional(),
-    encoding: encodingSchema.optional(),
+    header: nonEmptyStringSchema.describe("The request header containing the signature."),
+    algorithm: hashAlgorithmSchema.optional().describe("The HMAC hash algorithm."),
+    encoding: encodingSchema.optional().describe("The encoding used for the HMAC signature."),
     /** Stripped from the header value before comparison, e.g. `sha256=`. */
-    signaturePrefix: z.string().optional(),
-    payloadFormat: payloadFormatSchema.optional(),
-    timestamp: timestampSchema.optional(),
-    bodyHashBinding: bodyHashBindingSchema.optional(),
-    urlNormalization: urlNormalizationSchema.optional()
+    signaturePrefix: z.string().optional().describe("A prefix removed from the signature header before comparison."),
+    payloadFormat: payloadFormatSchema.optional().describe("How the payload signed by the provider is assembled."),
+    timestamp: timestampSchema.optional().describe("Timestamp validation included in signature verification."),
+    bodyHashBinding: bodyHashBindingSchema.optional().describe("A separately transmitted hash that binds the raw body to the signed payload."),
+    urlNormalization: urlNormalizationSchema.optional().describe("Alternate notification URL forms accepted during verification.")
   })
 ]);
 
 // src/sdk-config-domain/v1/api.ts
 var authVariableSchema = z.strictObject({
-  name: nonEmptyStringSchema.optional(),
-  environmentVariable: nonEmptyStringSchema.optional(),
-  description: z.string().optional(),
-  omit: z.boolean().optional()
+  name: nonEmptyStringSchema.optional().describe("The parameter name exposed by the SDK."),
+  environmentVariable: nonEmptyStringSchema.optional().describe("The environment variable used to populate the parameter."),
+  description: z.string().optional().describe(
+    "A description of the authentication parameter included in generated SDK documentation."
+  ),
+  omit: z.boolean().optional().describe("Whether the parameter is omitted from the SDK surface.")
 });
 var apiKeyAuthSchema = z.strictObject({
-  id: nonEmptyStringSchema,
-  type: z.literal("api-key"),
-  location: z.enum(["header", "query", "cookie"]),
-  name: nonEmptyStringSchema,
-  prefix: nonEmptyStringSchema.optional(),
-  environmentVariable: nonEmptyStringSchema.optional(),
-  description: z.string().optional()
+  id: nonEmptyStringSchema.describe("A unique identifier for this authentication scheme."),
+  type: z.literal("api-key").describe("Identifies an API key authentication scheme."),
+  location: z.enum(["header", "query", "cookie"]).describe("Where the API key is sent on requests."),
+  name: nonEmptyStringSchema.describe("The header, query parameter, or cookie name."),
+  prefix: nonEmptyStringSchema.optional().describe("A prefix added before the API key value."),
+  environmentVariable: nonEmptyStringSchema.optional().describe("The default environment variable for the API key."),
+  description: z.string().optional().describe(
+    "A description of the authentication scheme included in generated SDK documentation."
+  )
 });
 var bearerAuthSchema = z.strictObject({
-  id: nonEmptyStringSchema,
-  type: z.literal("bearer"),
-  header: nonEmptyStringSchema.optional(),
-  prefix: nonEmptyStringSchema.optional(),
-  environmentVariable: nonEmptyStringSchema.optional(),
-  description: z.string().optional()
+  id: nonEmptyStringSchema.describe("A unique identifier for this authentication scheme."),
+  type: z.literal("bearer").describe("Identifies a bearer token authentication scheme."),
+  header: nonEmptyStringSchema.optional().describe("The request header that carries the bearer token."),
+  prefix: nonEmptyStringSchema.optional().describe('The token prefix, such as "Bearer".'),
+  environmentVariable: nonEmptyStringSchema.optional().describe("The default environment variable for the bearer token."),
+  description: z.string().optional().describe(
+    "A description of the authentication scheme included in generated SDK documentation."
+  )
 });
 var basicAuthSchema = z.strictObject({
-  id: nonEmptyStringSchema,
-  type: z.literal("basic"),
-  username: authVariableSchema.optional(),
-  password: authVariableSchema.optional(),
-  description: z.string().optional()
+  id: nonEmptyStringSchema.describe("A unique identifier for this authentication scheme."),
+  type: z.literal("basic").describe("Identifies an HTTP Basic authentication scheme."),
+  username: authVariableSchema.optional().describe("The username parameter exposed by the SDK."),
+  password: authVariableSchema.optional().describe("The password parameter exposed by the SDK."),
+  description: z.string().optional().describe(
+    "A description of the authentication scheme included in generated SDK documentation."
+  )
 });
 var oauthScopeSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  description: z.string().optional()
+  name: nonEmptyStringSchema.describe("The OAuth scope value requested from the provider."),
+  description: z.string().optional().describe("A description of the OAuth scope included in generated SDK documentation.")
 });
 var oauthFlowSchema = z.discriminatedUnion("type", [
   z.strictObject({
-    type: z.literal("authorization-code"),
-    authorizationUrl: nonEmptyStringSchema,
-    tokenUrl: nonEmptyStringSchema,
-    refreshUrl: nonEmptyStringSchema.optional(),
-    scopes: z.array(oauthScopeSchema).optional()
+    type: z.literal("authorization-code").describe("Uses the OAuth authorization code flow."),
+    authorizationUrl: nonEmptyStringSchema.describe("The URL used to authorize the client."),
+    tokenUrl: nonEmptyStringSchema.describe("The URL used to exchange a code for tokens."),
+    refreshUrl: nonEmptyStringSchema.optional().describe("The URL used to refresh access tokens."),
+    scopes: z.array(oauthScopeSchema).optional().describe("The scopes supported by this flow.")
   }),
   z.strictObject({
-    type: z.literal("client-credentials"),
-    tokenUrl: nonEmptyStringSchema,
-    refreshUrl: nonEmptyStringSchema.optional(),
-    scopes: z.array(oauthScopeSchema).optional()
+    type: z.literal("client-credentials").describe("Uses the OAuth client credentials flow."),
+    tokenUrl: nonEmptyStringSchema.describe("The URL used to obtain access tokens."),
+    refreshUrl: nonEmptyStringSchema.optional().describe("The URL used to refresh access tokens."),
+    scopes: z.array(oauthScopeSchema).optional().describe("The scopes supported by this flow.")
   }),
   z.strictObject({
-    type: z.literal("implicit"),
-    authorizationUrl: nonEmptyStringSchema,
-    refreshUrl: nonEmptyStringSchema.optional(),
-    scopes: z.array(oauthScopeSchema).optional()
+    type: z.literal("implicit").describe("Uses the OAuth implicit flow."),
+    authorizationUrl: nonEmptyStringSchema.describe("The URL used to authorize the client."),
+    refreshUrl: nonEmptyStringSchema.optional().describe("The URL used to refresh access tokens."),
+    scopes: z.array(oauthScopeSchema).optional().describe("The scopes supported by this flow.")
   }),
   z.strictObject({
-    type: z.literal("password"),
-    tokenUrl: nonEmptyStringSchema,
-    refreshUrl: nonEmptyStringSchema.optional(),
-    scopes: z.array(oauthScopeSchema).optional()
+    type: z.literal("password").describe("Uses the OAuth resource owner password flow."),
+    tokenUrl: nonEmptyStringSchema.describe("The URL used to obtain access tokens."),
+    refreshUrl: nonEmptyStringSchema.optional().describe("The URL used to refresh access tokens."),
+    scopes: z.array(oauthScopeSchema).optional().describe("The scopes supported by this flow.")
   })
 ]);
 var oauth2AuthSchema = z.strictObject({
-  id: nonEmptyStringSchema,
-  type: z.literal("oauth2"),
-  flows: z.array(oauthFlowSchema).min(1),
-  clientId: authVariableSchema.optional(),
-  clientSecret: authVariableSchema.optional(),
-  tokenHeader: nonEmptyStringSchema.optional(),
-  tokenPrefix: nonEmptyStringSchema.optional(),
-  refreshBufferSeconds: z.number().nonnegative().optional(),
-  description: z.string().optional()
+  id: nonEmptyStringSchema.describe("A unique identifier for this authentication scheme."),
+  type: z.literal("oauth2").describe("Identifies an OAuth 2.0 authentication scheme."),
+  flows: z.array(oauthFlowSchema).min(1).describe("The OAuth flows supported by the API."),
+  clientId: authVariableSchema.optional().describe("The OAuth client ID parameter exposed by the SDK."),
+  clientSecret: authVariableSchema.optional().describe("The OAuth client secret parameter exposed by the SDK."),
+  tokenHeader: nonEmptyStringSchema.optional().describe("The request header that carries the OAuth access token."),
+  tokenPrefix: nonEmptyStringSchema.optional().describe("The prefix added before the OAuth access token."),
+  refreshBufferSeconds: z.number().nonnegative().optional().describe("How early, in seconds, the client refreshes a token before it expires."),
+  description: z.string().optional().describe(
+    "A description of the authentication scheme included in generated SDK documentation."
+  )
 });
 var customAuthParameterSchema = z.strictObject({
-  location: z.enum(["header", "query", "cookie"]),
-  name: nonEmptyStringSchema,
-  prefix: nonEmptyStringSchema.optional(),
-  environmentVariable: nonEmptyStringSchema.optional()
+  location: z.enum(["header", "query", "cookie"]).describe("Where the custom authentication value is sent."),
+  name: nonEmptyStringSchema.describe("The header, query parameter, or cookie name."),
+  prefix: nonEmptyStringSchema.optional().describe("A prefix added before the parameter value."),
+  environmentVariable: nonEmptyStringSchema.optional().describe("The default environment variable for the parameter.")
 });
 var customAuthSchema = z.strictObject({
-  id: nonEmptyStringSchema,
-  type: z.literal("custom"),
-  parameters: z.array(customAuthParameterSchema).min(1),
-  description: z.string().optional()
+  id: nonEmptyStringSchema.describe("A unique identifier for this authentication scheme."),
+  type: z.literal("custom").describe("Identifies a custom authentication scheme."),
+  parameters: z.array(customAuthParameterSchema).min(1).describe("The request parameters that implement the custom scheme."),
+  description: z.string().optional().describe(
+    "A description of the authentication scheme included in generated SDK documentation."
+  )
 });
 var authSchemeSchema = z.discriminatedUnion("type", [
   apiKeyAuthSchema,
@@ -175,12 +187,12 @@ var authSchemeSchema = z.discriminatedUnion("type", [
   customAuthSchema
 ]);
 var authRequirementSchema = z.strictObject({
-  schemes: z.array(nonEmptyStringSchema).min(1)
+  schemes: z.array(nonEmptyStringSchema).min(1).describe("Scheme identifiers that must be satisfied together.")
 });
 var authConfigSchema = z.strictObject({
-  schemes: z.array(authSchemeSchema).min(1),
-  requirements: z.array(authRequirementSchema).optional(),
-  endpointSecurity: z.boolean().optional()
+  schemes: z.array(authSchemeSchema).min(1).describe("Authentication schemes offered by the API."),
+  requirements: z.array(authRequirementSchema).optional().describe("Valid combinations of authentication schemes."),
+  endpointSecurity: z.boolean().optional().describe("Whether generated endpoints expose their individual security requirements.")
 }).superRefine(({ requirements, schemes }, context) => {
   const schemeIds = /* @__PURE__ */ new Set();
   schemes.forEach(({ id }, index) => {
@@ -206,57 +218,57 @@ var authConfigSchema = z.strictObject({
   });
 });
 var environmentUrlSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  url: nonEmptyStringSchema,
-  serverName: nonEmptyStringSchema.optional()
+  name: nonEmptyStringSchema.describe("The display name for this environment URL."),
+  url: nonEmptyStringSchema.describe("The base URL used for this environment entry."),
+  serverName: nonEmptyStringSchema.optional().describe("The source server represented by this URL.")
 });
 var environmentSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  urls: z.array(environmentUrlSchema).min(1),
-  description: z.string().optional()
+  name: nonEmptyStringSchema.describe("The environment name exposed by the SDK."),
+  urls: z.array(environmentUrlSchema).min(1).describe("The base URLs available in this environment."),
+  description: z.string().optional().describe("A description of the environment included in generated SDK documentation.")
 });
 var headerSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  value: z.string().optional(),
-  description: z.string().optional(),
-  environmentVariable: nonEmptyStringSchema.optional()
+  name: nonEmptyStringSchema.describe("The HTTP header name."),
+  value: z.string().optional().describe("A fixed value for the generated header."),
+  description: z.string().optional().describe("A description of the header included in generated SDK documentation."),
+  environmentVariable: nonEmptyStringSchema.optional().describe("The environment variable used to populate the header.")
 });
 var environmentVariableSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  description: z.string().optional(),
-  defaultValue: z.string().optional()
+  name: nonEmptyStringSchema.describe("The environment variable name exposed by the SDK."),
+  description: z.string().optional().describe("A description of the environment variable included in generated SDK documentation."),
+  defaultValue: z.string().optional().describe("The default value used when the variable is unset.")
 });
 var apiConfigSchema = z.strictObject({
-  baseUrl: z.string().default(""),
-  environments: z.array(environmentSchema).default([]),
-  environmentVariables: z.array(environmentVariableSchema).default([]),
-  defaultEnvironment: nonEmptyStringSchema.optional(),
-  auth: authConfigSchema.optional(),
-  headers: z.array(headerSchema).optional(),
+  baseUrl: z.string().default("").describe("The default base URL used by the generated client."),
+  environments: z.array(environmentSchema).default([]).describe("Named API environments and their base URLs."),
+  environmentVariables: z.array(environmentVariableSchema).default([]).describe("Environment variables exposed through generated client configuration."),
+  defaultEnvironment: nonEmptyStringSchema.optional().describe("The environment selected when a caller does not choose one."),
+  auth: authConfigSchema.optional().describe("Authentication supported by the API."),
+  headers: z.array(headerSchema).optional().describe("Headers added to generated API requests."),
   /**
    * Selects the named `x-fern-audiences`.
    *
    * Absent means all audiences. A present empty array selects no tagged audience: untagged nodes
    * remain included, while every audience-tagged node is excluded.
    */
-  audiences: z.array(nonEmptyStringSchema).optional(),
+  audiences: z.array(nonEmptyStringSchema).optional().describe("Named API audiences included in the generated SDK."),
   /**
    * How the API signs the webhooks it sends, enabling a generated verification helper. API-wide, and
    * independent of whether any webhook is modeled — see {@link webhookSignatureSchema}.
    */
-  webhookSignature: webhookSignatureSchema.optional()
+  webhookSignature: webhookSignatureSchema.optional().describe("How generated helpers verify webhook signatures from the API.")
 });
 var retryOverrideShape = {
-  enabled: z.boolean().optional(),
-  maxAttempts: z.number().int().min(1).optional(),
-  retryDelayMs: z.number().nonnegative().optional(),
-  maxDelayMs: z.number().nonnegative().optional(),
-  jitterMs: z.number().nonnegative().optional(),
-  backoffFactor: z.number().positive().optional(),
-  statusCodes: z.array(z.number().int().min(100).max(599)).optional(),
-  methods: z.array(nonEmptyStringSchema).optional(),
-  statusCodeProfile: z.enum(["legacy", "recommended"]).optional(),
-  maxRetryAfterDelayMs: z.number().nonnegative().optional()
+  enabled: z.boolean().optional().describe("Whether the generated client retries failed requests."),
+  maxAttempts: z.number().int().min(1).optional().describe("The maximum total request attempts, including the initial attempt."),
+  retryDelayMs: z.number().nonnegative().optional().describe("The initial delay between retry attempts, in milliseconds."),
+  maxDelayMs: z.number().nonnegative().optional().describe("The maximum backoff delay between attempts, in milliseconds."),
+  jitterMs: z.number().nonnegative().optional().describe("The maximum random jitter added to retry delays, in milliseconds."),
+  backoffFactor: z.number().positive().optional().describe("The multiplier applied to the delay after each failed attempt."),
+  statusCodes: z.array(z.number().int().min(100).max(599)).optional().describe("HTTP status codes that are eligible for retries."),
+  methods: z.array(nonEmptyStringSchema).optional().describe("HTTP methods that are eligible for retries."),
+  statusCodeProfile: z.enum(["legacy", "recommended"]).optional().describe("The built-in retryable status-code policy."),
+  maxRetryAfterDelayMs: z.number().nonnegative().optional().describe("The longest Retry-After delay the client will honor, in milliseconds.")
 };
 function validateRetryDelays({
   maxDelayMs,
@@ -273,27 +285,29 @@ function validateRetryDelays({
 var clientRetryOverrideSchema = z.strictObject(retryOverrideShape).superRefine(validateRetryDelays);
 var retryConfigSchema = z.strictObject({
   ...retryOverrideShape,
-  enabled: z.boolean().default(true),
-  maxAttempts: z.number().int().min(1).default(3),
-  retryDelayMs: z.number().nonnegative().default(150),
-  maxDelayMs: z.number().nonnegative().default(5e3),
-  jitterMs: z.number().nonnegative().default(50),
-  backoffFactor: z.number().positive().default(2),
-  methods: z.array(nonEmptyStringSchema).default(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]),
-  maxRetryAfterDelayMs: z.number().nonnegative().default(6e4)
+  enabled: z.boolean().default(true).describe("Whether the generated client retries failed requests."),
+  maxAttempts: z.number().int().min(1).default(3).describe("The maximum total request attempts, including the initial attempt."),
+  retryDelayMs: z.number().nonnegative().default(150).describe("The initial delay between retry attempts, in milliseconds."),
+  maxDelayMs: z.number().nonnegative().default(5e3).describe("The maximum backoff delay between attempts, in milliseconds."),
+  jitterMs: z.number().nonnegative().default(50).describe("The maximum random jitter added to retry delays, in milliseconds."),
+  backoffFactor: z.number().positive().default(2).describe("The multiplier applied to the delay after each failed attempt."),
+  methods: z.array(nonEmptyStringSchema).default(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]).describe("HTTP methods that are eligible for retries."),
+  maxRetryAfterDelayMs: z.number().nonnegative().default(6e4).describe("The longest Retry-After delay the client will honor, in milliseconds.")
 }).superRefine(validateRetryDelays);
 var constructorParameterSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  example: z.string().optional(),
-  description: z.string().optional(),
-  required: z.boolean().optional()
+  name: nonEmptyStringSchema.describe("The parameter name in the generated client constructor."),
+  example: z.string().optional().describe("An example value shown in generated documentation."),
+  description: z.string().optional().describe(
+    "A description of the constructor parameter included in generated SDK documentation."
+  ),
+  required: z.boolean().optional().describe("Whether callers must provide the parameter.")
 });
 var parameterStyleSchema = z.enum(["wrapped", "inline", "language-default"]);
 var tokenRefreshConfigSchema = z.strictObject({
-  enabled: z.boolean(),
-  endpoint: nonEmptyStringSchema.optional(),
-  accessTokenField: nonEmptyStringSchema.optional(),
-  refreshTokenField: nonEmptyStringSchema.optional()
+  enabled: z.boolean().describe("Whether the client can exchange refresh tokens."),
+  endpoint: nonEmptyStringSchema.optional().describe("The API endpoint used to refresh tokens."),
+  accessTokenField: nonEmptyStringSchema.optional().describe("The response field containing the refreshed access token."),
+  refreshTokenField: nonEmptyStringSchema.optional().describe("The response field containing the refreshed refresh token.")
 }).superRefine(({ enabled, endpoint }, context) => {
   if (enabled && endpoint === void 0) {
     context.addIssue({
@@ -304,53 +318,57 @@ var tokenRefreshConfigSchema = z.strictObject({
   }
 });
 var clientOverrideShape = {
-  retry: clientRetryOverrideSchema.optional(),
-  responseHeaders: z.boolean().optional(),
-  responseValidation: z.boolean().optional(),
-  multiTenant: z.boolean().optional(),
-  additionalConstructorParameters: z.array(constructorParameterSchema).optional(),
-  timeoutMs: z.union([z.number().nonnegative(), z.literal("infinity")]).optional(),
-  requestParameterStyle: parameterStyleSchema.optional(),
-  pathParameterStyle: parameterStyleSchema.optional(),
-  filePropertyStyle: parameterStyleSchema.optional(),
-  useDefaultRequestParameterValues: z.boolean().optional(),
-  respectOptionalRequestBody: z.boolean().optional(),
-  tokenRefresh: tokenRefreshConfigSchema.optional()
+  retry: clientRetryOverrideSchema.optional().describe("Retry behavior for generated API requests."),
+  responseHeaders: z.boolean().optional().describe("Whether generated operations expose HTTP response headers."),
+  responseValidation: z.boolean().optional().describe("Whether the client validates API responses against the schema."),
+  multiTenant: z.boolean().optional().describe("Whether the client exposes configuration for tenant-specific API access."),
+  additionalConstructorParameters: z.array(constructorParameterSchema).optional().describe("Additional parameters added to the generated client constructor."),
+  timeoutMs: z.union([z.number().nonnegative(), z.literal("infinity")]).optional().describe('The default request timeout in milliseconds, or "infinity" for no timeout.'),
+  requestParameterStyle: parameterStyleSchema.optional().describe("Whether generated operation parameters are wrapped or passed inline."),
+  pathParameterStyle: parameterStyleSchema.optional().describe("Whether generated path parameters are wrapped or passed inline."),
+  filePropertyStyle: parameterStyleSchema.optional().describe("Whether generated file properties are wrapped or passed inline."),
+  useDefaultRequestParameterValues: z.boolean().optional().describe("Whether schema defaults are applied to omitted request parameters."),
+  respectOptionalRequestBody: z.boolean().optional().describe("Whether an optional request body remains optional in generated methods."),
+  tokenRefresh: tokenRefreshConfigSchema.optional().describe("Refresh-token behavior for the generated client.")
 };
 var clientConfigOverrideSchema = z.strictObject(clientOverrideShape);
 var clientConfigSchema = z.strictObject({
   ...clientOverrideShape,
-  retry: retryConfigSchema.prefault({}),
-  responseHeaders: z.boolean().default(false),
-  multiTenant: z.boolean().default(false),
-  additionalConstructorParameters: z.array(constructorParameterSchema).default([])
+  retry: retryConfigSchema.prefault({}).describe("Retry behavior for generated API requests."),
+  responseHeaders: z.boolean().default(false).describe("Whether generated operations expose HTTP response headers."),
+  multiTenant: z.boolean().default(false).describe("Whether the client exposes configuration for tenant-specific API access."),
+  additionalConstructorParameters: z.array(constructorParameterSchema).default([]).describe("Additional parameters added to the generated client constructor.")
 });
 var unsupportedFieldSchema = z.strictObject({
-  source: z.enum(["fern", "postman", "sdk-config-ir"]),
-  path: z.array(z.union([nonEmptyStringSchema, z.number().int().nonnegative()])).min(1),
-  code: nonEmptyStringSchema.optional(),
-  reason: nonEmptyStringSchema,
-  severity: z.enum(["error", "warning", "info"]),
-  risk: z.enum(["high", "medium", "low"]),
-  owner: nonEmptyStringSchema,
-  suggestedAction: nonEmptyStringSchema
+  source: z.enum(["fern", "postman", "sdk-config-ir"]).describe("The configuration surface containing the unsupported field."),
+  path: z.array(z.union([nonEmptyStringSchema, z.number().int().nonnegative()])).min(1).describe("The property path to the unsupported field in its source configuration."),
+  code: nonEmptyStringSchema.optional().describe("A stable diagnostic code for the unsupported field."),
+  reason: nonEmptyStringSchema.describe(
+    "Why the field could not be represented in normalized configuration."
+  ),
+  severity: z.enum(["error", "warning", "info"]).describe("The diagnostic severity."),
+  risk: z.enum(["high", "medium", "low"]).describe("The migration risk of omitting this field."),
+  owner: nonEmptyStringSchema.describe("The component or team responsible for resolving the gap."),
+  suggestedAction: nonEmptyStringSchema.describe(
+    "Recommended action for preserving the intended behavior."
+  )
 });
 var postmanLegacyInputSchema = z.strictObject({
-  kind: z.literal("postman-build-parameters"),
-  value: jsonObjectSchema
+  kind: z.literal("postman-build-parameters").describe("Identifies legacy Postman build parameters."),
+  value: jsonObjectSchema.describe("A debugging copy of the original Postman build parameters.")
 });
 var fernLegacyInputSchema = z.strictObject({
-  kind: z.literal("fern-generator-invocation"),
-  value: jsonObjectSchema
+  kind: z.literal("fern-generator-invocation").describe("Identifies a legacy Fern generator invocation."),
+  value: jsonObjectSchema.describe("A debugging copy of the original Fern generator invocation.")
 });
 var legacyInputSchema = z.discriminatedUnion("kind", [
   postmanLegacyInputSchema,
   fernLegacyInputSchema
 ]);
 var compatibilityConfigSchema = z.strictObject({
-  outputProfile: z.enum(["converged", "postman-legacy", "fern-legacy"]),
-  legacyInput: legacyInputSchema.optional(),
-  unsupportedFields: z.array(unsupportedFieldSchema).optional()
+  outputProfile: z.enum(["converged", "postman-legacy", "fern-legacy"]).describe("The output-default profile retained while legacy producers converge."),
+  legacyInput: legacyInputSchema.optional().describe("Original producer input retained only for migration debugging."),
+  unsupportedFields: z.array(unsupportedFieldSchema).optional().describe("Legacy fields that could not be represented in normalized configuration.")
 });
 var httpMethodSchema = z.enum([
   "GET",
@@ -364,116 +382,122 @@ var httpMethodSchema = z.enum([
   "CONNECT"
 ]);
 var readmeEndpointSchema = z.strictObject({
-  method: httpMethodSchema,
-  path: nonEmptyStringSchema,
-  stream: z.boolean().optional()
+  method: httpMethodSchema.describe("The HTTP method of the documented endpoint."),
+  path: nonEmptyStringSchema.describe("The endpoint path used in generated examples."),
+  stream: z.boolean().optional().describe("Whether the example uses the streaming response API.")
 });
 var readmeCustomSectionSchema = z.strictObject({
-  title: nonEmptyStringSchema,
-  content: z.string()
+  title: nonEmptyStringSchema.describe("The heading displayed for this README section."),
+  content: z.string().describe("The Markdown content of this README section.")
 });
 var readmeConfigSchema = z.strictObject({
-  apiName: nonEmptyStringSchema.optional(),
-  introduction: z.string().optional(),
-  apiReferenceLink: nonEmptyStringSchema.optional(),
-  bannerLink: nonEmptyStringSchema.optional(),
-  disabledSections: z.array(nonEmptyStringSchema).optional(),
-  customSections: z.array(readmeCustomSectionSchema).optional(),
-  defaultEndpoint: readmeEndpointSchema.optional(),
-  features: z.record(z.string(), z.array(readmeEndpointSchema)).optional()
+  apiName: nonEmptyStringSchema.optional().describe("The API name displayed in the README."),
+  introduction: z.string().optional().describe("Custom introductory Markdown for the README."),
+  apiReferenceLink: nonEmptyStringSchema.optional().describe("The URL linked as the API reference."),
+  bannerLink: nonEmptyStringSchema.optional().describe("The destination URL for the README banner."),
+  disabledSections: z.array(nonEmptyStringSchema).optional().describe("Generated README sections to omit."),
+  customSections: z.array(readmeCustomSectionSchema).optional().describe("Additional sections inserted into the README."),
+  defaultEndpoint: readmeEndpointSchema.optional().describe("The endpoint used for the primary README example."),
+  features: z.record(z.string(), z.array(readmeEndpointSchema)).optional().describe("Named feature groups and the endpoints demonstrated by each group.")
 });
 var snippetsConfigSchema = z.strictObject({
-  enabled: z.boolean(),
-  format: z.enum(["md", "json"]).optional(),
-  outputPath: nonEmptyStringSchema.optional()
+  enabled: z.boolean().describe("Whether standalone usage snippets are generated."),
+  format: z.enum(["md", "json"]).optional().describe("The output format for generated snippets."),
+  outputPath: nonEmptyStringSchema.optional().describe("The output path for generated snippet files.")
 });
 var docsConfigSchema = z.strictObject({
-  readme: readmeConfigSchema.optional(),
-  snippets: snippetsConfigSchema.optional(),
-  referenceBaseUrl: nonEmptyStringSchema.optional(),
-  includeApiReference: z.boolean().optional()
+  readme: readmeConfigSchema.optional().describe("README content and example configuration."),
+  snippets: snippetsConfigSchema.optional().describe("Standalone usage snippet generation."),
+  referenceBaseUrl: nonEmptyStringSchema.optional().describe("The base URL used for links to generated API reference files."),
+  includeApiReference: z.boolean().optional().describe("Whether API reference documentation is included in the SDK output.")
 });
 var namingConfigSchema = z.strictObject({
-  clientName: nonEmptyStringSchema.optional(),
-  exportedClientName: nonEmptyStringSchema.optional(),
-  environmentTypeName: nonEmptyStringSchema.optional(),
-  apiErrorName: nonEmptyStringSchema.optional(),
-  baseErrorName: nonEmptyStringSchema.optional(),
-  pagerName: nonEmptyStringSchema.optional(),
+  clientName: nonEmptyStringSchema.optional().describe("The generated client class name."),
+  exportedClientName: nonEmptyStringSchema.optional().describe("The client name exported from the generated package."),
+  environmentTypeName: nonEmptyStringSchema.optional().describe("The generated type name for API environments."),
+  apiErrorName: nonEmptyStringSchema.optional().describe("The generated API error class name."),
+  baseErrorName: nonEmptyStringSchema.optional().describe("The generated base error class name."),
+  pagerName: nonEmptyStringSchema.optional().describe("The generated pagination helper name."),
   /** Apply Fern's initialism-aware casing rules when deriving generated identifiers. */
-  smartCasing: z.boolean().optional(),
+  smartCasing: z.boolean().optional().describe("Whether generated identifiers use initialism-aware casing."),
   /** Preserve a word boundary after digits when Fern smart casing is enabled. */
-  smartCasingDigitWordBoundary: z.boolean().optional()
+  smartCasingDigitWordBoundary: z.boolean().optional().describe("Whether smart casing preserves a word boundary after digits.")
 });
 var cliGenerationConfigSchema = z.strictObject({
-  paginationParameters: z.array(nonEmptyStringSchema).optional(),
-  skills: z.boolean().optional()
+  paginationParameters: z.array(nonEmptyStringSchema).optional().describe("Request parameter names treated as pagination controls by the CLI."),
+  skills: z.boolean().optional().describe("Whether the generated CLI includes skills that teach AI agents to invoke commands.")
 });
 var csharpGenerationConfigSchema = z.strictObject({
-  useOptionalWrapper: z.boolean().optional(),
-  simplifyObjectDictionaries: z.boolean().optional(),
-  explicitNamespaces: z.boolean().optional(),
-  rootNamespaceForCoreClasses: z.boolean().optional(),
-  includeExceptionHandler: z.boolean().optional(),
-  experimentalExplicitNullableOptional: z.boolean().optional()
+  useOptionalWrapper: z.boolean().optional().describe("Whether optional values use an explicit Optional wrapper."),
+  simplifyObjectDictionaries: z.boolean().optional().describe("Whether object schemas with arbitrary values use simplified dictionary types."),
+  explicitNamespaces: z.boolean().optional().describe("Whether generated resource groups use explicit nested namespaces."),
+  rootNamespaceForCoreClasses: z.boolean().optional().describe("Whether shared client classes are emitted in the root namespace."),
+  includeExceptionHandler: z.boolean().optional().describe("Whether generated client operations use a configurable exception handler."),
+  experimentalExplicitNullableOptional: z.boolean().optional().describe(
+    "Whether optional nullable properties distinguish omitted values from explicit nulls."
+  )
 });
 var goGenerationConfigSchema = z.strictObject({
-  legacyComplexModels: z.boolean().optional(),
+  legacyComplexModels: z.boolean().optional().describe("Whether complex models use the legacy Go representation."),
   /** Uppercase common initialisms in generated names (`UserID` rather than `UserId`). */
-  smartCasing: z.boolean().optional(),
+  smartCasing: z.boolean().optional().describe("Whether generated Go names capitalize common initialisms."),
   /** Overrides the fern root-client constructor independently from the client type name. */
-  clientConstructorName: nonEmptyStringSchema.optional(),
-  unionVersion: z.enum(["v0", "v1"]).optional(),
-  includeLegacyClientOptions: z.boolean().optional()
+  clientConstructorName: nonEmptyStringSchema.optional().describe("The generated root-client constructor name."),
+  unionVersion: z.enum(["v0", "v1"]).optional().describe("The representation used for generated Go unions."),
+  includeLegacyClientOptions: z.boolean().optional().describe("Whether the client retains legacy constructor option helpers.")
 });
 var jvmGenerationConfigSchema = z.strictObject({
-  packageLayout: z.enum(["flat", "nested"]).optional(),
-  useLocalDateForDates: z.boolean().optional(),
-  collapseOptionalNullable: z.boolean().optional(),
-  gradleDistributionUrl: z.string().min(1).optional(),
-  gradlePluginManagement: z.string().optional(),
-  gradleCentralDependencyManagement: z.boolean().optional(),
+  packageLayout: z.enum(["flat", "nested"]).optional().describe("Whether generated JVM packages use a flat or nested resource layout."),
+  useLocalDateForDates: z.boolean().optional().describe("Whether date-only values use LocalDate instead of OffsetDateTime."),
+  collapseOptionalNullable: z.boolean().optional().describe("Whether optional nullable values collapse into a single nullable representation."),
+  gradleDistributionUrl: z.string().min(1).optional().describe("The Gradle distribution URL written to the generated wrapper."),
+  gradlePluginManagement: z.string().optional().describe("Plugin management configuration added to the generated Gradle settings."),
+  gradleCentralDependencyManagement: z.boolean().optional().describe("Whether dependency versions are managed centrally in the Gradle project."),
   /** Selects co-located async methods or a separate async client surface. */
-  asyncStyle: z.enum(["dedicated-client", "twin-methods"]).optional()
+  asyncStyle: z.enum(["dedicated-client", "twin-methods"]).optional().describe("Whether asynchronous operations use a separate client or co-located methods.")
 });
 
 // src/sdk-config-domain/v1/language/java.ts
 var javaGenerationConfigSchema = jvmGenerationConfigSchema.extend({
-  includeKotlinSnippets: z.boolean().optional()
+  includeKotlinSnippets: z.boolean().optional().describe("Whether Java SDK documentation includes Kotlin usage snippets.")
 });
 
 // src/sdk-config-domain/v1/language/kotlin.ts
 var kotlinGenerationConfigSchema = jvmGenerationConfigSchema;
 var compilerOptionsSchema = z.strictObject({
-  target: nonEmptyStringSchema.optional(),
-  module: nonEmptyStringSchema.optional(),
-  lib: z.array(nonEmptyStringSchema).optional()
+  target: nonEmptyStringSchema.optional().describe("The JavaScript language target passed to TypeScript."),
+  module: nonEmptyStringSchema.optional().describe("The module format passed to TypeScript."),
+  lib: z.array(nonEmptyStringSchema).optional().describe("The runtime library definitions passed to TypeScript.")
 });
 var packageScriptSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  command: nonEmptyStringSchema
+  name: nonEmptyStringSchema.describe("The package script name."),
+  command: nonEmptyStringSchema.describe("The command executed by the package script.")
 });
 var httpClientSchema = z.strictObject({
-  name: z.enum(["axios", "fetch"])
+  name: z.enum(["axios", "fetch"]).describe("The HTTP client used by generated TypeScript code.")
 });
 var typescriptGenerationConfigSchema = z.strictObject({
-  typescriptVersion: nonEmptyStringSchema.optional(),
-  zodVersion: nonEmptyStringSchema.optional(),
-  compilerOptions: compilerOptionsSchema.optional(),
-  httpClient: httpClientSchema.optional(),
-  packageManager: z.enum(["pnpm", "yarn"]).optional(),
-  testFramework: z.enum(["jest", "vitest"]).optional(),
-  namingStrategy: z.enum(["base", "originalPropertyNames"]).optional(),
-  bundle: z.boolean().optional(),
-  exportClassDefault: z.boolean().optional(),
+  typescriptVersion: nonEmptyStringSchema.optional().describe("The TypeScript version used by the generated project."),
+  zodVersion: nonEmptyStringSchema.optional().describe("The Zod version used by generated runtime schemas."),
+  compilerOptions: compilerOptionsSchema.optional().describe("TypeScript compiler options for the generated project."),
+  httpClient: httpClientSchema.optional().describe("The HTTP client used by generated TypeScript code."),
+  packageManager: z.enum(["pnpm", "yarn"]).optional().describe("The package manager used by the generated project."),
+  packageManagerVersion: nonEmptyStringSchema.optional().describe("The package manager version used by the generated project."),
+  testFramework: z.enum(["jest", "vitest"]).optional().describe("The test framework used by generated tests."),
+  namingStrategy: z.enum(["base", "originalPropertyNames"]).optional().describe("How schema property names are converted into TypeScript identifiers."),
+  bundle: z.boolean().optional().describe("Whether the generated package includes bundled output."),
+  exportClassDefault: z.boolean().optional().describe("Whether the client class is also exported as the default export."),
   /** Name of the top-level namespace export emitted by Fern-compatible TypeScript SDKs. */
-  namespaceExportName: nonEmptyStringSchema.optional(),
-  allowCustomFetcher: z.boolean().optional(),
-  useBrandedStringAliases: z.boolean().optional(),
-  useLegacyExports: z.boolean().optional(),
-  useBigInt: z.boolean().optional(),
-  serdeLayer: z.boolean().optional(),
-  scripts: z.array(packageScriptSchema).optional()
+  namespaceExportName: nonEmptyStringSchema.optional().describe("The top-level namespace export name."),
+  consolidateTypeFiles: z.boolean().optional().describe("Whether generated types are consolidated into fewer source files."),
+  allowCustomFetcher: z.boolean().optional().describe("Whether callers can supply a custom fetch implementation."),
+  useBrandedStringAliases: z.boolean().optional().describe("Whether string aliases are emitted as distinct branded types."),
+  useLegacyExports: z.boolean().optional().describe("Whether the package emits the legacy export layout."),
+  useBigInt: z.boolean().optional().describe("Whether 64-bit integer values are represented with bigint."),
+  serdeLayer: z.boolean().optional().describe("Whether generated models use Fern serialization and deserialization helpers."),
+  /** Ship only the ESM build (drops CJS) to avoid the Node dual-package hazard. */
+  esmOnly: z.boolean().optional().describe("Whether the package emits only ECMAScript modules."),
+  scripts: z.array(packageScriptSchema).optional().describe("Additional scripts added to the generated package manifest.")
 });
 
 // src/sdk-config-domain/v1/language/mcp.ts
@@ -488,75 +512,75 @@ var mcpAvailabilityStatuses = [
   "LEGACY"
 ];
 var mcpToolFilterSchema = z.strictObject({
-  include: z.array(nonEmptyStringSchema).optional(),
-  exclude: z.array(nonEmptyStringSchema).optional()
+  include: z.array(nonEmptyStringSchema).optional().describe("Operations explicitly included as MCP tools."),
+  exclude: z.array(nonEmptyStringSchema).optional().describe("Operations explicitly excluded from MCP tools.")
 });
 var mcpToolsetNameSchema = nonEmptyStringSchema.refine(
   (name) => name !== "default" && /^[a-z0-9-]+$/.test(name),
   'toolset names must match [a-z0-9-]+ and cannot be "default"'
 );
 var mcpGenerationConfigSchema = typescriptGenerationConfigSchema.extend({
-  serverName: nonEmptyStringSchema.optional(),
-  serverDescription: nonEmptyStringSchema.optional(),
-  excludeAvailability: z.array(z.enum(mcpAvailabilityStatuses)).optional(),
-  tools: mcpToolFilterSchema.optional(),
-  toolsets: z.record(mcpToolsetNameSchema, mcpToolFilterSchema).optional()
+  serverName: nonEmptyStringSchema.optional().describe("The name advertised by the generated MCP server."),
+  serverDescription: nonEmptyStringSchema.optional().describe("The description advertised by the generated MCP server."),
+  excludeAvailability: z.array(z.enum(mcpAvailabilityStatuses)).optional().describe("Operation availability statuses excluded from MCP tool generation."),
+  tools: mcpToolFilterSchema.optional().describe("Global operation filters for generated MCP tools."),
+  toolsets: z.record(mcpToolsetNameSchema, mcpToolFilterSchema).optional().describe("Named MCP toolsets and the operation filters for each toolset.")
 });
 var phpGenerationConfigSchema = z.strictObject({
-  propertyAccess: z.enum(["public", "private"]).optional(),
-  generateClientInterfaces: z.boolean().optional()
+  propertyAccess: z.enum(["public", "private"]).optional().describe("The visibility of generated PHP model properties."),
+  generateClientInterfaces: z.boolean().optional().describe("Whether interfaces are generated for PHP client classes.")
 });
 var pythonClientSchema = z.strictObject({
-  fileName: nonEmptyStringSchema.optional(),
-  exportedFileName: nonEmptyStringSchema.optional()
+  fileName: nonEmptyStringSchema.optional().describe("The source file name for the Python client."),
+  exportedFileName: nonEmptyStringSchema.optional().describe("The file name used when exporting the Python client.")
 });
 var pydanticConfigSchema = z.strictObject({
-  versionCompatibility: z.enum(["v1", "v2", "both", "v1-on-v2"]).optional(),
-  frozen: z.boolean().optional(),
-  requireOptionalFields: z.boolean().optional(),
-  unionNaming: z.enum(["v0", "v1"]).optional(),
-  useFieldAliases: z.boolean().optional()
+  versionCompatibility: z.enum(["v1", "v2", "both", "v1-on-v2"]).optional().describe("The Pydantic major versions supported by generated models."),
+  frozen: z.boolean().optional().describe("Whether generated Pydantic models are immutable."),
+  requireOptionalFields: z.boolean().optional().describe("Whether Optional fields remain required unless they declare a default."),
+  unionNaming: z.enum(["v0", "v1"]).optional().describe("The naming strategy for generated union types."),
+  useFieldAliases: z.boolean().optional().describe("Whether Pydantic field aliases preserve wire names.")
 });
 var additionalInitExportSchema = z.strictObject({
-  from: nonEmptyStringSchema,
-  imports: z.array(nonEmptyStringSchema).min(1)
+  from: nonEmptyStringSchema.describe("The module from which names are re-exported."),
+  imports: z.array(nonEmptyStringSchema).min(1).describe("Names re-exported from the module.")
 });
 var pythonGenerationConfigSchema = z.strictObject({
-  pythonVersion: nonEmptyStringSchema.optional(),
-  pydanticVersion: nonEmptyStringSchema.optional(),
-  pydantic: pydanticConfigSchema.optional(),
-  client: pythonClientSchema.optional(),
+  pythonVersion: nonEmptyStringSchema.optional().describe("The Python version targeted by the generated project."),
+  pydanticVersion: nonEmptyStringSchema.optional().describe("The Pydantic dependency version requirement."),
+  pydantic: pydanticConfigSchema.optional().describe("Pydantic model-generation behavior."),
+  client: pythonClientSchema.optional().describe("Python client file naming."),
   /** Default followed by generated sync and async HTTP clients when the caller does not override it. */
-  followRedirectsByDefault: z.boolean().optional(),
+  followRedirectsByDefault: z.boolean().optional().describe("Whether generated HTTP clients follow redirects by default."),
   /** Chunk size passed to Python byte-stream iterators. */
-  defaultBytesStreamChunkSize: z.number().int().positive().optional(),
+  defaultBytesStreamChunkSize: z.number().int().positive().optional().describe("The default byte-stream iterator chunk size."),
   /** Python interpreter recursion limit installed by the generated package at import time. */
-  recursionLimit: z.number().int().gt(1e3).optional(),
+  recursionLimit: z.number().int().gt(1e3).optional().describe("The Python recursion limit installed when the generated package is imported."),
   /** Published Python extras, keyed by extra name with package dependency names as values. */
-  extras: z.record(nonEmptyStringSchema, z.array(nonEmptyStringSchema)).optional(),
-  alwaysInitializeOptionals: z.boolean().optional(),
-  useTypedDictRequests: z.boolean().optional(),
-  additionalInitExports: z.array(additionalInitExportSchema).optional()
+  extras: z.record(nonEmptyStringSchema, z.array(nonEmptyStringSchema)).optional().describe("Published Python extras and their dependency names."),
+  alwaysInitializeOptionals: z.boolean().optional().describe("Whether optional model fields are initialized even when omitted."),
+  useTypedDictRequests: z.boolean().optional().describe("Whether request bodies are generated as TypedDict types."),
+  additionalInitExports: z.array(additionalInitExportSchema).optional().describe("Additional names re-exported from the package initializer.")
 });
 var rubyGenerationConfigSchema = z.strictObject({
-  requirePaths: z.array(nonEmptyStringSchema).optional()
+  requirePaths: z.array(nonEmptyStringSchema).optional().describe("Ruby load paths included in the generated gem specification.")
 });
 var rustGenerationConfigSchema = z.strictObject({
   /**
    * Rust type for datetime primitives. `offset` maps to `DateTime<FixedOffset>` and preserves the
    * timezone the payload carried; `utc` maps to `DateTime<Utc>` and normalizes to UTC.
    */
-  dateTimeType: z.enum(["offset", "utc"]).optional(),
+  dateTimeType: z.enum(["offset", "utc"]).optional().describe("Whether datetime values preserve their offset or normalize to UTC."),
   /** Uppercase common initialisms in generated names (`UserID` rather than `UserId`). */
-  capitalizeInitialisms: z.boolean().optional(),
+  capitalizeInitialisms: z.boolean().optional().describe("Whether generated Rust names capitalize common initialisms."),
   /** Cargo features, mapping a feature name to the dependencies or features it enables. */
-  features: z.record(z.string(), z.array(nonEmptyStringSchema)).optional(),
+  features: z.record(z.string(), z.array(nonEmptyStringSchema)).optional().describe("Cargo features and the dependencies or features each enables."),
   /** Overrides which features make up Cargo's `default` feature set. */
-  defaultFeatures: z.array(nonEmptyStringSchema).optional()
+  defaultFeatures: z.array(nonEmptyStringSchema).optional().describe("Cargo features included in the crate default feature set.")
 });
 var swiftGenerationConfigSchema = z.strictObject({
-  moduleName: nonEmptyStringSchema.optional(),
-  nullableAsOptional: z.boolean().optional()
+  moduleName: nonEmptyStringSchema.optional().describe("The Swift module name for the generated package."),
+  nullableAsOptional: z.boolean().optional().describe("Whether nullable values are represented as Swift optionals.")
 });
 var goModulePathSchema = relativePathSchema.regex(
   /^(?!.*(?:^|\/)\.{1,2}(?:\/|$))[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/,
@@ -567,140 +591,166 @@ var composerPackageNameSchema = nonEmptyStringSchema.regex(
   'Composer package name must be a lowercase "vendor/package" name'
 );
 var authorSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  email: z.email().optional(),
-  url: nonEmptyStringSchema.optional()
+  name: nonEmptyStringSchema.describe("The package author name."),
+  email: z.email().optional().describe("The package author email address."),
+  url: nonEmptyStringSchema.optional().describe("The package author website.")
 });
 var developerSchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  email: z.email().optional(),
-  organization: nonEmptyStringSchema.optional(),
-  organizationUrl: nonEmptyStringSchema.optional()
+  name: nonEmptyStringSchema.describe("The package developer name."),
+  email: z.email().optional().describe("The package developer email address."),
+  organization: nonEmptyStringSchema.optional().describe("The developer organization name."),
+  organizationUrl: nonEmptyStringSchema.optional().describe("The developer organization website.")
 });
 var licenseSchema = z.strictObject({
-  type: nonEmptyStringSchema,
-  name: nonEmptyStringSchema.optional(),
-  url: nonEmptyStringSchema.optional(),
-  path: nonEmptyStringSchema.optional()
+  type: nonEmptyStringSchema.describe("The license identifier or license type."),
+  name: nonEmptyStringSchema.optional().describe("The human-readable license name."),
+  url: nonEmptyStringSchema.optional().describe("The URL containing the license text."),
+  path: nonEmptyStringSchema.optional().describe("The path to a custom license file.")
 });
 var dependencySourceSchema = z.discriminatedUnion("type", [
   z.strictObject({
-    type: z.literal("registry"),
-    registry: nonEmptyStringSchema.optional()
+    type: z.literal("registry").describe("Resolves the dependency from a package registry."),
+    registry: nonEmptyStringSchema.optional().describe("The registry used to resolve the dependency.")
   }),
   z.strictObject({
-    type: z.literal("git"),
-    url: nonEmptyStringSchema,
-    ref: nonEmptyStringSchema.optional(),
-    subdirectory: nonEmptyStringSchema.optional()
+    type: z.literal("git").describe("Resolves the dependency from a Git repository."),
+    url: nonEmptyStringSchema.describe("The Git repository URL."),
+    ref: nonEmptyStringSchema.optional().describe("The Git branch, tag, or commit to use."),
+    subdirectory: nonEmptyStringSchema.optional().describe("The package subdirectory within the Git repository.")
   }),
   z.strictObject({
-    type: z.literal("path"),
-    path: nonEmptyStringSchema
+    type: z.literal("path").describe("Resolves the dependency from a local path."),
+    path: nonEmptyStringSchema.describe("The local path containing the dependency.")
   })
 ]);
 var dependencySchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  version: nonEmptyStringSchema.optional(),
-  source: dependencySourceSchema.optional(),
-  packageName: nonEmptyStringSchema.optional(),
-  features: z.array(nonEmptyStringSchema).optional(),
-  extras: z.array(nonEmptyStringSchema).optional(),
-  optional: z.boolean().optional(),
-  defaultFeatures: z.boolean().optional(),
-  environmentMarker: nonEmptyStringSchema.optional()
+  name: nonEmptyStringSchema.describe("The dependency name used by the package manager."),
+  version: nonEmptyStringSchema.optional().describe("The dependency version requirement."),
+  source: dependencySourceSchema.optional().describe("A non-default source for the dependency."),
+  packageName: nonEmptyStringSchema.optional().describe("The source package name when it differs from the dependency alias."),
+  features: z.array(nonEmptyStringSchema).optional().describe("Cargo features enabled for this dependency."),
+  extras: z.array(nonEmptyStringSchema).optional().describe("Python extras enabled for this dependency."),
+  optional: z.boolean().optional().describe("Whether the dependency is optional."),
+  defaultFeatures: z.boolean().optional().describe("Whether the dependency enables its default Cargo features."),
+  environmentMarker: nonEmptyStringSchema.optional().describe("A Python environment marker that conditions this dependency.")
 }).refine(({ source, version }) => source !== void 0 || version !== void 0, {
   message: "dependency must define a version or a source"
 });
 var projectUrlSchema = z.strictObject({
-  label: nonEmptyStringSchema,
-  url: nonEmptyStringSchema
+  label: nonEmptyStringSchema.describe("The label displayed for the project link."),
+  url: nonEmptyStringSchema.describe("The project link URL.")
 });
 var packageConfigSchema = z.strictObject({
-  packageName: nonEmptyStringSchema.optional(),
-  moduleName: nonEmptyStringSchema.optional(),
-  modulePath: goModulePathSchema.optional(),
-  namespace: nonEmptyStringSchema.optional(),
-  groupId: nonEmptyStringSchema.optional(),
-  artifactId: nonEmptyStringSchema.optional(),
-  description: z.string().optional(),
-  repository: nonEmptyStringSchema.optional(),
-  homepage: nonEmptyStringSchema.optional(),
-  documentationUrl: nonEmptyStringSchema.optional(),
-  authors: z.array(authorSchema).optional(),
-  developers: z.array(developerSchema).optional(),
-  license: licenseSchema.optional(),
-  keywords: z.array(nonEmptyStringSchema).optional(),
-  classifiers: z.array(nonEmptyStringSchema).optional(),
-  projectUrls: z.array(projectUrlSchema).optional(),
-  extraDependencies: z.array(dependencySchema).optional(),
-  extraDevDependencies: z.array(dependencySchema).optional(),
-  extraPeerDependencies: z.array(dependencySchema).optional()
+  packageName: nonEmptyStringSchema.optional().describe("The package name used by the target language registry."),
+  moduleName: nonEmptyStringSchema.optional().describe("The generated module or import name when it differs from the package name."),
+  modulePath: goModulePathSchema.optional().describe("The Go module path used for imports and publishing."),
+  namespace: nonEmptyStringSchema.optional().describe("The namespace or package prefix for generated code."),
+  groupId: nonEmptyStringSchema.optional().describe("The Maven group identifier."),
+  artifactId: nonEmptyStringSchema.optional().describe("The Maven artifact identifier."),
+  description: z.string().optional().describe("The package description used in generated metadata."),
+  repository: nonEmptyStringSchema.optional().describe("The source repository for the generated SDK."),
+  homepage: nonEmptyStringSchema.optional().describe("The package homepage URL."),
+  documentationUrl: nonEmptyStringSchema.optional().describe("The package documentation URL."),
+  authors: z.array(authorSchema).optional().describe("Authors credited in package metadata."),
+  developers: z.array(developerSchema).optional().describe("Developers credited in package metadata."),
+  license: licenseSchema.optional().describe("License metadata for the generated package."),
+  keywords: z.array(nonEmptyStringSchema).optional().describe("Search keywords for package metadata."),
+  classifiers: z.array(nonEmptyStringSchema).optional().describe("Package classifiers used by registries such as PyPI."),
+  projectUrls: z.array(projectUrlSchema).optional().describe("Labeled project links for package metadata."),
+  extraDependencies: z.array(dependencySchema).optional().describe("Additional runtime dependencies added to the generated package."),
+  extraDevDependencies: z.array(dependencySchema).optional().describe("Additional development dependencies added to the generated package."),
+  extraPeerDependencies: z.array(dependencySchema).optional().describe("Additional peer dependencies added to the generated package.")
 });
 
 // src/sdk-config-domain/v1/language/terraform.ts
 var planModifierSourceSchema = z.discriminatedUnion("enabled", [
-  z.strictObject({ enabled: z.literal(true), sourceDir: nonEmptyStringSchema }),
-  z.strictObject({ enabled: z.literal(false) })
+  z.strictObject({
+    enabled: z.literal(true).describe("Enables custom Terraform plan modifiers."),
+    sourceDir: nonEmptyStringSchema.describe(
+      "The directory containing custom plan modifier source files."
+    )
+  }),
+  z.strictObject({
+    enabled: z.literal(false).describe("Disables custom Terraform plan modifiers.")
+  })
 ]);
 var planModifiersSchema = z.strictObject({
-  resources: planModifierSourceSchema,
-  attributes: planModifierSourceSchema
+  resources: planModifierSourceSchema.describe("Custom plan modifiers for generated resources."),
+  attributes: planModifierSourceSchema.describe("Custom plan modifiers for generated attributes.")
 });
 var providerSchemaSchema = z.strictObject({
-  addressKey: nonEmptyStringSchema,
-  authTokenKey: nonEmptyStringSchema
+  addressKey: nonEmptyStringSchema.describe(
+    "The provider attribute used to configure the API address."
+  ),
+  authTokenKey: nonEmptyStringSchema.describe(
+    "The provider attribute used to configure the authentication token."
+  )
 });
 var terraformGenerationConfigSchema = z.strictObject({
-  providerName: nonEmptyStringSchema.optional(),
-  providerVersion: nonEmptyStringSchema.optional(),
-  providerModulePath: goModulePathSchema.optional(),
-  mockAcceptance: z.boolean().optional(),
-  hideComputedDiff: z.boolean().optional(),
-  providerSchema: providerSchemaSchema.optional(),
-  planModifiers: planModifiersSchema.optional()
+  providerName: nonEmptyStringSchema.optional().describe("The Terraform provider name."),
+  providerVersion: nonEmptyStringSchema.optional().describe("The generated Terraform provider version."),
+  providerModulePath: goModulePathSchema.optional().describe("The Go module path for the generated provider."),
+  mockAcceptance: z.boolean().optional().describe("Whether acceptance tests use a mock API server."),
+  hideComputedDiff: z.boolean().optional().describe("Whether computed-only changes are hidden from Terraform plans."),
+  providerSchema: providerSchemaSchema.optional().describe("Names of provider-level configuration attributes."),
+  planModifiers: planModifiersSchema.optional().describe("Custom plan modifier source configuration.")
 });
 
 // src/sdk-config-ir/v1/generation.ts
 var generationAssetSchema = z.discriminatedUnion("type", [
-  z.strictObject({ type: z.literal("path"), location: relativePathSchema }),
-  z.strictObject({ type: z.literal("url"), location: nonEmptyStringSchema }),
-  z.strictObject({ type: z.literal("artifact"), location: nonEmptyStringSchema })
+  z.strictObject({
+    type: z.literal("path").describe("Loads the generation asset from a relative path."),
+    location: relativePathSchema.describe("The relative path to the generation asset.")
+  }),
+  z.strictObject({
+    type: z.literal("url").describe("Loads the generation asset from a URL."),
+    location: nonEmptyStringSchema.describe("The URL of the generation asset.")
+  }),
+  z.strictObject({
+    type: z.literal("artifact").describe("Loads the generation asset from stored build output."),
+    location: nonEmptyStringSchema.describe("The artifact identifier or location.")
+  })
 ]);
 var hookDependencySchema = z.strictObject({
-  name: nonEmptyStringSchema,
-  version: nonEmptyStringSchema,
-  groupId: nonEmptyStringSchema.optional()
+  name: nonEmptyStringSchema.describe("The hook dependency name."),
+  version: nonEmptyStringSchema.describe("The hook dependency version requirement."),
+  groupId: nonEmptyStringSchema.optional().describe("The Maven group identifier for the dependency.")
 });
 var hooksConfigSchema = z.strictObject({
-  enabled: z.boolean(),
-  source: generationAssetSchema.optional(),
-  dependencies: z.array(hookDependencySchema).optional()
+  enabled: z.boolean().describe("Whether custom request and response hooks are generated."),
+  source: generationAssetSchema.optional().describe("The source containing custom hook implementations."),
+  dependencies: z.array(hookDependencySchema).optional().describe("Dependencies required by custom hooks.")
 });
 var customCodeConfigSchema = z.strictObject({
-  enabled: z.boolean(),
-  source: generationAssetSchema.optional(),
-  conflictStrategy: z.enum(["mark", "ours", "theirs"]).optional(),
-  trackChanges: z.boolean().optional(),
-  previousBuildId: z.number().int().positive().optional(),
-  protectedFiles: z.array(nonEmptyStringSchema).optional()
+  enabled: z.boolean().describe("Whether customer-authored code is merged into generated output."),
+  source: generationAssetSchema.optional().describe("The source containing customer-authored code."),
+  conflictStrategy: z.enum(["mark", "ours", "theirs"]).optional().describe("How merge conflicts between generated and custom code are handled."),
+  trackChanges: z.boolean().optional().describe("Whether custom-code changes are tracked between builds."),
+  previousBuildId: z.number().int().positive().optional().describe("The previous build used as the merge baseline."),
+  protectedFiles: z.array(nonEmptyStringSchema).optional().describe("Generated file paths that custom-code merging must not overwrite.")
 });
 var workflowConfigSchema = z.strictObject({
-  path: relativePathSchema,
-  outputName: nonEmptyStringSchema.optional()
+  path: relativePathSchema.describe("The relative path to the workflow definition."),
+  outputName: nonEmptyStringSchema.optional().describe("The file name used for the generated workflow.")
 });
 var analyticsHeaderSchema = z.union([
-  z.strictObject({ name: nonEmptyStringSchema, value: z.string() }),
-  z.strictObject({ name: nonEmptyStringSchema, valueRef: nonEmptyStringSchema })
+  z.strictObject({
+    name: nonEmptyStringSchema.describe("The exported telemetry header name."),
+    value: z.string().describe("The literal telemetry header value.")
+  }),
+  z.strictObject({
+    name: nonEmptyStringSchema.describe("The exported telemetry header name."),
+    valueRef: nonEmptyStringSchema.describe("A reference to the telemetry header value.")
+  })
 ]);
 var analyticsConfigSchema = z.strictObject({
-  enabled: z.boolean(),
-  endpoint: nonEmptyStringSchema.optional(),
-  exporter: z.enum(["otlp-http", "console"]).optional(),
-  headers: z.array(analyticsHeaderSchema).optional(),
-  batchSize: z.number().int().positive().optional(),
-  scheduledDelayMs: z.number().nonnegative().optional(),
-  exportTimeoutMs: z.number().nonnegative().optional()
+  enabled: z.boolean().describe("Whether generated clients export usage telemetry."),
+  endpoint: nonEmptyStringSchema.optional().describe("The telemetry export endpoint."),
+  exporter: z.enum(["otlp-http", "console"]).optional().describe("The telemetry exporter implementation."),
+  headers: z.array(analyticsHeaderSchema).optional().describe("Headers sent by the telemetry exporter."),
+  batchSize: z.number().int().positive().optional().describe("The maximum spans in each export batch."),
+  scheduledDelayMs: z.number().nonnegative().optional().describe("The delay between scheduled exports, in milliseconds."),
+  exportTimeoutMs: z.number().nonnegative().optional().describe("The maximum time allowed for an export, in milliseconds.")
 }).superRefine(({ enabled, endpoint }, context) => {
   if (enabled && endpoint === void 0) {
     context.addIssue({
@@ -711,91 +761,93 @@ var analyticsConfigSchema = z.strictObject({
   }
 });
 var wireTestsSchema = z.strictObject({
-  enabled: z.boolean(),
-  exclusions: z.array(nonEmptyStringSchema).optional(),
-  fallbackToGeneratedErrorExamples: z.boolean().optional(),
-  fixtureSource: z.enum(["synthetic", "recorded", "auto"]).optional()
+  enabled: z.boolean().describe("Whether wire-level request and response tests are generated."),
+  exclusions: z.array(nonEmptyStringSchema).optional().describe("Operations excluded from wire tests."),
+  fallbackToGeneratedErrorExamples: z.boolean().optional().describe("Whether missing error fixtures are synthesized from generated examples."),
+  fixtureSource: z.enum(["synthetic", "recorded", "auto"]).optional().describe("Where wire-test fixtures are obtained.")
 });
 var unitTestsSchema = z.strictObject({
-  enabled: z.boolean(),
-  mode: z.enum(["core-runtime", "schema-driven", "both"]).optional(),
-  exclusions: z.array(nonEmptyStringSchema).optional()
+  enabled: z.boolean().describe("Whether SDK unit tests are generated."),
+  mode: z.enum(["core-runtime", "schema-driven", "both"]).optional().describe("The unit-test generation strategy."),
+  exclusions: z.array(nonEmptyStringSchema).optional().describe("Operations excluded from unit tests.")
 });
 var fernDefinitionMetadataSchema = z.strictObject({
-  definitionS3DownloadUrl: nonEmptyStringSchema,
-  outputPath: nonEmptyStringSchema.optional(),
-  cliVersion: nonEmptyStringSchema.optional()
+  definitionS3DownloadUrl: nonEmptyStringSchema.describe(
+    "The download URL for the materialized Fern definition archive."
+  ),
+  outputPath: nonEmptyStringSchema.optional().describe("The destination path for Fern definition support files."),
+  cliVersion: nonEmptyStringSchema.optional().describe("The Fern CLI version associated with the definition.")
 });
 var streamsSchema = z.strictObject({
-  enabled: z.boolean(),
-  responseType: z.enum(["wrapper", "native", "web"]).optional(),
-  fileResponseType: z.enum(["stream", "binary-response"]).optional(),
-  defaultChunkSizeBytes: z.number().int().positive().optional()
+  enabled: z.boolean().describe("Whether generated clients expose streaming response APIs."),
+  responseType: z.enum(["wrapper", "native", "web"]).optional().describe("The streaming response abstraction exposed by generated clients."),
+  fileResponseType: z.enum(["stream", "binary-response"]).optional().describe("The response type used for file downloads."),
+  defaultChunkSizeBytes: z.number().int().positive().optional().describe("The default number of bytes yielded by streaming iterators.")
 });
 var layoutConfigSchema = z.strictObject({
-  outputDirectory: z.enum(["project-root", "source-root"]).optional(),
-  packagePath: nonEmptyStringSchema.optional()
+  outputDirectory: z.enum(["project-root", "source-root"]).optional().describe("Whether generated source is rooted at the project or its source directory."),
+  packagePath: nonEmptyStringSchema.optional().describe("The package-relative path for generated source files.")
 });
 var serializationConfigSchema = z.strictObject({
-  enumRepresentation: z.enum(["enum", "union", "literal", "forward-compatible-enum", "language-default"]).optional(),
-  additionalProperties: z.enum(["allow", "forbid", "ignore", "language-default"]).optional(),
-  inlineTypes: z.boolean().optional(),
-  omitUndefined: z.boolean().optional()
+  enumRepresentation: z.enum(["enum", "union", "literal", "forward-compatible-enum", "language-default"]).optional().describe("How schema enums are represented in generated code."),
+  additionalProperties: z.enum(["allow", "forbid", "ignore", "language-default"]).optional().describe("How undeclared object properties are handled."),
+  inlineTypes: z.boolean().optional().describe("Whether inline schemas remain nested under their parent types."),
+  omitUndefined: z.boolean().optional().describe("Whether undefined properties are omitted during serialization.")
 });
 var languageGenerationConfigSchema = z.strictObject({
-  typescript: typescriptGenerationConfigSchema.optional(),
-  python: pythonGenerationConfigSchema.optional(),
-  java: javaGenerationConfigSchema.optional(),
-  kotlin: kotlinGenerationConfigSchema.optional(),
-  go: goGenerationConfigSchema.optional(),
-  csharp: csharpGenerationConfigSchema.optional(),
-  php: phpGenerationConfigSchema.optional(),
-  ruby: rubyGenerationConfigSchema.optional(),
-  rust: rustGenerationConfigSchema.optional(),
-  cli: cliGenerationConfigSchema.optional(),
-  mcp: mcpGenerationConfigSchema.optional(),
-  swift: swiftGenerationConfigSchema.optional(),
-  terraform: terraformGenerationConfigSchema.optional()
+  typescript: typescriptGenerationConfigSchema.optional().describe("TypeScript-specific generation settings."),
+  python: pythonGenerationConfigSchema.optional().describe("Python-specific generation settings."),
+  java: javaGenerationConfigSchema.optional().describe("Java-specific generation settings."),
+  kotlin: kotlinGenerationConfigSchema.optional().describe("Kotlin-specific generation settings."),
+  go: goGenerationConfigSchema.optional().describe("Go-specific generation settings."),
+  csharp: csharpGenerationConfigSchema.optional().describe("C#-specific generation settings."),
+  php: phpGenerationConfigSchema.optional().describe("PHP-specific generation settings."),
+  ruby: rubyGenerationConfigSchema.optional().describe("Ruby-specific generation settings."),
+  rust: rustGenerationConfigSchema.optional().describe("Rust-specific generation settings."),
+  cli: cliGenerationConfigSchema.optional().describe("CLI-specific generation settings."),
+  mcp: mcpGenerationConfigSchema.optional().describe("MCP-specific generation settings."),
+  swift: swiftGenerationConfigSchema.optional().describe("Swift-specific generation settings."),
+  terraform: terraformGenerationConfigSchema.optional().describe("Terraform-specific generation settings.")
 });
 var generationConfigSchema = z.strictObject({
-  includeWatermark: z.boolean().default(false),
+  includeWatermark: z.boolean().default(false).describe("Whether generated files include a generator watermark."),
   /** Emits an AI service into the generated SDK. Python, Java and TypeScript honour it. */
-  ai: z.boolean().default(false),
-  includeOptionalSnippetParameters: z.boolean().optional(),
-  buildAllModels: z.boolean().default(false),
-  inferServiceNames: z.boolean().default(false),
-  includeDeprecatedOperations: z.boolean().default(true),
-  multipleResponses: z.boolean().default(false),
+  ai: z.boolean().default(false).describe("Whether the SDK includes generated AI service helpers."),
+  includeOptionalSnippetParameters: z.boolean().optional().describe("Whether usage snippets include optional request parameters."),
+  buildAllModels: z.boolean().default(false).describe("Whether models not referenced by operations are also generated."),
+  inferServiceNames: z.boolean().default(false).describe("Whether service names are inferred from API structure."),
+  includeDeprecatedOperations: z.boolean().default(true).describe("Whether deprecated API operations are generated."),
+  multipleResponses: z.boolean().default(false).describe("Whether operations model multiple successful response types."),
   /** Generate the entire SDK project, including package manifests and publishable artifacts. */
-  generateFullProject: z.boolean().default(false),
-  devContainer: z.boolean().default(false),
-  allowMockClient: z.boolean().default(false),
-  ignoreFiles: z.array(nonEmptyStringSchema).optional(),
+  generateFullProject: z.boolean().default(false).describe("Whether generation emits a complete publishable project."),
+  devContainer: z.boolean().default(false).describe("Whether development-container configuration is generated."),
+  allowMockClient: z.boolean().default(false).describe("Whether a mock API client is included in the generated SDK."),
+  ignoreFiles: z.array(nonEmptyStringSchema).optional().describe("Generated paths excluded from the final output."),
   /**
    * Raw .fernignore file contents supplied to external publishers that need Fern ignore semantics.
    * This is separate from generation.ignoreFiles because raw contents preserve comments, ordering,
    * blank lines, and negation rules.
    */
-  fernignoreContents: z.string().optional(),
+  fernignoreContents: z.string().optional().describe("The raw .fernignore contents retained for external publishers."),
   /**
    * Optional Fern definition metadata for publisher paths that need to write definition or
    * mock-server support files. This is not required for core GitHub artifact publishing.
    */
-  fernDefinitionMetadata: fernDefinitionMetadataSchema.optional(),
-  reservedKeywords: z.array(nonEmptyStringSchema).optional(),
-  hooks: hooksConfigSchema.optional(),
-  customCode: customCodeConfigSchema.optional(),
-  workflows: z.array(workflowConfigSchema).optional(),
-  customQueryPaths: z.array(relativePathSchema).optional(),
-  analytics: analyticsConfigSchema.optional(),
-  wireTests: wireTestsSchema.optional(),
-  unitTests: unitTestsSchema.optional(),
-  webSockets: z.boolean().optional(),
-  streams: streamsSchema.optional(),
-  naming: namingConfigSchema.optional(),
-  layout: layoutConfigSchema.optional(),
-  serialization: serializationConfigSchema.optional(),
-  language: languageGenerationConfigSchema.optional()
+  fernDefinitionMetadata: fernDefinitionMetadataSchema.optional().describe("Materialized Fern definition metadata used by external publishers."),
+  reservedKeywords: z.array(nonEmptyStringSchema).optional().describe("Additional identifiers treated as reserved words."),
+  hooks: hooksConfigSchema.optional().describe("Custom SDK request and response hook configuration."),
+  customCode: customCodeConfigSchema.optional().describe("Customer-authored code merge configuration."),
+  workflows: z.array(workflowConfigSchema).optional().describe("Workflow definitions included in generated output."),
+  customQueryPaths: z.array(relativePathSchema).optional().describe("Relative paths to custom query definitions."),
+  analytics: analyticsConfigSchema.optional().describe("Generated client telemetry configuration."),
+  wireTests: wireTestsSchema.optional().describe("Wire-level request and response test generation."),
+  unitTests: unitTestsSchema.optional().describe("SDK unit-test generation."),
+  webSockets: z.boolean().optional().describe("Whether WebSocket clients are generated for supported channels."),
+  streams: streamsSchema.optional().describe("Streaming response generation behavior."),
+  naming: namingConfigSchema.optional().describe("Names and casing used by generated code."),
+  layout: layoutConfigSchema.optional().describe("Generated project and source layout."),
+  serialization: serializationConfigSchema.optional().describe("Generated model serialization behavior."),
+  language: languageGenerationConfigSchema.optional().describe("Settings specific to the selected target language.")
 });
 var publishRegistrySchema = z.enum([
   "npm",
@@ -813,154 +865,160 @@ var credentialResolutionSchema = z.enum([
   "resolved-by-fiddle"
 ]);
 var registryCredentialsSchema = z.strictObject({
-  username: nonEmptyStringSchema.optional(),
-  password: nonEmptyStringSchema.optional(),
-  token: nonEmptyStringSchema.optional(),
-  apiKey: nonEmptyStringSchema.optional()
+  username: nonEmptyStringSchema.optional().describe("The resolved credential username."),
+  password: nonEmptyStringSchema.optional().describe("The resolved credential password."),
+  token: nonEmptyStringSchema.optional().describe("The resolved credential token."),
+  apiKey: nonEmptyStringSchema.optional().describe("The resolved credential API key.")
 });
 var commonPublishShape = {
-  url: nonEmptyStringSchema.optional(),
+  url: nonEmptyStringSchema.optional().describe("A custom package registry URL."),
   /** Reference to registry publishing credentials. */
-  credentialsRef: nonEmptyStringSchema.optional(),
+  credentialsRef: nonEmptyStringSchema.optional().describe("A reference to registry publishing credentials."),
   /** Raw registry credentials. These values can be sensitive and must be handled as secrets. */
-  credentials: registryCredentialsSchema.optional(),
+  credentials: registryCredentialsSchema.optional().describe("Resolved registry publishing credentials."),
   /**
    * Registry-specific package version override. If omitted, the external publisher/orchestrator may
    * fall back to target.sdkVersion.
    */
-  version: nonEmptyStringSchema.optional(),
-  releaseBranch: nonEmptyStringSchema.optional(),
-  tolerateRepublish: z.boolean().optional(),
+  version: nonEmptyStringSchema.optional().describe("A registry-specific package version override."),
+  releaseBranch: nonEmptyStringSchema.optional().describe("The branch used by generated package release workflows."),
+  tolerateRepublish: z.boolean().optional().describe("Whether publishing succeeds when this package version already exists."),
   /** Generate registry publishing workflow files when publishing through GitHub delivery. */
-  shouldGeneratePublishWorkflow: z.boolean().optional()
+  shouldGeneratePublishWorkflow: z.boolean().optional().describe("Whether GitHub delivery includes a registry publishing workflow.")
 };
 var trustedPublishingShape = {
   /** Use registry trusted publishing / OIDC instead of a static token secret. */
-  trustedPublishing: z.boolean().optional()
+  trustedPublishing: z.boolean().optional().describe("Whether registry publication uses trusted publishing or OIDC.")
 };
 var mavenCoordinateSchema = nonEmptyStringSchema.regex(
   /^[A-Za-z0-9_.-]+:[A-Za-z0-9_.-]+$/,
   "Maven coordinate must be in groupId:artifactId form"
 );
 var mavenSignatureEnvironmentSchema = z.strictObject({
-  keyIdEnvironmentVariable: nonEmptyStringSchema.optional(),
-  passwordEnvironmentVariable: nonEmptyStringSchema.optional(),
-  secretKeyEnvironmentVariable: nonEmptyStringSchema.optional()
+  keyIdEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the signing key ID."),
+  passwordEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the signing key password."),
+  secretKeyEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the armored secret key.")
 });
 var mavenSignatureSchema = z.strictObject({
-  keyId: nonEmptyStringSchema,
-  password: nonEmptyStringSchema,
-  secretKey: nonEmptyStringSchema
+  keyId: nonEmptyStringSchema.describe("The resolved signing key identifier."),
+  password: nonEmptyStringSchema.describe("The resolved signing key password."),
+  secretKey: nonEmptyStringSchema.describe("The resolved armored secret key.")
 });
 var publishConfigSchema = z.discriminatedUnion("registry", [
   z.strictObject({
-    registry: z.literal("npm"),
+    registry: z.literal("npm").describe("Publishes the package to an npm-compatible registry."),
     /** Environment variable name containing the npm registry token. */
-    tokenEnvironmentVariable: nonEmptyStringSchema.optional(),
+    tokenEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the npm registry token."),
     /** Write npm package metadata as private when the publisher creates/updates package.json. */
-    isPackagePrivate: z.boolean().optional(),
+    isPackagePrivate: z.boolean().optional().describe("Whether generated npm package metadata marks the package as private."),
     /** Also publish the TypeScript package to JSR from the npm publishing path. */
-    publishToJsr: z.boolean().optional(),
+    publishToJsr: z.boolean().optional().describe("Whether the npm publishing flow also publishes the package to JSR."),
     ...trustedPublishingShape,
     ...commonPublishShape
   }),
   z.strictObject({
-    registry: z.literal("pypi"),
-    usernameEnvironmentVariable: nonEmptyStringSchema.optional(),
-    passwordEnvironmentVariable: nonEmptyStringSchema.optional(),
+    registry: z.literal("pypi").describe("Publishes the package to a PyPI-compatible registry."),
+    usernameEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the PyPI username."),
+    passwordEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the PyPI password or token."),
     ...trustedPublishingShape,
     ...commonPublishShape
   }),
   z.strictObject({
-    registry: z.literal("nuget"),
-    apiKeyEnvironmentVariable: nonEmptyStringSchema.optional(),
+    registry: z.literal("nuget").describe("Publishes the package to a NuGet-compatible registry."),
+    apiKeyEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the NuGet API key."),
     ...trustedPublishingShape,
     ...commonPublishShape
   }),
   z.strictObject({
-    registry: z.literal("rubygems"),
-    apiKeyEnvironmentVariable: nonEmptyStringSchema.optional(),
+    registry: z.literal("rubygems").describe("Publishes the package to a RubyGems-compatible registry."),
+    apiKeyEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the RubyGems API key."),
+    ...commonPublishShape
+  }),
+  z.strictObject({
+    registry: z.literal("crates").describe("Publishes the crate to a Cargo-compatible registry."),
+    tokenEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the Cargo registry token."),
+    ...commonPublishShape
+  }),
+  z.strictObject({
+    registry: z.literal("go").describe("Publishes the SDK as a Go module."),
     ...commonPublishShape
   }),
   z.strictObject({
-    registry: z.literal("crates"),
-    tokenEnvironmentVariable: nonEmptyStringSchema.optional(),
+    registry: z.literal("composer").describe("Publishes the package to a Composer-compatible registry."),
     ...commonPublishShape
   }),
-  z.strictObject({ registry: z.literal("go"), ...commonPublishShape }),
-  z.strictObject({ registry: z.literal("composer"), ...commonPublishShape }),
   z.strictObject({
-    registry: z.literal("maven"),
+    registry: z.literal("maven").describe("Publishes the package to a Maven-compatible repository."),
     /** Maven coordinate in groupId:artifactId form when consumers need the combined value. */
-    coordinate: mavenCoordinateSchema.optional(),
-    usernameEnvironmentVariable: nonEmptyStringSchema.optional(),
-    passwordEnvironmentVariable: nonEmptyStringSchema.optional(),
-    mavenUrlEnvironmentVariable: nonEmptyStringSchema.optional(),
-    signatureEnvironmentVariables: mavenSignatureEnvironmentSchema.optional(),
+    coordinate: mavenCoordinateSchema.optional().describe("The Maven coordinate in groupId:artifactId form."),
+    usernameEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the Maven username."),
+    passwordEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the Maven password."),
+    mavenUrlEnvironmentVariable: nonEmptyStringSchema.optional().describe("The environment variable containing the Maven repository URL."),
+    signatureEnvironmentVariables: mavenSignatureEnvironmentSchema.optional().describe("Environment variables containing Maven signing material."),
     /** Reference to Maven signing credentials. */
-    signingCredentialsRef: nonEmptyStringSchema.optional(),
+    signingCredentialsRef: nonEmptyStringSchema.optional().describe("A reference to Maven signing credentials."),
     /** Raw Maven signing material. These values can be sensitive and must be handled as secrets. */
-    signature: mavenSignatureSchema.optional(),
+    signature: mavenSignatureSchema.optional().describe("Resolved Maven signing material."),
     ...commonPublishShape
   })
 ]);
 var reviewersSchema = z.strictObject({
-  teams: z.array(nonEmptyStringSchema).optional(),
-  users: z.array(nonEmptyStringSchema).optional()
+  teams: z.array(nonEmptyStringSchema).optional().describe("GitHub teams requested as reviewers."),
+  users: z.array(nonEmptyStringSchema).optional().describe("GitHub users requested as reviewers.")
 });
 var replayControlSchema = z.strictObject({
-  enabled: z.boolean()
+  enabled: z.boolean().describe("Whether regeneration reapplies customer-authored repository changes.")
 });
 var githubLicenseSchema = z.strictObject({
   /** SPDX identifier or license key for the repository license (for example, "MIT"). */
-  type: nonEmptyStringSchema.optional(),
+  type: nonEmptyStringSchema.optional().describe("The SPDX identifier or license key for the repository license."),
   /** Path to a custom license file to be committed into the GitHub repository. */
-  customPath: nonEmptyStringSchema.optional()
+  customPath: nonEmptyStringSchema.optional().describe("The path to a custom license file committed to the repository.")
 }).refine((value) => value.type !== void 0 || value.customPath !== void 0, {
   message: "GitHub license must set type or customPath"
 });
 var githubOutputSchema = z.strictObject({
-  repository: nonEmptyStringSchema,
-  host: nonEmptyStringSchema.optional(),
-  branch: nonEmptyStringSchema.optional(),
-  mode: z.enum(["release", "pull-request", "push", "commit", "commit-and-release"]).optional(),
-  reviewers: reviewersSchema.optional(),
+  repository: nonEmptyStringSchema.describe("The GitHub repository that receives generated files."),
+  host: nonEmptyStringSchema.optional().describe("The GitHub host for enterprise installations."),
+  branch: nonEmptyStringSchema.optional().describe("The target branch for generated changes."),
+  mode: z.enum(["release", "pull-request", "push", "commit", "commit-and-release"]).optional().describe("How generated changes are delivered to the repository."),
+  reviewers: reviewersSchema.optional().describe("Reviewers requested for generated pull requests."),
   /** Reference to GitHub credentials. */
-  credentialsRef: nonEmptyStringSchema.optional(),
+  credentialsRef: nonEmptyStringSchema.optional().describe("A reference to GitHub credentials."),
   /** Raw GitHub credentials. These values can be sensitive and must be handled as secrets. */
-  credentials: registryCredentialsSchema.optional(),
-  privateRepository: z.boolean().optional(),
+  credentials: registryCredentialsSchema.optional().describe("Resolved GitHub credentials."),
+  privateRepository: z.boolean().optional().describe("Whether the destination repository is private."),
   /** GitHub license block scoped to repository delivery. */
-  license: githubLicenseSchema.optional(),
+  license: githubLicenseSchema.optional().describe("License configuration for the destination repository."),
   /** GitHub replay control. If omitted, the external publisher applies its default behavior. */
-  replay: replayControlSchema.optional(),
+  replay: replayControlSchema.optional().describe("Replay behavior for the external GitHub publisher."),
   /** Run GitHub publishing verification. Defaults to false to match current Fiddle job behavior. */
-  verify: z.boolean().default(false),
+  verify: z.boolean().default(false).describe("Whether the GitHub publisher verifies the generated result."),
   /** Skip creating/updating a GitHub PR when no files changed. Defaults to false. */
-  skipIfNoDiff: z.boolean().default(false),
+  skipIfNoDiff: z.boolean().default(false).describe("Whether GitHub publication is skipped when no generated files changed."),
   /** Automatically merge the GitHub publishing PR. Defaults to false. */
-  autoMerge: z.boolean().default(false)
+  autoMerge: z.boolean().default(false).describe("Whether the GitHub publisher automatically merges its pull request.")
 });
 var credentialResolutionShape = {
   /** Where output credential references are resolved. */
-  credentialResolution: credentialResolutionSchema.default("refs-only")
+  credentialResolution: credentialResolutionSchema.default("refs-only").describe("Where output credential references are resolved.")
 };
 var filesOutputSchema = z.strictObject({
-  delivery: z.literal("files"),
-  path: nonEmptyStringSchema.optional(),
-  publish: publishConfigSchema.optional(),
+  delivery: z.literal("files").describe("Writes the generated SDK to a directory."),
+  path: nonEmptyStringSchema.optional().describe("The destination directory for generated files."),
+  publish: publishConfigSchema.optional().describe("Optional package registry publication."),
   ...credentialResolutionShape
 });
 var zipOutputSchema = z.strictObject({
-  delivery: z.literal("zip"),
-  fileName: nonEmptyStringSchema.optional(),
-  publish: publishConfigSchema.optional(),
+  delivery: z.literal("zip").describe("Packages the generated SDK as a ZIP archive."),
+  fileName: nonEmptyStringSchema.optional().describe("The generated ZIP archive file name."),
+  publish: publishConfigSchema.optional().describe("Optional package registry publication."),
   ...credentialResolutionShape
 });
 var githubDeliverySchema = z.strictObject({
-  delivery: z.literal("github"),
-  github: githubOutputSchema,
-  publish: publishConfigSchema.optional(),
+  delivery: z.literal("github").describe("Delivers the generated SDK to GitHub."),
+  github: githubOutputSchema.describe("GitHub repository delivery settings."),
+  publish: publishConfigSchema.optional().describe("Optional package registry publication."),
   ...credentialResolutionShape
 });
 var outputConfigSchema = z.discriminatedUnion(
@@ -971,29 +1029,33 @@ var outputConfigSchema = z.discriminatedUnion(
   }
 );
 var replayConfigSchema = z.strictObject({
-  enabled: z.boolean()
+  enabled: z.boolean().describe("Whether regeneration reapplies customer-authored repository changes.")
 });
 var apiImportSettingsSchema = z.strictObject({
-  respectNullableSchemas: z.boolean().optional(),
-  titleAsSchemaName: z.boolean().optional(),
-  coerceEnumsToLiterals: z.boolean().optional(),
-  idiomaticRequestNames: z.boolean().optional(),
-  wrapReferencesToNullableInOptional: z.boolean().optional(),
-  coerceOptionalSchemasToNullable: z.boolean().optional(),
-  pathParameterOrder: z.enum(["url-order", "spec-order"]).optional(),
-  onlyIncludeReferencedSchemas: z.boolean().optional(),
-  objectQueryParameters: z.boolean().optional(),
-  typeDatesAsStrings: z.boolean().optional(),
-  groupMultiApiEnvironments: z.boolean().optional(),
-  ignoreTags: z.boolean().optional(),
-  disambiguateRequestNames: z.boolean().optional(),
-  respectReadonlySchemas: z.boolean().optional(),
-  discriminatedUnionV2: z.boolean().optional(),
-  undiscriminatedUnionsWithLiterals: z.boolean().optional(),
-  inlineAllOfSchemas: z.boolean().optional(),
-  resolveSchemaCollisions: z.boolean().optional(),
-  asyncApiMessageNaming: z.enum(["v1", "v2"]).optional(),
-  defaultIntegerFormat: z.enum(["int32", "int64", "uint32", "uint64"]).optional()
+  respectNullableSchemas: z.boolean().optional().describe("Whether nullable schemas remain nullable in generated types."),
+  titleAsSchemaName: z.boolean().optional().describe("Whether a schema title can determine the generated type name."),
+  coerceEnumsToLiterals: z.boolean().optional().describe("Whether single-value enums are imported as literal values."),
+  idiomaticRequestNames: z.boolean().optional().describe("Whether request types use concise, idiomatic generated names."),
+  wrapReferencesToNullableInOptional: z.boolean().optional().describe("Whether nullable schema references are also treated as optional."),
+  coerceOptionalSchemasToNullable: z.boolean().optional().describe("Whether optional properties are represented as nullable required properties."),
+  pathParameterOrder: z.enum(["url-order", "spec-order"]).optional().describe("Whether path parameters follow their URL order or specification order."),
+  onlyIncludeReferencedSchemas: z.boolean().optional().describe("Whether unreferenced schemas are omitted from the generated SDK."),
+  objectQueryParameters: z.boolean().optional().describe("Whether object-valued query parameters are preserved as objects."),
+  typeDatesAsStrings: z.boolean().optional().describe("Whether date and date-time schemas are generated as strings."),
+  groupMultiApiEnvironments: z.boolean().optional().describe(
+    "Whether environments from multiple API sources are merged into shared named groups."
+  ),
+  ignoreTags: z.boolean().optional().describe("Whether API tags are ignored when organizing generated resources."),
+  disambiguateRequestNames: z.boolean().optional().describe("Whether colliding request type names are automatically disambiguated."),
+  respectReadonlySchemas: z.boolean().optional().describe(
+    "Whether read-only properties are modeled separately for request and response types."
+  ),
+  discriminatedUnionV2: z.boolean().optional().describe("Whether oneOf and anyOf schemas use the newer discriminator inference rules."),
+  undiscriminatedUnionsWithLiterals: z.boolean().optional().describe("Whether literal-bearing unions remain undiscriminated during import."),
+  inlineAllOfSchemas: z.boolean().optional().describe("Whether schemas composed with allOf are inlined when possible."),
+  resolveSchemaCollisions: z.boolean().optional().describe("Whether colliding imported schema names are resolved automatically."),
+  asyncApiMessageNaming: z.enum(["v1", "v2"]).optional().describe("The naming strategy used for messages imported from AsyncAPI."),
+  defaultIntegerFormat: z.enum(["int32", "int64", "uint32", "uint64"]).optional().describe("The integer format used when a schema does not declare one.")
 });
 var sourceSpecTypeSchema = z.enum([
   "openapi",
@@ -1005,18 +1067,20 @@ var sourceSpecTypeSchema = z.enum([
 
 // src/sdk-config-ir/v1/source.ts
 var sourceSpecConfigSchema = z.strictObject({
-  id: nonEmptyStringSchema.optional(),
-  name: nonEmptyStringSchema.optional(),
-  namespace: nonEmptyStringSchema.optional(),
-  specUrl: nonEmptyStringSchema,
-  specType: sourceSpecTypeSchema,
-  apiImportSettings: apiImportSettingsSchema.optional(),
-  overlays: z.array(nonEmptyStringSchema).optional(),
-  overrides: z.array(nonEmptyStringSchema).optional()
+  id: nonEmptyStringSchema.optional().describe("A unique identifier for this API source."),
+  name: nonEmptyStringSchema.optional().describe("A human-readable name for this API source."),
+  namespace: nonEmptyStringSchema.optional().describe("A namespace used to isolate this source in a multi-source SDK."),
+  specUrl: nonEmptyStringSchema.describe(
+    "The materialized URL from which the generator retrieves the API source."
+  ),
+  specType: sourceSpecTypeSchema.describe("The API description format of this source."),
+  apiImportSettings: apiImportSettingsSchema.optional().describe("Import behavior that overrides the source-level defaults for this spec."),
+  overlays: z.array(nonEmptyStringSchema).optional().describe("Materialized overlays applied to this source in order."),
+  overrides: z.array(nonEmptyStringSchema).optional().describe("Materialized source overrides applied in order.")
 });
 var sourceConfigSchema = z.strictObject({
-  specs: z.array(sourceSpecConfigSchema).min(1, "source.specs must contain at least one source spec"),
-  apiImportSettings: apiImportSettingsSchema.optional()
+  specs: z.array(sourceSpecConfigSchema).min(1, "source.specs must contain at least one source spec").describe("Materialized API sources in authoritative processing order."),
+  apiImportSettings: apiImportSettingsSchema.optional().describe("Default import behavior shared by every source spec.")
 }).superRefine(({ specs }, context) => {
   const seenIds = /* @__PURE__ */ new Set();
   specs.forEach(({ id }, index) => {
@@ -1048,25 +1112,27 @@ var targetLanguageSchema = z.enum([
   "terraform"
 ]);
 var targetConfigSchema = z.strictObject({
-  language: targetLanguageSchema,
-  generatorVersion: exactSemverSchema.optional(),
-  sourceOrigin: z.enum(["postman", "fern"]),
-  sdkName: nonEmptyStringSchema,
+  language: targetLanguageSchema.describe(
+    "The language or platform generated by this single-target request."
+  ),
+  generatorVersion: exactSemverSchema.optional().describe("The exact generator version requested for this target."),
+  sourceOrigin: z.enum(["postman", "fern"]).describe("The configuration system from which this IR was normalized."),
+  sdkName: nonEmptyStringSchema.describe("The name used for the generated SDK."),
   /**
    * Stable Fern/Fiddle API identity for external publishing.
    * Producers must set this explicitly for GitHub or registry publishing; it is not inferred from
    * target.sdkName because SDK display names and Fern API names are not equivalent.
    */
-  apiName: nonEmptyStringSchema.optional(),
-  organization: nonEmptyStringSchema.optional(),
+  apiName: nonEmptyStringSchema.optional().describe("The stable API identity used for external publishing."),
+  organization: nonEmptyStringSchema.optional().describe("Source organization metadata retained for generation."),
   /**
    * Stable Fern/Fiddle organization identity for external publishing.
    * Producers must set this explicitly for GitHub or registry publishing; it is not inferred from
    * target.organization because source organization metadata is optional and may not match Fern.
    */
-  organizationName: nonEmptyStringSchema.optional(),
-  sdkVersion: nonEmptyStringSchema.default("1.0.0"),
-  apiVersion: nonEmptyStringSchema.optional()
+  organizationName: nonEmptyStringSchema.optional().describe("The stable organization identity used for external publishing."),
+  sdkVersion: nonEmptyStringSchema.default("1.0.0").describe("The version of the generated SDK."),
+  apiVersion: nonEmptyStringSchema.optional().describe("The version of the API represented by the SDK.")
 });
 
 // src/sdk-config-ir/v1/sdk-config-ir-v1.ts
@@ -1128,17 +1194,21 @@ function validatePublishingIdentity(packageConfig, registry, context) {
   }
 }
 var sdkConfigIrV1Schema = z.strictObject({
-  schemaVersion: z.literal(SDK_CONFIG_IR_V1_SCHEMA_VERSION),
-  source: sourceConfigSchema,
-  target: targetConfigSchema,
-  api: apiConfigSchema,
-  client: clientConfigSchema,
-  package: packageConfigSchema,
-  output: outputConfigSchema,
-  replay: replayConfigSchema.optional(),
-  docs: docsConfigSchema,
-  generation: generationConfigSchema,
-  compatibility: compatibilityConfigSchema.optional()
+  schemaVersion: z.literal(SDK_CONFIG_IR_V1_SCHEMA_VERSION).describe("The version of the normalized SDK Config IR schema."),
+  source: sourceConfigSchema.describe("Materialized API descriptions consumed by generation."),
+  target: targetConfigSchema.describe(
+    "Identity and provenance for this single generation target."
+  ),
+  api: apiConfigSchema.describe("API behavior exposed by the generated SDK."),
+  client: clientConfigSchema.describe("Behavior of the generated API client."),
+  package: packageConfigSchema.describe("Package identity and metadata for the generated SDK."),
+  output: outputConfigSchema.describe("Artifact delivery and optional package publication."),
+  replay: replayConfigSchema.optional().describe("Generation replay behavior."),
+  docs: docsConfigSchema.describe("Generated documentation settings."),
+  generation: generationConfigSchema.describe(
+    "Shared and language-specific generation behavior."
+  ),
+  compatibility: compatibilityConfigSchema.optional().describe("Temporary provenance and diagnostics retained during legacy migration.")
 }).superRefine(({ compatibility, generation, output, package: packageConfig, target }, context) => {
   const configuredLanguages = Object.keys(generation.language ?? {});
   const requiresExternalPublishIdentity = output.delivery === "github" || output.publish !== void 0;