diff --git a/packages/core-types/src/schema/fields.ts b/packages/core-types/src/schema/fields.ts
index e38117dfb7..13f397f685 100644
--- a/packages/core-types/src/schema/fields.ts
+++ b/packages/core-types/src/schema/fields.ts
@@ -17,23 +17,42 @@ import type { ObjectValue, PrimitiveValue } from '../json/raw';
  * "type" points to a new-style transform on "field"
  * that a record implmentation *must* use.
  *
- * @typedoc
+ * @class <Type> GenericField
+ * @public
  */
 export interface GenericField {
+  /**
+   * The kind of field this is.
+   *
+   * @property {'field'} kind
+   * @public
+   */
   kind: 'field';
+
+  /**
+   * The name of the field.
+   *
+   * @property {string} name
+   * @public
+   */
   name: string;
+
   /**
    * the name of the transform to use, if any
-   * @typedoc
+   *
+   * @property {string | undefined} type
+   * @public
    */
   type?: string;
+
   /**
    * Options to pass to the transform, if any
    *
    * Must comply to the specific transform's options
    * schema.
    *
-   * @typedoc
+   * @property {ObjectValue | undefined} options
+   * @public
    */
   options?: ObjectValue;
 }
@@ -64,7 +83,8 @@ export interface GenericField {
  * an AliasField could be used to expose both a string and a Date version of the
  * same field, with both being capable of being written to.
  *
- * @typedoc
+ * @class <Type> LegacyAliasField
+ * @public
  */
 export interface LegacyAliasField {
   kind: 'alias';
@@ -115,7 +135,8 @@ export interface LegacyAliasField {
  * an AliasField could be used to expose both a string and a Date version of the
  * same field, with both being capable of being written to.
  *
- * @typedoc
+ * @class <Type> PolarisAliasField
+ * @public
  */
 export interface PolarisAliasField {
   kind: 'alias';
@@ -165,7 +186,8 @@ export interface PolarisAliasField {
  * an AliasField could be used to expose both a string and a Date version of the
  * same field, with both being capable of being written to.
  *
- * @typedoc
+ * @class <Type> ObjectAliasField
+ * @public
  */
 export interface ObjectAliasField {
   kind: 'alias';
@@ -192,7 +214,8 @@ export interface ObjectAliasField {
  * 'uuid', 'urn' or 'entityUrn' or 'primaryKey' as their
  * primary key field instead of 'id'.
  *
- * @typedoc
+ * @class <Type> IdentityField
+ * @public
  */
 export interface IdentityField {
   kind: '@id';
@@ -227,7 +250,8 @@ export interface IdentityField {
  * it should be placed in the `ResourceSchema`'s `@id` field
  * in place of an `IdentityField`.
  *
- * @typedoc
+ * @class <Type> HashField
+ * @public
  */
 export interface HashField {
   kind: '@hash';
@@ -288,7 +312,8 @@ export interface HashField {
  *
  * Don't make us regret this decision.
  *
- * @typedoc
+ * @class <Type> LocalField
+ * @public
  */
 export interface LocalField {
   kind: '@local';
@@ -312,7 +337,8 @@ export interface LocalField {
  * if the key/value pairs have well-defined shape,
  * use 'schema-object' instead.
  *
- * @typedoc
+ * @class <Type> ObjectField
+ * @public
  */
 export interface ObjectField {
   kind: 'object';
@@ -345,7 +371,8 @@ export interface ObjectField {
  * If the object's structure is not well-defined,
  * use 'object' instead.
  *
- * @typedoc
+ * @class <Type> SchemaObjectField
+ * @public
  */
 export interface SchemaObjectField {
   kind: 'schema-object';
@@ -390,7 +417,8 @@ export interface SchemaObjectField {
  * If the array's elements are not primitive
  * values, use 'schema-array' instead.
  *
- * @typedoc
+ * @class <Type> ArrayField
+ * @public
  */
 export interface ArrayField {
   kind: 'array';
@@ -424,7 +452,8 @@ export interface ArrayField {
  * If the array's elements are not well-defined,
  * use 'array' instead.
  *
- * @typedoc
+ * @class <Type> SchemaArrayField
+ * @public
  */
 export interface SchemaArrayField {
   kind: 'schema-array';
@@ -512,7 +541,8 @@ export interface SchemaArrayField {
  * or that require access to related resources
  * that may not be loaded should be avoided.
  *
- * @typedoc
+ * @class <Type> DerivedField
+ * @public
  */
 export interface DerivedField {
   kind: 'derived';
@@ -557,7 +587,8 @@ export interface DerivedField {
  * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
  * BY SchemaRecord
  *
- * @typedoc
+ * @class <Type> ResourceField
+ * @public
  */
 export interface ResourceField {
   kind: 'resource';
@@ -635,7 +666,8 @@ export interface ResourceField {
  * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
  * BY SchemaRecord
  *
- * @typedoc
+ * @class <Type> CollectionField
+ * @public
  */
 export interface CollectionField {
   kind: 'collection';
@@ -731,7 +763,8 @@ export interface CollectionField {
  * that a serializer *might* use, but their usage
  * is not guaranteed.
  *
- * @typedoc
+ * @class <Type> LegacyAttributeField
+ * @public
  */
 export interface LegacyAttributeField {
   kind: 'attribute';
@@ -762,7 +795,8 @@ export interface LegacyAttributeField {
  *
  * This is the legacy version of the `ResourceField`.
  *
- * @typedoc
+ * @class <Type> LegacyBelongsToField
+ * @public
  */
 export interface LegacyBelongsToField {
   kind: 'belongsTo';
@@ -890,7 +924,8 @@ export interface LegacyBelongsToField {
  *
  * This is the legacy version of the `ResourceField`.
  *
- * @typedoc
+ * @class <Type> LinksModeBelongsToField
+ * @public
  */
 export interface LinksModeBelongsToField {
   kind: 'belongsTo';
@@ -1017,7 +1052,8 @@ export interface LinksModeBelongsToField {
  *
  * This is the legacy version of the `CollectionField`.
  *
- * @typedoc
+ * @class <Type> LegacyHasManyField
+ * @public
  */
 export interface LegacyHasManyField {
   kind: 'hasMany';
@@ -1141,7 +1177,8 @@ export interface LegacyHasManyField {
  *
  * This is the legacy version of the `CollectionField`.
  *
- * @typedoc
+ * @class <Type> LinksModeHasManyField
+ * @public
  */
 export interface LinksModeHasManyField {
   kind: 'hasMany';
@@ -1265,7 +1302,24 @@ export interface LinksModeHasManyField {
 /**
  * A union of all possible LegacyMode field schemas.
  *
- * @typedoc
+ * Available field schemas are:
+ *
+ * - [GenericField](../classes/<Type>%20GenericField)
+ * - [LegacyAliasField](../classes/<Type>%20LegacyAliasField)
+ * - [LocalField](../classes/<Type>%20LocalField)
+ * - [ObjectField](../classes/<Type>%20ObjectField)
+ * - [SchemaObjectField](../classes/<Type>%20SchemaObjectField)
+ * - [ArrayField](../classes/<Type>%20ArrayField)
+ * - [SchemaArrayField](../classes/<Type>%20SchemaArrayField)
+ * - [DerivedField](../classes/<Type>%20DerivedField)
+ * - [ResourceField (not yet implemented)](../classes/<Type>%20ResourceField)
+ * - [CollectionField (not yet implemented)](../classes/<Type>%20CollectionField)
+ * - [LegacyAttributeField](../classes/<Type>%20LegacyAttributeField)
+ * - [LegacyBelongsToField](../classes/<Type>%20LegacyBelongsToField)
+ * - [LegacyHasManyField](../classes/<Type>%20LegacyHasManyField)
+ *
+ * @class <Type> LegacyModeFieldSchema
+ * @public
  */
 export type LegacyModeFieldSchema =
   | GenericField
@@ -1276,8 +1330,8 @@ export type LegacyModeFieldSchema =
   | ArrayField
   | SchemaArrayField
   | DerivedField
-  //  | ResourceField
-  //  | CollectionField
+  //  | ResourceField // not yet implemented
+  //  | CollectionField // not yet implemented
   | LegacyAttributeField
   | LegacyBelongsToField
   | LegacyHasManyField;
@@ -1285,7 +1339,23 @@ export type LegacyModeFieldSchema =
 /**
  * A union of all possible PolarisMode field schemas.
  *
- * @typedoc
+ * Available field schemas are:
+ *
+ * - [GenericField](../classes/<Type>%20GenericField)
+ * - [PolarisAliasField](../classes/<Type>%20PolarisAliasField)
+ * - [LocalField](../classes/<Type>%20LocalField)
+ * - [ObjectField](../classes/<Type>%20ObjectField)
+ * - [SchemaObjectField](../classes/<Type>%20SchemaObjectField)
+ * - [ArrayField](../classes/<Type>%20ArrayField)
+ * - [SchemaArrayField](../classes/<Type>%20SchemaArrayField)
+ * - [DerivedField](../classes/<Type>%20DerivedField)
+ * - [ResourceField (not yet implemented)](../classes/<Type>%20ResourceField)
+ * - [CollectionField (not yet implemented)](../classes/<Type>%20CollectionField)
+ * - [LinksModeBelongsToField](../classes/<Type>%20LinksModeBelongsToField)
+ * - [LinksModeHasManyField](../classes/<Type>%20LinksModeHasManyField)
+ *
+ * @class <Type> PolarisModeFieldSchema
+ * @public
  */
 export type PolarisModeFieldSchema =
   | GenericField
@@ -1310,7 +1380,8 @@ export type PolarisModeFieldSchema =
  * as appropriate as they are more specific and will
  * provide better guidance around what is valid.
  *
- * @typedoc
+ * @class <Type> FieldSchema
+ * @public
  */
 export type FieldSchema =
   | GenericField
@@ -1334,7 +1405,8 @@ export type FieldSchema =
  * A union of all possible field schemas that can be
  * used in an ObjectSchema.
  *
- * @typedoc
+ * @class <Type> ObjectFieldSchema
+ * @public
  */
 export type ObjectFieldSchema =
   | GenericField
@@ -1353,7 +1425,8 @@ export type ObjectFieldSchema =
  * own which may allow them to appear in relationships, or in multiple
  * response documents.
  *
- * @typedoc
+ * @class <Type> PolarisResourceSchema
+ * @public
  */
 export interface PolarisResourceSchema {
   legacy?: false;
@@ -1363,7 +1436,8 @@ export interface PolarisResourceSchema {
    *
    * for schema-objects, this should be either a HashField or null
    *
-   * @typedoc
+   * @property {IdentityField} identity
+   * @public
    */
   identity: IdentityField;
 
@@ -1386,14 +1460,16 @@ export interface PolarisResourceSchema {
    * - for resource-specific objects: The pattern `$${ResourceKlassName}:$field:${KlassName}` e.g. `$User:$field:ReusableAddress`
    * - for inline objects: The pattern `$${ResourceKlassName}.${fieldPath}:$field:anonymous` e.g. `$User.shippingAddress:$field:anonymous`
    *
-   * @typedoc
+   * @property {string} type
+   * @public
    */
   type: string;
 
   /**
    * The fields that make up the shape of the resource
    *
-   * @typedoc
+   * @property {PolarisModeFieldSchema[]} fields
+   * @public
    */
   fields: PolarisModeFieldSchema[];
 
@@ -1405,7 +1481,8 @@ export interface PolarisResourceSchema {
    * resource schema. The trait can be abstract and reference a resource
    * type that is never defined as a schema.
    *
-   * @typedoc
+   * @property {string[]} traits
+   * @public
    */
   traits?: string[];
 }
@@ -1417,17 +1494,27 @@ export interface PolarisResourceSchema {
  * own which may allow them to appear in relationships, or in multiple
  * response documents.
  *
- * @typedoc
+ * @class <Type> LegacyResourceSchema
+ * @public
  */
 export interface LegacyResourceSchema {
+  /**
+   * A flag indicating that this is a legacy resource schema
+   *
+   * @property {true} legacy
+   * @public
+   */
   legacy: true;
 
   /**
-   * For primary resources, this should be an IdentityField
+   * This should be an IdentityField.
    *
-   * for schema-objects, this should be either a HashField or null
+   * To maximize compatibility with Model where `id` was the
+   * name of the identity field, we recommend using `{ kind: '@id', name: 'id' }`
+   * for records in legacy mode, but this is not required.
    *
-   * @typedoc
+   * @property {IdentityField} identity
+   * @public
    */
   identity: IdentityField;
 
@@ -1437,9 +1524,6 @@ export interface LegacyResourceSchema {
    * For cacheable resources, this should be the
    * primary resource type.
    *
-   * For object schemas, this should be the name
-   * of the object schema.
-   *
    * The names of object and resource schemas share
    * a single namespace and must not conflict.
    *
@@ -1450,14 +1534,16 @@ export interface LegacyResourceSchema {
    * - for resource-specific objects: The pattern `$${ResourceKlassName}:$field:${KlassName}` e.g. `$User:$field:ReusableAddress`
    * - for inline objects: The pattern `$${ResourceKlassName}.${fieldPath}:$field:anonymous` e.g. `$User.shippingAddress:$field:anonymous`
    *
-   * @typedoc
+   * @property {string} type
+   * @public
    */
   type: string;
 
   /**
    * The fields that make up the shape of the resource
    *
-   * @typedoc
+   * @property {LegacyModeFieldSchema[]} fields
+   * @public
    */
   fields: LegacyModeFieldSchema[];
 
@@ -1469,7 +1555,8 @@ export interface LegacyResourceSchema {
    * resource schema. The trait can be abstract and reference a resource
    * type that is never defined as a schema.
    *
-   * @typedoc
+   * @property {string[]} traits
+   * @public
    */
   traits?: string[];
 }
@@ -1493,7 +1580,8 @@ export type ResourceSchema = PolarisResourceSchema | LegacyResourceSchema;
  *
  * ObjectSchemas may not currently contain relationships.
  *
- * @typedoc
+ * @class <Type> ObjectSchema
+ * @public
  */
 export interface ObjectSchema {
   /**
@@ -1503,7 +1591,8 @@ export interface ObjectSchema {
    * on the referential identity of the object in the cache itself
    * when an identity is needed.
    *
-   * @typedoc
+   * @property {HashField | null} identity
+   * @public
    */
   identity: HashField | null;
 
@@ -1520,14 +1609,16 @@ export interface ObjectSchema {
    * - for resource-specific objects: The pattern `$${ResourceKlassName}:$field:${KlassName}` e.g. `$User:$field:ReusableAddress`
    * - for inline objects: The pattern `$${ResourceKlassName}.${fieldPath}:$field:anonymous` e.g. `$User.shippingAddress:$field:anonymous`
    *
-   * @typedoc
+   * @property {string} type
+   * @public
    */
   type: string;
 
   /**
    * The fields that make up the shape of the object
    *
-   * @typedoc
+   * @property {ObjectFieldSchema[]} fields
+   * @public
    */
   fields: ObjectFieldSchema[];
 }
diff --git a/packages/schema-record/README.md b/packages/schema-record/README.md
index 9071910ea1..88182ac957 100644
--- a/packages/schema-record/README.md
+++ b/packages/schema-record/README.md
@@ -1,23 +1,21 @@
 <p align="center">
   <img
     class="project-logo"
-    src="./logos/NCC-1701-a-blue.svg#gh-light-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    src="./logos/github-header.svg#gh-light-mode-only"
+    alt="WarpDrive | Boldly go where no app has gone before"
+    title="WarpDrive | Boldly go where no app has gone before"
+    />
   <img
     class="project-logo"
-    src="./logos/NCC-1701-a.svg#gh-dark-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    src="./logos/github-header.svg#gh-dark-mode-only"
+    alt="WarpDrive | Boldly go where no app has gone before"
+    title="WarpDrive | Boldly go where no app has gone before"
+    />
 </p>
 
 <h3 align="center">Your Data, Managed.</h3>
 <p align="center">🌲 Get back to Nature 🐿️ Or shipping 💚</p>
 
-SchemaRecord is:
-
 - ⚡️ Fast
 - 📦 Tiny
 - ✨ Optimized
@@ -25,11 +23,15 @@ SchemaRecord is:
 - ⚛️ Universal
 - ☢️ Reactive
 
-This package provides reactive capabilities for your resource data.
-It works together with a [*Warp***Drive**](https://github.com/emberjs/data/)
-[Cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts)
-and associated Schemas to simplify the most complex parts of your
-app's state management.
+SchemaRecord is a reactive object that transforms raw data from an [associated cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts) into reactive data backed by Signals.
+
+The shape of the object and the transformation of raw cache data into its
+reactive form is controlled by a resource schema.
+
+Resource schemas are simple JSON, allowing them to be defined and delivered from anywhere.
+
+The capabilities that SchemaRecord brings to [*Warp***Drive**](https://github.com/emberjs/data/)
+will simplify even the most complex parts of your app's state management.
 
 ## Installation
 
@@ -150,7 +152,8 @@ store.registerSchemas([
         options: {
           async: false,
           inverse: 'owner',
-          polymorphic: true
+          polymorphic: true,
+          linksMode: true,
         }
       }
     ]
@@ -174,6 +177,7 @@ store.registerSchemas([
           async: false,
           inverse: 'pets',
           as: 'pet',
+          linksMode: true,
         }
       }
     ]
@@ -286,6 +290,16 @@ store.registerSchemas([
 ]);
 ```
 
+Additionally, `@warp-drive/core-types` provides several utilities for type-checking and narrowing schemas.
+
+- (type) [PolarisResourceSchema]()
+- (type) [LegacyResourceSchema]()
+- (type) [ObjectSchema]()
+- [resourceSchema]()
+- [objectSchema]()
+- [isResourceSchema]()
+- [isLegacyResourceSchema]()
+
 
 ### Field Schemas
 
diff --git a/packages/schema-record/src/index.ts b/packages/schema-record/src/index.ts
index 55511ad000..04e9eee1ee 100644
--- a/packages/schema-record/src/index.ts
+++ b/packages/schema-record/src/index.ts
@@ -1,9 +1,336 @@
 /**
- * This package provides reactive capabilities for your resource data.
- * It works together with a [*Warp***Drive**](https://github.com/emberjs/data/)
- * [Cache](../classes/<Interface>%20Cache)
- * and associated Schemas to simplify the most complex parts of your
- * app's state management.
+ * <h3 align="center">Your Data, Managed.</h3>
+ * <p align="center">🌲 Get back to Nature 🐿️ Or shipping 💚</p>
+ *
+ * SchemaRecord is a reactive object that transforms raw data from an [associated cache](../classes/<Interface>%20Cache)
+ * into reactive data backed by Signals. The shape of the object and the transformation of raw cache data into its
+ * reactive form is controlled by a resource schema. Resource schemas are simple JSON, allowing them to be defined
+ * and delivered from anywhere.
+ *
+ * The capabilities that SchemaRecord brings to [*Warp***Drive**](https://github.com/emberjs/data/)
+ * will simplify even the most complex parts of your app's state management.
+ *
+ * ## Installation
+ *
+ * Install using your javascript package manager of choice. For instance
+ * with [pnpm](https://pnpm.io/)
+ *
+ * ```cli
+ * pnpm add @warp-drive/schema-record
+ * ```
+ *
+ *
+ * ---
+ *
+ *
+ * ## Getting Started
+ *
+ * If this package is how you are first learning about WarpDrive/EmberData, we
+ * recommend starting with learning about [Requests](../modules/@ember-data%2Frequest)
+ * and the [Store](../modules/@ember-data%2Fstore).
+ *
+ *
+ * ---
+ *
+ *
+ * ## 🚀 Setup
+ *
+ * SchemaRecord integrates with WarpDrive via the Store's resource lifecycle hooks.
+ * When WarpDrive needs to create a new record instance to give reactive access to
+ * a resource in the cache, it calls `instantiateRecord`. When it no longer needs
+ * that instance, it will call `teardownRecord`.
+ *
+ * ```diff
+ * import Store from '@ember-data/store';
+ * +import { instantiateRecord, teardownRecord, registerDerivations, SchemaService } from '@warp-drive/schema-record';
+ *
+ * class AppStore extends Store {
+ *
+ * +  createSchemaService() {
+ * +    const schema = new SchemaService();
+ * +    registerDerivations(schema);
+ * +    return schema;
+ * +  }
+ *
+ * +  instantiateRecord(identifier, createArgs) {
+ * +    return instantiateRecord(this, identifier, createArgs);
+ * +  }
+ *
+ * +  teardownRecord(record) {
+ * +    return teardownRecord(record);
+ * +  }
+ * }
+ * ```
+ *
+ * Any Store API that returns a record instance will use the `instantiateRecord`
+ * hook configured above to instantiate a SchemaRecord once this is in place.
+ * After that, its up to you what SchemaRecord can do.
+ *
+ *
+ * ---
+ *
+ *
+ * ## Start Using
+ *
+ * ### Modes
+ *
+ * SchemaRecord has two modes: `legacy` and `polaris`.
+ *
+ * **LegacyMode** can be used to emulate the behaviors and capabilities of EmberData's `Model` class,
+ * and because there is little distinction between Model and SchemaRecord in LegacyMode we refer
+ * to both of these approaches as LegacyMode. This mode is the default experience in V5.
+ *
+ * In LegacyMode:
+ *
+ * - records are mutable
+ * - local changes immediately reflect app wide
+ * - records have all the APIs of Model (references, state props, currentState, methods etc)
+ * - the continued use of `@ember-data/model` and `@ember-data/legacy-compat` packages is required (though most imports from them can be removed)
+ * - `async: true` relationships are supported (but not recommended outside of [LinksMode](https://github.com/emberjs/data/blob/main/guides/relationships/features/links-mode.md))
+ *
+ * ---
+ *
+ * **PolarisMode** is an upcoming suite of features that will become the default experience in V6.
+ *
+ * In PolarisMode:
+ *
+ * - records are immutable, unless creating a new resource or explicitly checking out a record for editing
+ * - local changes are isolated until committed, displaying only via the editable version of the record
+ * - records have a more limited API, focused on only what is in their schema.
+ * - some common operations may have more friction to perform because intended utilities are not yet available
+ * - `async: true` relationships are not supported (see [LinksMode](https://github.com/emberjs/data/blob/main/guides/relationships/features/links-mode.md))
+ * - `@ember-data/model` and `@ember-data/legacy-compat` packages are not required
+ *
+ * These modes are interopable. The reactive object (record) for a resource in PolarisMode can relate to
+ * a record in LegacyMode and vice-versa. This interopability is true whether the record in LegacyMode is
+ * a SchemaRecord or a Model.
+ *
+ * ---
+ *
+ * ### About
+ *
+ * SchemaRecord is a reactive object that transforms raw data from an associated
+ * cache into reactive data backed by Signals.
+ *
+ * The shape of the object and the transformation of raw cache data into its
+ * reactive form is controlled by a resource schema.
+ *
+ * For instance, lets say your API is a [{JSON:API}](https://jsonapi.org) and your store is using
+ * the Cache provided by [@ember-data/json-api](../modules/@ember-data%2Fjson-api), and a request
+ * returns the following raw data:
+ *
+ * ```ts
+ * {
+ *   data: {
+ *     type: 'user',
+ *     id: '1',
+ *     attributes: { firstName: 'Chris', lastName: 'Thoburn' },
+ *     relationships: { pets: { data: [{ type: 'dog', id: '1' }] }}
+ *   },
+ *   included: [
+ *     {
+ *       type: 'dog',
+ *       id: '1',
+ *       attributes: { name: 'Rey' },
+ *       relationships: { owner: { data: { type: 'user', id: '1' }}}
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * We could describe the `'user'` and `'dog'` resources in the above payload
+ * with the following schemas:
+ *
+ * ```ts
+ * store.registerSchemas([
+ *   {
+ *     type: 'user',
+ *     identity: { type: '@id', name: 'id' },
+ *     fields: [
+ *       {
+ *         type: '@identity',
+ *         name: '$type',
+ *         kind: 'derived',
+ *         options: { key: 'type' },
+ *       },
+ *       { kind: 'field', name: 'firstName' },
+ *       { kind: 'field', name: 'lastName' },
+ *       {
+ *         kind: 'derived',
+ *         name: 'name',
+ *         type: 'concat',
+ *         options: { fields: ['firstName', 'lastName'], separator: ' ' }
+ *       },
+ *       {
+ *         kind: 'hasMany',
+ *         name: 'pets',
+ *         type: 'pet',
+ *         options: {
+ *           async: false,
+ *           inverse: 'owner',
+ *           polymorphic: true,
+ *           linksMode: true,
+ *         }
+ *       }
+ *     ]
+ *   },
+ *   {
+ *     type: 'dog',
+ *     identity: { type: '@id', name: 'id' },
+ *     fields: [
+ *       {
+ *         type: '@identity',
+ *         name: '$type',
+ *         kind: 'derived',
+ *         options: { key: 'type' },
+ *       },
+ *       { kind: 'field', name: 'name' },
+ *       {
+ *         kind: 'belongsTo',
+ *         name: 'owner',
+ *         type: 'user',
+ *         options: {
+ *           async: false,
+ *           inverse: 'pets',
+ *           as: 'pet',
+ *           linksMode: true,
+ *         }
+ *       }
+ *     ]
+ *   }
+ * ]);
+ * ```
+ *
+ * With these schemas in place, the reactive objects that the store would
+ * provide us whenever we encountered a `'user'` or a `'dog'` would be:
+ *
+ * ```ts
+ *
+ * interface Pet {
+ *   readonly id: string;
+ *   readonly owner: User;
+ * }
+ *
+ * interface Dog extends Pet {
+ *   readonly $type: 'dog';
+ *   readonly name: string;
+ * }
+ *
+ * interface EditableUser {
+ *   readonly $type: 'user';
+ *   readonly id: string;
+ *   firstName: string;
+ *   lastName: string;
+ *   readonly name: string;
+ *   pets: Array<Dog | Pet>;
+ * }
+ *
+ * interface User {
+ *   readonly $type: 'user';
+ *   readonly id: string;
+ *   readonly firstName: string;
+ *   readonly lastName: string;
+ *   readonly name: string;
+ *   readonly pets: Readonly<Array<Dog | Pet>>;
+ *   [Checkout]: Promise<EditableUser>
+ * }>
+ * ```
+ *
+ * Note how based on the schema the reactive object we receive is able to produce
+ * `name` on user (despite no name field being in the cache), provide `$type`
+ * pulled from the identity of the resource, and flatten the individual attributes
+ * and relationships onto the record for easier use.
+ *
+ * Notice also how we typed this object with `readonly`. This is because while
+ * SchemaRecord instances are ***deeply reactive***, they are also ***immutable***.
+ *
+ * We can mutate a SchemaRecord only be explicitly asking permission to do so, and
+ * in the process gaining access to an editable copy. The immutable version will
+ * not show any in-process edits made to this editable copy.
+ *
+ * ```ts
+ * import { Checkout } from '@warp-drive/schema-record';
+ *
+ * const editable = await user[Checkout]();
+ * ```
+ *
+ * ---
+ *
+ * ### Utilities
+ *
+ * SchemaRecord provides a schema builder that simplifies setting up a couple of
+ * conventional fields like identity and `$type`. We can rewrite the schema
+ * definition above using this utility like so:
+ *
+ * ```ts
+ * import { withDefaults } from '@warp-drive/schema-record';
+ *
+ * store.registerSchemas([
+ *   withDefaults({
+ *     type: 'user',
+ *     fields: [
+ *       { kind: 'field', name: 'firstName' },
+ *       { kind: 'field', name: 'lastName' },
+ *       {
+ *         kind: 'derived',
+ *         name: 'name',
+ *         type: 'concat',
+ *         options: { fields: ['firstName', 'lastName'], separator: ' ' }
+ *       },
+ *       {
+ *         kind: 'hasMany',
+ *         name: 'pets',
+ *         type: 'pet',
+ *         options: {
+ *           async: false,
+ *           inverse: 'owner',
+ *           polymorphic: true,
+ *           linksMode: true,
+ *         }
+ *       }
+ *     ]
+ *   }),
+ *   withDefaults({
+ *     type: 'dog',
+ *     fields: [
+ *       { kind: 'field', name: 'name' },
+ *       {
+ *         kind: 'belongsTo',
+ *         name: 'owner',
+ *         type: 'user',
+ *         options: {
+ *           async: false,
+ *           inverse: 'pets',
+ *           as: 'pet',
+ *           linksMode: true,
+ *         }
+ *       }
+ *     ]
+ *   })
+ * ]);
+ * ```
+ *
+ * Additionally, `@warp-drive/core-types` provides several utilities for type-checking and narrowing schemas.
+ *
+ * - (type) [PolarisResourceSchema]()
+ * - (type) [LegacyResourceSchema]()
+ * - (type) [ObjectSchema]()
+ * - [resourceSchema](../functions/@warp-drive%2Fcore-types/resourceSchema)
+ * - [objectSchema](../functions/@warp-drive%2Fcore-types/objectSchema)
+ * - [isResourceSchema](../functions/@warp-drive%2Fcore-types/isResourceSchema)
+ * - [isLegacyResourceSchema](../functions/@warp-drive%2Fcore-types/isLegacyResourceSchema)
+ *
+ * ---
+ *
+ * ### Field Schemas
+ *
+ * LegacyMode
+ *
+ * - (type) [LegacyFieldSchema]()
+ *
+ * PolarisMode
+ *
+ * - (type) [FieldSchema]()
  *
  * @module @warp-drive/schema-record
  * @main @warp-drive/schema-record
diff --git a/tests/docs/fixtures/expected.js b/tests/docs/fixtures/expected.js
index be96d42298..a77725bbf3 100644
--- a/tests/docs/fixtures/expected.js
+++ b/tests/docs/fixtures/expected.js
@@ -31,6 +31,22 @@ module.exports = {
     'ember-data-overview',
   ],
   classitems: [
+    '(public) @warp-drive/core-types <Type> LegacyResourceSchema#fields',
+    '(public) @warp-drive/core-types <Type> LegacyResourceSchema#identity',
+    '(public) @warp-drive/core-types <Type> LegacyResourceSchema#legacy',
+    '(public) @warp-drive/core-types <Type> LegacyResourceSchema#traits',
+    '(public) @warp-drive/core-types <Type> LegacyResourceSchema#type',
+    '(public) @warp-drive/core-types <Type> ObjectSchema#fields',
+    '(public) @warp-drive/core-types <Type> ObjectSchema#identity',
+    '(public) @warp-drive/core-types <Type> ObjectSchema#type',
+    '(public) @warp-drive/core-types <Type> PolarisResourceSchema#fields',
+    '(public) @warp-drive/core-types <Type> PolarisResourceSchema#identity',
+    '(public) @warp-drive/core-types <Type> PolarisResourceSchema#traits',
+    '(public) @warp-drive/core-types <Type> PolarisResourceSchema#type',
+    '(public) @warp-drive/core-types <Type> GenericField#kind',
+    '(public) @warp-drive/core-types <Type> GenericField#name',
+    '(public) @warp-drive/core-types <Type> GenericField#options',
+    '(public) @warp-drive/core-types <Type> GenericField#type',
     '(public) @warp-drive/core-types @warp-drive/core-types#isLegacyResourceSchema',
     '(public) @warp-drive/core-types @warp-drive/core-types#isResourceSchema',
     '(public) @warp-drive/core-types @warp-drive/core-types#objectSchema',