Add deprecated help into description fields

mintlify-codegen/layouts/partials/object-property.hbs

@@ -1,4 +1,8 @@
 <ResponseField name="{{name}}" type="{{type}}"{{#if deprecated}} deprecated{{/if}}>
+{{#if deprecationMessage}}
+  **Deprecated**. {{deprecationMessage}}
+
+{{/if}}
   {{description}}
 {{#if enumValues}}
 

mintlify-codegen/lib/layout/object-page.ts

@@ -12,6 +12,7 @@ interface BlueprintProperty {
   format: string
   jsonType: string
   isDeprecated: boolean
+  deprecationMessage: string
   isUndocumented: boolean
   properties?: BlueprintProperty[]
   itemFormat?: string
@@ -24,6 +25,7 @@ export interface PropertyFieldContext {
   name: string
   type: string
   deprecated: boolean
+  deprecationMessage: string
   description: string
   children: PropertyFieldContext[]
   // Renders an `Enum values` accordion after the description. Set on the Event
@@ -98,6 +100,7 @@ function buildField(
     name: prop.name,
     type: formatType(prop),
     deprecated: prop.isDeprecated,
+    deprecationMessage: prop.deprecationMessage,
     description: prop.description || `The ${prop.name.replace(/_/g, ' ')}.`,
     children: [],
   }
@@ -267,6 +270,7 @@ export function setActionAttemptPageLayoutContext(
     name,
     type,
     deprecated: false,
+    deprecationMessage: '',
     description,
     children: [],
     ...(enumValues == null ? {} : { enumValues }),

mintlify-codegen/lib/transform-spec.ts

@@ -252,9 +252,36 @@ function rewriteLinks(text: string): string {
   return result
 }
 
+/**
+ * Fold a node's `x-deprecated` guidance text (e.g. "Use `space_ids`.") into
+ * its description as a "Deprecated. …" prefix. OpenAPI has no standard field
+ * for deprecation guidance, so without this the text is lost.
+ *
+ * Also set the standard `deprecated: true` flag, which Mintlify renders
+ * natively (a badge on the page and a strikethrough in the navigation).
+ * Most annotated nodes already carry it, but the deprecated operations
+ * (`/locks/get`, `/thermostats/get`, `/devices/delete`, and the two
+ * credential-automation endpoints) only carry the `x-deprecated` text, so
+ * without this they would show the notice but no deprecation styling.
+ */
+function foldDeprecationText(obj: any): void {
+  const message = obj['x-deprecated']
+  if (typeof message === 'string' && message.trim() !== '') {
+    const notice = `Deprecated. ${message.trim()}`
+    obj.description =
+      typeof obj.description === 'string' && obj.description !== ''
+        ? `${notice}\n\n${obj.description}`
+        : notice
+    obj.deprecated = true
+  }
+  delete obj['x-deprecated']
+}
+
 /**
  * Recursively rewrite all `description` string fields in an object tree.
  * This ensures links are fixed in deeply nested schemas, not just top-level.
+ * Also folds `x-deprecated` guidance text into each node's description first,
+ * so the merged text gets the same link rewriting.
  */
 function rewriteAllDescriptions(obj: any): void {
   if (obj == null || typeof obj !== 'object') return
@@ -264,6 +291,7 @@ function rewriteAllDescriptions(obj: any): void {
     }
     return
   }
+  foldDeprecationText(obj)
   for (const [key, value] of Object.entries(obj)) {
     if (key === 'description' && typeof value === 'string') {
       obj[key] = rewriteLinks(value)
@@ -533,14 +561,16 @@ export function transformSpec(
       }
     }
 
-    // 6. Clean up vendor extensions Mintlify doesn't need
+    // 6. Clean up vendor extensions Mintlify doesn't need.
+    // `x-deprecated` is intentionally not deleted here — the
+    // rewriteAllDescriptions pass below folds its guidance text into
+    // op.description before removing the marker.
     delete op['x-fern-sdk-group-name']
     delete op['x-fern-sdk-method-name']
     delete op['x-fern-sdk-return-value']
     delete op['x-undocumented']
     delete op['x-draft']
     delete op['x-batch-keys']
-    delete op['x-deprecated']
   }
 
   // Transform component schemas

mintlify-docs/api/access_grants/object.mdx

@@ -104,6 +104,8 @@ Represents an Access Grant. Access Grants enable you to grant a user identity ac
 </ResponseField>
 
 <ResponseField name="location_ids" type="Array" deprecated>
+  **Deprecated**. Use `space_ids`.
+
   The location ids.
 </ResponseField>
 

mintlify-docs/api/acs/access_groups/object.mdx

@@ -40,10 +40,14 @@ To learn whether your access control system supports access groups, see the corr
 ## Properties
 
 <ResponseField name="access_group_type" type="Enum (String)" deprecated>
+  **Deprecated**. Use `external_type`.
+
   The access group type.
 </ResponseField>
 
 <ResponseField name="access_group_type_display_name" type="String" deprecated>
+  **Deprecated**. Use `external_type_display_name`.
+
   The access group type display name.
 </ResponseField>
 

mintlify-docs/api/acs/systems/object.mdx

@@ -62,6 +62,8 @@ For details about the resources associated with an access control system, see th
 </ResponseField>
 
 <ResponseField name="connected_account_ids" type="Array" deprecated>
+  **Deprecated**. Use `connected_account_id`.
+
   IDs of the [connected accounts](/core-concepts/connected-accounts) associated with the [access control system](/low-level-apis/access-systems).
 </ResponseField>
 
@@ -111,10 +113,14 @@ For details about the resources associated with an access control system, see th
 </ResponseField>
 
 <ResponseField name="system_type" type="Enum (String)" deprecated>
+  **Deprecated**. Use `external_type`.
+
   The system type.
 </ResponseField>
 
 <ResponseField name="system_type_display_name" type="String" deprecated>
+  **Deprecated**. Use `external_type_display_name`.
+
   The system type display name.
 </ResponseField>
 

mintlify-docs/api/acs/users/object.mdx

@@ -95,6 +95,8 @@ For details about how to configure users in your access system, see the correspo
 </ResponseField>
 
 <ResponseField name="email" type="String" deprecated>
+  **Deprecated**. use email_address.
+
   The email.
 </ResponseField>
 

mintlify-docs/api/client_sessions/object.mdx

@@ -87,6 +87,8 @@ See also [Get Started with React](/ui-components/overview/getting-started-with-s
 </ResponseField>
 
 <ResponseField name="user_identity_ids" type="Array" deprecated>
+  **Deprecated**. Use `user_identity_id` instead.
+
   IDs of the [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with the client session.
 </ResponseField>
 

mintlify-docs/api/connected_accounts/object.mdx

@@ -106,6 +106,8 @@ Represents a [connected account](/core-concepts/connected-accounts). A connected
 </ResponseField>
 
 <ResponseField name="user_identifier" type="Object" deprecated>
+  **Deprecated**. Use `display_name` instead.
+
   User identifier associated with the connected account.
   <Expandable title="properties">
     <ResponseField name="api_url" type="String">