chore: improve schema-record documentation

Author: runspired

packages/schema-record/README.md

@@ -1,35 +1,37 @@
 <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
 - 🚀 Scalable
 - ⚛️ 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
 

packages/schema-record/src/index.ts

@@ -1,9 +1,75 @@
 /**
- * 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>
+ *
+ * - ⚡️ Fast
+ * - 📦 Tiny
+ * - ✨ Optimized
+ * - 🚀 Scalable
+ * - ⚛️ Universal
+ * - ☢️ Reactive
+ *
+ * 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
  *
  * @module @warp-drive/schema-record
  * @main @warp-drive/schema-record