diff --git a/packages/docs-site/src/availability.test.ts b/packages/docs-site/src/availability.test.ts
new file mode 100644
index 000000000..00c743810
--- /dev/null
+++ b/packages/docs-site/src/availability.test.ts
@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { availabilityLabel } from './availability.ts';
+
+test('labels every Fern endpoint availability status', () => {
+  assert.equal(availabilityLabel('alpha'), 'Alpha');
+  assert.equal(availabilityLabel('beta'), 'Beta');
+  assert.equal(availabilityLabel('preview'), 'Preview');
+  assert.equal(availabilityLabel('generally-available'), 'Generally Available');
+  assert.equal(availabilityLabel('deprecated'), 'Deprecated');
+  assert.equal(availabilityLabel('legacy'), 'Legacy');
+});
+
+test('keeps unknown statuses readable', () => {
+  assert.equal(availabilityLabel('custom-channel'), 'custom channel');
+});
diff --git a/packages/docs-site/src/availability.ts b/packages/docs-site/src/availability.ts
new file mode 100644
index 000000000..d76963795
--- /dev/null
+++ b/packages/docs-site/src/availability.ts
@@ -0,0 +1,14 @@
+/** Display labels for Fern endpoint availability statuses. */
+const AVAILABILITY_LABELS: Record<string, string> = {
+  alpha: 'Alpha',
+  beta: 'Beta',
+  preview: 'Preview',
+  'generally-available': 'Generally Available',
+  deprecated: 'Deprecated',
+  legacy: 'Legacy',
+};
+
+/** Human label for an availability status. Unknown statuses keep their words. */
+export function availabilityLabel(status: string): string {
+  return AVAILABILITY_LABELS[status] ?? status.replaceAll('-', ' ');
+}
diff --git a/packages/docs-site/src/components/Operation.astro b/packages/docs-site/src/components/Operation.astro
index 8694c3625..f6109f557 100644
--- a/packages/docs-site/src/components/Operation.astro
+++ b/packages/docs-site/src/components/Operation.astro
@@ -3,6 +3,7 @@ import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
 import { Aside } from '@astrojs/starlight/components';
 import type { FernPageSchema } from 'astro-fern';
 import { DEFER_THRESHOLD, nodeCount, operationView, responseSummary, topLevelNodes } from '../operation-sections.ts';
+import { availabilityLabel } from '../availability.ts';
 import CodeSample from './CodeSample.astro';
 import SchemaSectionIsland from './SchemaSectionIsland.astro';
 import SchemaTree from './SchemaTree.astro';
@@ -36,7 +37,7 @@ const availabilityMessage = !op.deprecated ? op.availability?.message : undefine
     }
     {
       availabilityMessage ? (
-        <Aside type="note" title={op.availability?.status.replaceAll('-', ' ')}>
+        <Aside type="note" title={op.availability ? availabilityLabel(op.availability.status) : 'Availability'}>
           <p>{availabilityMessage}</p>
         </Aside>
       ) : null
diff --git a/packages/docs-site/src/components/PageTitle.astro b/packages/docs-site/src/components/PageTitle.astro
index 9951f94d9..70775aa62 100644
--- a/packages/docs-site/src/components/PageTitle.astro
+++ b/packages/docs-site/src/components/PageTitle.astro
@@ -1,6 +1,7 @@
 ---
 import Default from '@astrojs/starlight/components/PageTitle.astro';
 import { getApiPage, getApiRouter } from '../api-server.ts';
+import { availabilityLabel } from '../availability.ts';
 
 const router = await getApiRouter();
 const resolved = await getApiPage(Astro.url, Astro.request, Astro.locals);
@@ -26,18 +27,8 @@ const markdownHref =
         page.operation.placement?.projectionId,
       )
     : undefined;
-const availabilityLabels: Record<string, string> = {
-  alpha: 'Alpha',
-  beta: 'Beta',
-  preview: 'Preview',
-  'generally-available': 'Generally Available',
-  deprecated: 'Deprecated',
-  legacy: 'Legacy',
-};
 const availabilityStatus = op?.deprecated ? 'deprecated' : op?.availability?.status;
-const availability = availabilityStatus
-  ? (availabilityLabels[availabilityStatus] ?? availabilityStatus.replaceAll('-', ' '))
-  : undefined;
+const availability = availabilityStatus ? availabilityLabel(availabilityStatus) : undefined;
 ---
 
 {
@@ -224,6 +215,12 @@ const availability = availabilityStatus
     --forge-availability-background: var(--cf-danger-muted);
   }
 
+  .forge-availability[data-status='legacy'] {
+    --forge-availability-color: var(--cf-muted-foreground);
+    --forge-availability-background: var(--cf-surface-sunken);
+    border-style: dashed;
+  }
+
   .forge-endpoint {
     min-width: 0;
     gap: 0.625rem;
diff --git a/packages/fern-forge/README.md b/packages/fern-forge/README.md
index e3e2f41c2..2d4c7aab9 100644
--- a/packages/fern-forge/README.md
+++ b/packages/fern-forge/README.md
@@ -238,7 +238,7 @@ Primary operation metadata accepts these fields:
 | ------------------------------ | ----------------------------------------------- | --------------------- | --------------------------------------------------------- |
 | `x-fern-sdk-group-name`        | Nonempty string with segments separated by dots | `sdkGroupName`        | Selects products and supplies the SDK accessor path       |
 | `x-fern-sdk-method-name`       | Nonempty string                                 | `sdkMethodName`       | Supplies the SDK method for snippets                      |
-| `x-fern-availability`          | Availability value below                        | `availability`        | Supplies lifecycle metadata                               |
+| `x-fern-availability`          | Status string, or `{ status, message }`         | `availability`, `availabilityMessage` | Supplies lifecycle metadata. `message` is kept when the object form is used. |
 | `x-fern-ignore`                | Boolean, default `false`                        | `ignore`              | Removes the operation from generated content when true    |
 | `x-forge-hidden`               | Boolean, default `false`                        | `hidden`              | Stores approval state and lowers route-collision priority |
 | `x-forge-internal`             | Boolean                                         | `internal`            | Stores internal visibility metadata                       |
@@ -256,7 +256,10 @@ projections always require both names.
 
 ### Availability
 
-`x-fern-availability` accepts:
+`x-fern-availability` accepts Fern's endpoint vocabulary as a status string or as
+`{ status, message }`. The message is the human note Fern shows beside the
+status, such as a replacement endpoint. `availability` stores the status.
+`availabilityMessage` stores the note when the object form includes one.
 
 ```text
 alpha
@@ -267,6 +270,12 @@ deprecated
 legacy
 ```
 
+```yaml
+x-fern-availability:
+  status: legacy
+  message: Use the v2 widgets endpoint.
+```
+
 ## Argument metadata reference
 
 `x-forge-globals` contains arguments. `x-forge-args` contains arguments or
diff --git a/packages/fern-forge/extension.ts b/packages/fern-forge/extension.ts
index 8a85fa9c8..4672c7f0b 100644
--- a/packages/fern-forge/extension.ts
+++ b/packages/fern-forge/extension.ts
@@ -17,6 +17,15 @@ function aliasName(alias: ForgeOperationDataSchema): string {
   return `alias:${encodeURIComponent(alias.sdkGroupName)}/${encodeURIComponent(alias.sdkMethodName)}`;
 }
 
+function variantAvailability(
+  alias: ForgeOperationDataSchema,
+): ForgeOperationDataSchema['availability'] | { status: ForgeOperationDataSchema['availability']; message: string } {
+  if (alias.availability !== undefined && alias.availabilityMessage !== undefined) {
+    return { status: alias.availability, message: alias.availabilityMessage };
+  }
+  return alias.availability;
+}
+
 const extension = defineFernExtension<ForgeOperationDataSchema, ForgeExtensionState>({
   name: 'forge',
   schema: forgeOperationDataSchema,
@@ -26,14 +35,17 @@ const extension = defineFernExtension<ForgeOperationDataSchema, ForgeExtensionSt
     if (!parsed) return undefined;
     return {
       ...(parsed.primary ? { data: parsed.primary, presentation: presentation(parsed.primary) } : {}),
-      variants: parsed.aliases.map((alias) => ({
-        name: aliasName(alias),
-        sdkGroupName: alias.sdkGroupName,
-        sdkMethodName: alias.sdkMethodName,
-        ...(alias.availability !== undefined ? { availability: alias.availability } : {}),
-        data: alias,
-        presentation: presentation(alias),
-      })),
+      variants: parsed.aliases.map((alias) => {
+        const availability = variantAvailability(alias);
+        return {
+          name: aliasName(alias),
+          sdkGroupName: alias.sdkGroupName,
+          sdkMethodName: alias.sdkMethodName,
+          ...(availability !== undefined ? { availability } : {}),
+          data: alias,
+          presentation: presentation(alias),
+        };
+      }),
     };
   },
 });
diff --git a/packages/fern-forge/index.test.ts b/packages/fern-forge/index.test.ts
index 3cb4b0528..7be1b5235 100644
--- a/packages/fern-forge/index.test.ts
+++ b/packages/fern-forge/index.test.ts
@@ -68,9 +68,46 @@ test('validates and exposes every known operation-level Forge field', () => {
   assert.equal(forge?.hidden, true);
   assert.equal(forge?.internal, true);
   assert.equal(forge?.sdkGroupName, 'widgets.items');
+  assert.equal(forge?.availability, 'deprecated');
+  assert.equal(forge?.availabilityMessage, undefined);
   assert.equal(forge?.params?.widget_id && typeof forge.params.widget_id, 'object');
 });
 
+test('keeps Fern availability messages on the operation and on alias projections', () => {
+  const source = operation({
+    'x-fern-sdk-group-name': undefined,
+    'x-fern-sdk-method-name': undefined,
+    'x-forge-aliases': [
+      {
+        'x-fern-sdk-group-name': 'widgets.items',
+        'x-fern-sdk-method-name': 'update',
+        'x-fern-availability': { status: 'legacy', message: '  Use the v2 widgets endpoint.  ' },
+      },
+    ],
+  });
+  const model = buildDocsModel({ source, products: [product], extensions: [forgeExtension()] });
+  const result = model.products[0]?.sections[0]?.operations[0];
+  assert.ok(result);
+  assert.deepEqual(result.availability, { status: 'legacy', message: 'Use the v2 widgets endpoint.' });
+  const forge = getOperationExtensionData(result, 'forge');
+  assert.equal(forge?.availability, 'legacy');
+  assert.equal(forge?.availabilityMessage, 'Use the v2 widgets endpoint.');
+});
+
+test('accepts an availability object on a primary operation', () => {
+  const model = buildDocsModel({
+    source: operation({
+      'x-fern-availability': { status: 'preview', message: 'Subject to change.' },
+    }),
+    products: [product],
+    extensions: [forgeExtension()],
+  });
+  const result = model.products[0]?.sections[0]?.operations[0];
+  assert.ok(result);
+  assert.deepEqual(result.availability, { status: 'preview', message: 'Subject to change.' });
+  assert.equal(getOperationExtensionData(result, 'forge')?.availabilityMessage, 'Subject to change.');
+});
+
 test('aliases participate in product discovery and retain projection-specific data', () => {
   const source = operation({
     'x-fern-sdk-group-name': undefined,
@@ -350,6 +387,24 @@ test('rejects malformed, misplaced, and unknown Forge metadata', () => {
       }),
     /x-fern-sdk-group-name[\s\S]*expected string/,
   );
+  assert.throws(
+    () =>
+      buildDocsModel({
+        source: operation({ 'x-fern-availability': { status: 'stable', message: 'Ready.' } }),
+        products: [product],
+        extensions: [forgeExtension()],
+      }),
+    /x-fern-availability/,
+  );
+  assert.throws(
+    () =>
+      buildDocsModel({
+        source: operation({ 'x-fern-availability': { status: 'legacy', message: '   ' } }),
+        products: [product],
+        extensions: [forgeExtension()],
+      }),
+    /x-fern-availability/,
+  );
 });
 
 test('validates known root-level Forge metadata', () => {
diff --git a/packages/fern-forge/parser.ts b/packages/fern-forge/parser.ts
index 9941f9c15..59c2cb81a 100644
--- a/packages/fern-forge/parser.ts
+++ b/packages/fern-forge/parser.ts
@@ -22,11 +22,22 @@ export type ForgeExtensionState = {
 const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
 const OPERATION_PROJECTION_KEYS = operationProjectionFieldsSchema.keyof().options;
 
+function availabilityFields(
+  value: ReturnType<typeof projectionSchema>['_output']['x-fern-availability'],
+): Pick<ForgeOperationDataSchema, 'availability' | 'availabilityMessage'> {
+  if (value === undefined) return {};
+  if (typeof value === 'string') return { availability: value };
+  return {
+    availability: value.status,
+    ...(value.message !== undefined ? { availabilityMessage: value.message } : {}),
+  };
+}
+
 function toOperationData(value: ReturnType<typeof projectionSchema>['_output']): ForgeOperationDataSchema {
   return forgeOperationDataSchema.parse({
     sdkGroupName: value['x-fern-sdk-group-name'],
     sdkMethodName: value['x-fern-sdk-method-name'],
-    ...(value['x-fern-availability'] !== undefined ? { availability: value['x-fern-availability'] } : {}),
+    ...availabilityFields(value['x-fern-availability']),
     ignore: value['x-fern-ignore'] ?? false,
     hidden: value['x-forge-hidden'] ?? false,
     ...(value['x-forge-internal'] !== undefined ? { internal: value['x-forge-internal'] } : {}),
diff --git a/packages/fern-forge/schemas/operation.ts b/packages/fern-forge/schemas/operation.ts
index 8c864feeb..e160696e3 100644
--- a/packages/fern-forge/schemas/operation.ts
+++ b/packages/fern-forge/schemas/operation.ts
@@ -2,7 +2,7 @@ import { z } from 'astro/zod';
 import { argumentSchema, methodArgumentSchema, paramOverrideSchema } from './arguments.ts';
 import { nonEmptyStringSchema } from './shared.ts';
 
-/** Availability values accepted by the Forge OpenAPI contract. */
+/** Availability statuses accepted by the Forge OpenAPI contract. */
 export const forgeAvailabilitySchema = z.enum([
   'alpha',
   'beta',
@@ -12,15 +12,28 @@ export const forgeAvailabilitySchema = z.enum([
   'legacy',
 ]);
 
-/** A validated Forge availability value. */
+/** A validated Forge availability status. */
 export type ForgeAvailabilitySchema = z.infer<typeof forgeAvailabilitySchema>;
 
+/**
+ * Fern's endpoint availability: a status string, or `{ status, message }`.
+ * @see https://buildwithfern.com/learn/api-definition/openapi/extensions/availability
+ */
+const forgeAvailabilityInputSchema = z.union([
+  forgeAvailabilitySchema,
+  z.strictObject({
+    status: forgeAvailabilitySchema,
+    message: nonEmptyStringSchema.optional(),
+  }),
+]);
+
 /** Normalized, serializable Forge metadata stored on an operation projection. */
 export const forgeOperationDataSchema = z
   .object({
     sdkGroupName: nonEmptyStringSchema,
     sdkMethodName: nonEmptyStringSchema,
     availability: forgeAvailabilitySchema.optional(),
+    availabilityMessage: nonEmptyStringSchema.optional(),
     ignore: z.boolean(),
     hidden: z.boolean(),
     internal: z.boolean().optional(),
@@ -51,7 +64,7 @@ const sdkGroupSchema = nonEmptyStringSchema
 export const operationProjectionFieldsSchema = z.object({
   'x-fern-sdk-group-name': sdkGroupSchema,
   'x-fern-sdk-method-name': nonEmptyStringSchema,
-  'x-fern-availability': forgeAvailabilitySchema.optional(),
+  'x-fern-availability': forgeAvailabilityInputSchema.optional(),
   'x-fern-ignore': z.boolean().optional(),
   'x-forge-hidden': z.boolean().optional(),
   'x-forge-internal': z.boolean().optional(),
diff --git a/packages/forge/init-from-openapi.ts b/packages/forge/init-from-openapi.ts
index 9f242c25e..66b16c0bb 100644
--- a/packages/forge/init-from-openapi.ts
+++ b/packages/forge/init-from-openapi.ts
@@ -2,6 +2,7 @@ import { Forge } from './forge.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import { populateOperationMap } from './openapi-resolver.js';
 import type { Schema } from './schema/schema.js';
+import { parseFernAvailability, type FernAvailabilityStatus } from './shared/fern-availability.js';
 import { ensureUniqueSdkMethodNames } from './shared/sdk-method-names.js';
 import { resolveCommandArgDescriptions, resolveCommandDescriptions } from './shared/schema-utils.js';
 
@@ -11,7 +12,7 @@ export type ForgeOpenApiDocument = OpenAPIV3.Document & {
 };
 type GroupInfo = { description?: string; 'x-forge-epilogue'?: string };
 type GroupInfoMap = Record<string, Record<string, GroupInfo>>;
-type MethodStatus = Schema.method['status'];
+type MethodStatus = FernAvailabilityStatus;
 
 type OperationMetadata = {
   operationId: string;
@@ -19,6 +20,7 @@ type OperationMetadata = {
   groupPath: string[];
   methodName: string;
   status: MethodStatus;
+  availabilityMessage?: string;
   ignore: boolean;
   hidden: boolean;
   globals?: Schema.arg[];
@@ -30,8 +32,6 @@ type OperationMetadata = {
 
 const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
 
-const METHOD_STATUSES = new Set<string>(['alpha', 'beta', 'preview', 'generally-available', 'deprecated']);
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -78,12 +78,9 @@ function loadCommandGroupInfo(openapi: ForgeOpenApiDocument): GroupInfoMap {
   return groupInfo;
 }
 
-function parseStatus(operationId: string, value: unknown): MethodStatus {
-  if (value === undefined) return 'alpha';
-  if (typeof value !== 'string' || !METHOD_STATUSES.has(value)) {
-    throw new Error(`${operationId}: invalid x-fern-availability ${String(value)}`);
-  }
-  return value as MethodStatus;
+function parseStatus(operationId: string, value: unknown): { status: MethodStatus; message?: string } {
+  if (value === undefined) return { status: 'alpha' };
+  return parseFernAvailability(value, operationId);
 }
 
 function parseMetadata(operationId: string, source: Record<string, unknown>, ignore: boolean): OperationMetadata {
@@ -101,15 +98,17 @@ function parseMetadata(operationId: string, source: Record<string, unknown>, ign
   const methodRaw = source['x-fern-sdk-method-name'];
   const methodName = typeof methodRaw === 'string' && methodRaw ? methodRaw : operationId.split(/[-_]+/).pop() || 'get';
 
+  const availability = parseStatus(operationId, source['x-fern-availability']);
   const metadata: OperationMetadata = {
     operationId,
     commandName,
     groupPath,
     methodName,
-    status: parseStatus(operationId, source['x-fern-availability']),
+    status: availability.status,
     ignore,
     hidden: source['x-forge-hidden'] === true,
   };
+  if (availability.message !== undefined) metadata.availabilityMessage = availability.message;
 
   if (Array.isArray(source['x-forge-globals'])) metadata.globals = source['x-forge-globals'] as Schema.arg[];
   if (typeof source['x-forge-epilogue'] === 'string') metadata.epilogue = source['x-forge-epilogue'];
@@ -155,18 +154,16 @@ function collectOperationMetadata(openapi: ForgeOpenApiDocument): OperationMetad
 }
 
 function toSchemaMethod(metadata: OperationMetadata): Schema.method {
-  const common = {
+  return {
     name: metadata.methodName,
     operationId: metadata.operationId,
+    status: metadata.status,
+    ...(metadata.availabilityMessage !== undefined ? { availabilityMessage: metadata.availabilityMessage } : {}),
     ...(metadata.epilogue !== undefined ? { epilogue: metadata.epilogue } : {}),
     ...(metadata.args !== undefined ? { args: metadata.args } : {}),
     ...(metadata.params !== undefined ? { params: metadata.params } : {}),
     ...(metadata.requireConfirmation !== undefined ? { requireConfirmation: metadata.requireConfirmation } : {}),
   };
-
-  if (metadata.status === 'deprecated') return { ...common, status: 'deprecated' };
-
-  return { ...common, status: metadata.status };
 }
 
 type GroupNode = {
diff --git a/packages/forge/overlay-source.test.ts b/packages/forge/overlay-source.test.ts
index 04d1e1214..3b0ba1bf6 100644
--- a/packages/forge/overlay-source.test.ts
+++ b/packages/forge/overlay-source.test.ts
@@ -464,3 +464,91 @@ test('rejects invalid method lifecycle metadata on the OpenAPI-only path', async
     /available: invalid x-fern-availability stable/,
   );
 });
+
+test('keeps legacy availability and its message through overlay resolution', async () => {
+  const source: ForgeOpenApiDocument = {
+    openapi: '3.0.3',
+    info: { title: 'public', version: '1' },
+    paths: {
+      '/available': {
+        get: {
+          operationId: 'available',
+          description: 'Lists widgets.',
+          responses: {},
+        },
+      },
+    },
+    components: { schemas: {} },
+  };
+  const api = overlay('widgets', [
+    {
+      operationId: 'available',
+      'x-fern-sdk-method-name': 'list',
+      'x-fern-availability': { status: 'legacy', message: 'Use the v2 widgets endpoint.' },
+    },
+  ]);
+
+  const { overlaidOpenApi } = await resolveApiOverlays([api], source, {
+    allowMissingOperations: true,
+    writeArtifacts: false,
+  });
+  const operation = overlaidOpenApi.paths?.['/available']?.get as { 'x-fern-availability'?: unknown } | undefined;
+  assert.deepEqual(operation?.['x-fern-availability'], {
+    status: 'legacy',
+    message: 'Use the v2 widgets endpoint.',
+  });
+
+  const forge = initFromOpenApi(overlaidOpenApi as ForgeOpenApiDocument);
+  const method = forge.commands.get('widgets')?.methods[0];
+  assert.ok(method && !('methods' in method));
+  assert.equal(method.status, 'legacy');
+  assert.equal(method.availabilityMessage, 'Use the v2 widgets endpoint.');
+});
+
+test('reads Fern availability objects directly from an OpenAPI document', () => {
+  const source = {
+    openapi: '3.0.3',
+    info: { title: 'public', version: '1' },
+    paths: {
+      '/widgets': {
+        get: {
+          operationId: 'list-widgets',
+          description: 'Lists widgets.',
+          'x-fern-sdk-group-name': 'widgets',
+          'x-fern-sdk-method-name': 'list',
+          'x-fern-availability': { status: 'preview', message: 'Subject to change.' },
+          responses: {},
+        },
+      },
+    },
+    components: { schemas: {} },
+  } as ForgeOpenApiDocument;
+
+  const forge = initFromOpenApi(source);
+  const method = forge.commands.get('widgets')?.methods[0];
+  assert.ok(method && !('methods' in method));
+  assert.equal(method.status, 'preview');
+  assert.equal(method.availabilityMessage, 'Subject to change.');
+});
+
+test('rejects an availability object with an unknown status on the OpenAPI path', () => {
+  const source = {
+    openapi: '3.0.3',
+    info: { title: 'public', version: '1' },
+    paths: {
+      '/widgets': {
+        get: {
+          operationId: 'list-widgets',
+          description: 'Lists widgets.',
+          'x-fern-sdk-group-name': 'widgets',
+          'x-fern-sdk-method-name': 'list',
+          'x-fern-availability': { status: 'stable', message: 'Ready.' },
+          responses: {},
+        },
+      },
+    },
+    components: { schemas: {} },
+  } as ForgeOpenApiDocument;
+
+  assert.throws(() => initFromOpenApi(source), /list-widgets: invalid x-fern-availability stable/);
+});
diff --git a/packages/forge/overlay-source.ts b/packages/forge/overlay-source.ts
index 2a503eea6..42af37e9b 100644
--- a/packages/forge/overlay-source.ts
+++ b/packages/forge/overlay-source.ts
@@ -8,6 +8,7 @@ import { isObject } from './shared/schema-utils.js';
 import { ensureUniqueSdkMethodNames } from './shared/sdk-method-names.js';
 
 import { stringify as toYaml } from 'yaml';
+import { parseFernAvailability } from './shared/fern-availability.js';
 import type {
   ApiOverlay,
   ApiOverlayFile,
@@ -25,18 +26,6 @@ import type {
 
 type OpenApiDocument = OpenAPIV3.Document;
 
-const METHOD_STATUSES: ReadonlySet<unknown> = new Set([
-  'alpha',
-  'beta',
-  'preview',
-  'generally-available',
-  'deprecated',
-]);
-
-function isMethodStatus(value: unknown): value is Schema.method['status'] {
-  return METHOD_STATUSES.has(value);
-}
-
 type OverlayResolution = {
   commands: Map<string, Schema.command>;
   overlaidOpenApi: OpenApiDocument;
@@ -105,7 +94,9 @@ function isExtensionMethod(value: unknown): value is ExtensionMethods {
   if (!isObject(value)) return false;
   if (typeof value['x-fern-sdk-method-name'] !== 'string') return false;
   if (typeof value.operationId !== 'string') return false;
-  if (typeof value['x-fern-availability'] !== 'string') return false;
+  const availability = value['x-fern-availability'];
+  if (typeof availability !== 'string' && !isObject(availability)) return false;
+  parseFernAvailability(availability, value.operationId);
   return true;
 }
 
@@ -144,40 +135,22 @@ function collectMethods(command: Schema.command): Schema.method[] {
 }
 
 function toSchemaMethod(method: ExtensionMethods): Schema.method {
-  const status: unknown = method['x-fern-availability'];
-  if (!isMethodStatus(status)) {
-    throw new Error(`${method.operationId}: invalid x-fern-availability ${String(status)}`);
-  }
-
-  if (status === 'deprecated') {
-    const deprecated: Schema.method = {
-      name: method['x-fern-sdk-method-name'],
-      operationId: method.operationId,
-      status: 'deprecated',
-    };
-
-    if (method['x-forge-epilogue'] !== undefined) deprecated.epilogue = method['x-forge-epilogue'];
-    if (method['x-forge-args'] !== undefined) deprecated.args = method['x-forge-args'];
-    if (method['x-forge-params'] !== undefined) deprecated.params = method['x-forge-params'];
-    if (method['x-forge-require-confirmation'] !== undefined)
-      deprecated.requireConfirmation = method['x-forge-require-confirmation'];
-
-    return deprecated;
-  }
-
-  const active: Schema.method = {
+  const availability = parseFernAvailability(method['x-fern-availability'], method.operationId);
+  const schemaMethod: Schema.method = {
     name: method['x-fern-sdk-method-name'],
     operationId: method.operationId,
-    status,
+    status: availability.status,
   };
 
-  if (method['x-forge-epilogue'] !== undefined) active.epilogue = method['x-forge-epilogue'];
-  if (method['x-forge-args'] !== undefined) active.args = method['x-forge-args'];
-  if (method['x-forge-params'] !== undefined) active.params = method['x-forge-params'];
-  if (method['x-forge-require-confirmation'] !== undefined)
-    active.requireConfirmation = method['x-forge-require-confirmation'];
+  if (availability.message !== undefined) schemaMethod.availabilityMessage = availability.message;
+  if (method['x-forge-epilogue'] !== undefined) schemaMethod.epilogue = method['x-forge-epilogue'];
+  if (method['x-forge-args'] !== undefined) schemaMethod.args = method['x-forge-args'];
+  if (method['x-forge-params'] !== undefined) schemaMethod.params = method['x-forge-params'];
+  if (method['x-forge-require-confirmation'] !== undefined) {
+    schemaMethod.requireConfirmation = method['x-forge-require-confirmation'];
+  }
 
-  return active;
+  return schemaMethod;
 }
 
 function toSchemaMethodFromMetadata(method: OperationForgeMetadata): Schema.method {
diff --git a/packages/forge/overlay-types.ts b/packages/forge/overlay-types.ts
index 4d26def65..f492f27d5 100644
--- a/packages/forge/overlay-types.ts
+++ b/packages/forge/overlay-types.ts
@@ -1,8 +1,9 @@
 import type { Schema } from './schema/schema.js';
+import type { FernAvailabilityWire } from './shared/fern-availability.js';
 
 export type FernExtensions = {
-  /** @see https://buildwithfern.com/learn/api-definitions/openapi/extensions/availability */
-  'x-fern-availability': Schema.method['status'];
+  /** @see https://buildwithfern.com/learn/api-definition/openapi/extensions/availability */
+  'x-fern-availability': FernAvailabilityWire;
   /** @see https://buildwithfern.com/learn/api-definitions/openapi/extensions/ignoring-elements */
   'x-fern-ignore'?: boolean;
   /** @see https://buildwithfern.com/learn/api-definitions/openapi/extensions/method-names */
@@ -125,8 +126,8 @@ export type OverlaidOperationForgeFields = {
   'x-fern-sdk-group-name': string;
   /** Resolved method name within the group (e.g. 'create') */
   'x-fern-sdk-method-name': string;
-  /** Lifecycle status */
-  'x-fern-availability': Schema.method['status'];
+  /** Lifecycle status, as a Fern status string or `{ status, message }`. */
+  'x-fern-availability': FernAvailabilityWire;
   /** Do not generate any code for this operation in any surface. */
   'x-fern-ignore': boolean;
   /** Generate code but hide from CLI help unless CF_HIDE_COMMANDS is set. */
diff --git a/packages/forge/package.json b/packages/forge/package.json
index 363bfcf7e..95f885ab1 100644
--- a/packages/forge/package.json
+++ b/packages/forge/package.json
@@ -40,7 +40,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test openapi-resolver.test.ts overlay-source.test.ts shared/fern-openapi-compat.test.ts shared/sdk-method-names.test.ts"
+    "test": "node --import tsx --test openapi-resolver.test.ts overlay-source.test.ts shared/fern-availability.test.ts shared/fern-openapi-compat.test.ts shared/sdk-method-names.test.ts"
   },
   "dependencies": {
     "openapi-format": "^1.33.5",
diff --git a/packages/forge/schema/schema.ts b/packages/forge/schema/schema.ts
index f2756afba..c31ae39c0 100644
--- a/packages/forge/schema/schema.ts
+++ b/packages/forge/schema/schema.ts
@@ -1,3 +1,5 @@
+import type { FernAvailabilityStatus } from '../shared/fern-availability.js';
+
 export namespace Schema {
   // Completion source types for shell tab completion
   export type completionSource =
@@ -198,18 +200,23 @@ export namespace Schema {
   };
 
   /**
-   * Active lifecycle statuses (non-deprecated).
-   * Uses the x-fern-availability vocabulary:
-   *   alpha          — early experimental stage
-   *   beta           — stable enough for early adopters
-   *   preview        — feature-complete but subject to change
+   * API method definition with lifecycle status.
+   *
+   * `status` uses Fern's endpoint vocabulary:
+   *   alpha               — early experimental stage
+   *   beta                — stable enough for early adopters
+   *   preview             — feature-complete but subject to change
    *   generally-available — stable and ready for production
+   *   deprecated          — no longer recommended for new use
+   *   legacy              — superseded but still supported
    */
-  type activeStatus = 'alpha' | 'beta' | 'preview' | 'generally-available';
-
-  /** API method definition with lifecycle status. */
   export type method = methodBase & {
-    status: activeStatus | 'deprecated';
+    status: FernAvailabilityStatus;
+    /**
+     * Human note from `x-fern-availability.message`.
+     * Present only when the source used the object form.
+     */
+    availabilityMessage?: string;
   };
 
   export type methodGroup = {
diff --git a/packages/forge/shared/fern-availability.test.ts b/packages/forge/shared/fern-availability.test.ts
new file mode 100644
index 000000000..8fe276ebd
--- /dev/null
+++ b/packages/forge/shared/fern-availability.test.ts
@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { fernAvailabilityJsDocLine, FERN_PRERELEASE_JSDOC, parseFernAvailability } from './fern-availability.ts';
+
+test('parses every Fern endpoint status string', () => {
+  for (const status of ['alpha', 'beta', 'preview', 'generally-available', 'deprecated', 'legacy'] as const) {
+    assert.deepEqual(parseFernAvailability(status, 'listWidgets'), { status });
+  }
+});
+
+test('parses an availability object and trims the message', () => {
+  assert.deepEqual(
+    parseFernAvailability({ status: 'legacy', message: '  Use the v2 widgets endpoint.  ' }, 'listWidgets'),
+    { status: 'legacy', message: 'Use the v2 widgets endpoint.' },
+  );
+});
+
+test('rejects statuses outside the Fern endpoint vocabulary', () => {
+  assert.throws(
+    () => parseFernAvailability('stable', 'listWidgets'),
+    /listWidgets: invalid x-fern-availability stable/,
+  );
+  assert.throws(
+    () => parseFernAvailability({ status: 'in-development' }, 'listWidgets'),
+    /listWidgets: invalid x-fern-availability in-development/,
+  );
+});
+
+test('rejects malformed availability objects', () => {
+  assert.throws(
+    () => parseFernAvailability({ message: 'Missing status' }, 'listWidgets'),
+    /invalid x-fern-availability/,
+  );
+  assert.throws(
+    () => parseFernAvailability({ status: 'beta', message: '   ' }, 'listWidgets'),
+    /listWidgets: invalid x-fern-availability message/,
+  );
+  assert.throws(
+    () => parseFernAvailability({ status: 'beta', note: 'nope' }, 'listWidgets'),
+    /invalid x-fern-availability property "note"/,
+  );
+  assert.throws(() => parseFernAvailability(null, 'listWidgets'), /invalid x-fern-availability null/);
+});
+
+test('maps availability onto the JSDoc tags Fern emits for TypeScript', () => {
+  assert.equal(fernAvailabilityJsDocLine({ status: 'deprecated' }), '@deprecated');
+  assert.equal(
+    fernAvailabilityJsDocLine({ status: 'deprecated', message: 'Use PATCH /widgets.' }),
+    '@deprecated Use PATCH /widgets.',
+  );
+  assert.equal(fernAvailabilityJsDocLine({ status: 'preview' }), `@beta ${FERN_PRERELEASE_JSDOC}`);
+  assert.equal(
+    fernAvailabilityJsDocLine({ status: 'alpha', message: 'Subject to change.' }),
+    '@beta Subject to change.',
+  );
+  assert.equal(fernAvailabilityJsDocLine({ status: 'generally-available' }), undefined);
+  assert.equal(fernAvailabilityJsDocLine({ status: 'legacy', message: 'Still supported.' }), undefined);
+});
diff --git a/packages/forge/shared/fern-availability.ts b/packages/forge/shared/fern-availability.ts
new file mode 100644
index 000000000..a1f87f58d
--- /dev/null
+++ b/packages/forge/shared/fern-availability.ts
@@ -0,0 +1,103 @@
+/**
+ * Fern `x-fern-availability` values.
+ *
+ * Endpoint statuses and the `{ status, message }` object form follow
+ * https://buildwithfern.com/learn/api-definition/openapi/extensions/availability
+ */
+
+export const FERN_AVAILABILITY_STATUSES = [
+  'alpha',
+  'beta',
+  'preview',
+  'generally-available',
+  'deprecated',
+  'legacy',
+] as const;
+
+/** Lifecycle status Fern accepts on an endpoint. */
+export type FernAvailabilityStatus = (typeof FERN_AVAILABILITY_STATUSES)[number];
+
+/** Parsed availability. `message` is set only when the source object included one. */
+export type FernAvailability = {
+  status: FernAvailabilityStatus;
+  message?: string;
+};
+
+/**
+ * Value as it appears on an OpenAPI operation or overlay method.
+ * A bare status string is equivalent to `{ status }` with no message.
+ */
+export type FernAvailabilityWire = FernAvailabilityStatus | { status: FernAvailabilityStatus; message?: string };
+
+const STATUS_SET: ReadonlySet<string> = new Set(FERN_AVAILABILITY_STATUSES);
+
+const PRE_RELEASE_STATUSES: ReadonlySet<FernAvailabilityStatus> = new Set(['alpha', 'beta', 'preview']);
+
+/** Message Fern's TypeScript SDK attaches to pre-release methods when the spec has none. */
+export const FERN_PRERELEASE_JSDOC = 'This endpoint is in pre-release and may change.';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function isFernAvailabilityStatus(value: string): value is FernAvailabilityStatus {
+  return STATUS_SET.has(value);
+}
+
+/**
+ * Parse a Fern availability value.
+ *
+ * Missing values are not defaulted here. Callers that treat omission as `alpha`
+ * should do that before calling.
+ *
+ * @throws When the status is outside Fern's endpoint vocabulary, the object
+ *   has unexpected properties, or `message` is not a non-empty string.
+ */
+export function parseFernAvailability(value: unknown, operationId: string): FernAvailability {
+  const prefix = `${operationId}: invalid x-fern-availability`;
+
+  if (typeof value === 'string') {
+    if (!isFernAvailabilityStatus(value)) throw new Error(`${prefix} ${value}`);
+    return { status: value };
+  }
+
+  if (!isRecord(value)) throw new Error(`${prefix} ${String(value)}`);
+
+  for (const key of Object.keys(value)) {
+    if (key !== 'status' && key !== 'message') {
+      throw new Error(`${prefix} property ${JSON.stringify(key)}`);
+    }
+  }
+
+  const status = value.status;
+  if (typeof status !== 'string' || !isFernAvailabilityStatus(status)) {
+    throw new Error(`${prefix} ${typeof status === 'string' ? status : String(status)}`);
+  }
+
+  if (value.message === undefined) return { status };
+
+  if (typeof value.message !== 'string' || value.message.trim() === '') {
+    throw new Error(`${prefix} message`);
+  }
+
+  return { status, message: value.message.trim() };
+}
+
+/**
+ * JSDoc tag Fern's TypeScript generator emits for this availability.
+ *
+ * `deprecated` becomes `@deprecated`. `alpha`, `beta`, and `preview` become
+ * `@beta`. `generally-available` and `legacy` do not emit a tag; legacy stays
+ * supported, so it is not marked deprecated.
+ */
+export function fernAvailabilityJsDocLine(availability: FernAvailability): string | undefined {
+  if (availability.status === 'deprecated') {
+    return availability.message ? `@deprecated ${availability.message}` : '@deprecated';
+  }
+
+  if (PRE_RELEASE_STATUSES.has(availability.status)) {
+    return `@beta ${availability.message ?? FERN_PRERELEASE_JSDOC}`;
+  }
+
+  return undefined;
+}
diff --git a/packages/forge/shared/index.ts b/packages/forge/shared/index.ts
index 45617d54b..c7c677254 100644
--- a/packages/forge/shared/index.ts
+++ b/packages/forge/shared/index.ts
@@ -23,6 +23,17 @@ export {
 } from './generated-cli-options.js';
 // Fern OpenAPI conversion compatibility
 export { applyFernCompatibilityFixes, type FernCompatibilityFixes } from './fern-openapi-compat.js';
+// Fern endpoint availability
+export {
+  FERN_AVAILABILITY_STATUSES,
+  FERN_PRERELEASE_JSDOC,
+  fernAvailabilityJsDocLine,
+  isFernAvailabilityStatus,
+  parseFernAvailability,
+  type FernAvailability,
+  type FernAvailabilityStatus,
+  type FernAvailabilityWire,
+} from './fern-availability.js';
 // HTTP utilities
 export { getHttpMethod, type HttpMethod, isIdempotentMethod, isSafeMethod, methodHasBody } from './http.js';
 // Interface generation utilities