@harperfast/template-vue-ts-studio 1.9.2 → 1.10.0

package/.agents/skills/harper-best-practices/AGENTS.md

@@ -40,7 +40,7 @@ type ExamplePerson @table @export {
 }
 ```
 
-### 1.2 Schema Design and Tooling
+### 1.2 Schema Design and GraphQL Tooling
 
 Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
@@ -50,7 +50,18 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
 
 #### How It Works
 
-1. **Create a GraphQL schema file** with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
+1. **Create a schema file** using standard GraphQL type definitions with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
+
+2. **Register the schema** in the component's `config.yaml` using the `graphqlSchema` plugin:
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   ```
+
+   Both plugins and applications can specify schemas.
+
+3. **Mark types as tables** with `@table`. The type name becomes the table name by default:
 
    ```graphql
    type Dog @table {
@@ -59,23 +70,36 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    	breed: String
    	age: Int
    }
+   ```
+
+4. **Designate a primary key** with `@primaryKey` on exactly one field per type. Primary keys must be unique; duplicate-key inserts are rejected. If no primary key is provided on insert, Harper auto-generates one:
+   - `String` or `ID` → UUID string
+   - `Int`, `Long`, or `Any` → auto-incrementing integer
+
+   Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
+
+5. **Add secondary indexes** with `@indexed` on any field that will be used for filtering in REST queries, SQL, or NoSQL operations:
 
+   ```graphql
    type Breed @table {
    	id: Long @primaryKey
    	name: String @indexed
    }
    ```
 
-2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin key:
+   If the field value is an array, each element is individually indexed. Null values are indexed by default.
 
-   ```yaml
-   graphqlSchema:
-     files: 'schema.graphql'
+6. **Expose a table as an external endpoint** with `@export`. The optional `name` parameter sets the URL path segment:
+
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
    ```
 
-   Both plugins and applications can specify schemas this way.
+   Without `name`, the type name is used as the path segment.
 
-3. **Mark every table type with `@table`**. The type name becomes the table name by default. Use optional arguments to override behavior:
+7. **Configure `@table` arguments** as needed for database placement, expiration, eviction, and replication:
 
    | Argument       | Type      | Default                       | Description                                                   |
    | -------------- | --------- | ----------------------------- | ------------------------------------------------------------- |
@@ -86,147 +110,271 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    | `scanInterval` | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                |
    | `replicate`    | `Boolean` | `true`                        | Enable replication of this table                              |
 
-4. **Designate a primary key on every table** using `@primaryKey`. Primary keys must be unique; duplicate-key inserts are rejected. If no key is provided on insert, Harper auto-generates one:
-   - `String` or `ID` → UUID string
-   - `Int`, `Long`, or `Any` → auto-incrementing integer
+8. **Apply additional field directives** where needed:
+   - `@createdTime` — auto-assigns Unix epoch milliseconds on record creation
+   - `@updatedTime` — auto-assigns Unix epoch milliseconds on each update
+   - `@embed(source: "fieldName", model: "modelName")` — computes an embedding vector on write; attribute type must be `[Float]`
+   - `@hidden` — suppresses the field from MCP tool descriptors and OpenAPI documents (not an access-control mechanism)
 
-   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
+9. **Restrict extra properties** with `@sealed` if records must not include properties beyond those declared:
+   ```graphql
+   type StrictRecord @table @sealed {
+   	id: Long @primaryKey
+   	name: String
+   }
+   ```
 
-5. **Index fields that need fast querying** with `@indexed`. This is required for filtering by that attribute in REST queries, SQL, or NoSQL operations. If the field value is an array, each element is individually indexed.
+#### Examples
+
+**Minimal two-table schema:**
+
+```graphql
+type Dog @table {
+	id: Long @primaryKey
+	name: String
+	breed: String
+	age: Int
+}
+
+type Breed @table {
+	id: Long @primaryKey
+	name: String @indexed
+}
+```
+
+**Table with expiration, eviction, and custom scan interval:**
+
+```graphql
+# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
+type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
+	id: ID @primaryKey
+	temperature: Float
+}
+```
+
+**Exported table with timestamps and a hidden field:**
+
+```graphql
+type Customer @table @export(name: "customers") {
+	id: Long @primaryKey
+	name: String @indexed
+	createdAt: Long @createdTime
+	updatedAt: Long @updatedTime
+
+	"""
+	Internal — do not surface to external consumers.
+	"""
+	creditScore: Int @hidden
+}
+```
+
+**Multiple `@table` argument combinations:**
+
+```graphql
+# Override table name
+type Product @table(table: "products") {
+	id: Long @primaryKey
+}
+
+# Place in a specific database
+type Order @table(database: "commerce") {
+	id: Long @primaryKey
+}
+
+# Auto-expire records after 1 hour
+type Session @table(expiration: 3600) {
+	id: Long @primaryKey
+	userId: String
+}
+
+# Disable replication
+type LocalRecord @table(replicate: false) {
+	id: Long @primaryKey
+	value: String
+}
+
+# Combine multiple arguments
+type Event @table(database: "analytics", expiration: 86400) {
+	id: Long @primaryKey
+	name: String @indexed
+}
+```
+
+#### Notes
+
+- All tables default to the `"data"` database. When designing plugins or applications, use unique database names to avoid table naming collisions.
+- Schemas are flexible by default — records may include properties beyond those declared. Use `@sealed` to prevent this.
+- `expiration` marks a record stale; `eviction` controls how long after expiration the record is physically removed. Eviction does not remove records from secondary indexes — Harper fetches the full record on demand if an evicted record matches a query.
+- `scanInterval` is clock-aligned to the server's local timezone, not startup-aligned. The eviction schedule is deterministic across restarts.
+- If replication is disabled on a table and later re-enabled, writes made during the disabled period are not replicated retroactively.
+- `@hidden` (on types or fields) is a metadata-visibility directive only. Use `attribute_permissions` on roles to enforce data access control.
+- Disabling replication (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.
+
+### 1.3 Defining Relationships Between Tables in Harper
+
+Instructions for the agent to follow when defining and querying relationships between tables in Harper using the `@relationship` directive.
+
+#### When to Use
+
+Apply this rule whenever a schema requires linking two tables via a foreign key — for example, modeling shows and networks, products and brands, or orders and items. Use it when queries need to filter or select nested related records using dot-syntax.
+
+#### How It Works
+
+1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on a field in the current table when the foreign key lives in this table and references the primary key of the target table.
 
    ```graphql
-   type Product @table {
+   type RealityShow @table @export {
    	id: Long @primaryKey
-   	category: String @indexed
-   	price: Float @indexed
+   	networkId: Long @indexed
+   	network: Network @relationship(from: networkId)
+   	title: String @indexed
+   }
+
+   type Network @table @export {
+   	id: Long @primaryKey
+   	name: String @indexed
    }
    ```
 
-6. **Expose a table as an external resource endpoint** with `@export`. This makes the table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment; without it, the type name is used.
+   For a many-to-many relationship, make the foreign key an array:
 
    ```graphql
-   type MyTable @table @export(name: "my-table") {
+   type RealityShow @table @export {
    	id: Long @primaryKey
+   	networkIds: [Long] @indexed
+   	networks: [Network] @relationship(from: networkIds)
    }
    ```
 
-7. **Restrict extra properties** with `@sealed` when records must not include attributes beyond those declared. By default, Harper allows additional properties.
+2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on a field in the current table when the foreign key lives in the target table and references the primary key of this table. The result type must be an array.
 
    ```graphql
-   type StrictRecord @table @sealed {
+   type Network @table @export {
+   	id: Long @primaryKey
+   	name: String @indexed
+   	shows: [RealityShow] @relationship(to: networkId)
+   }
+   ```
+
+3. **Use `@relationship(from: attribute, to: attribute)` for foreign key to foreign key joins**: Specify both `from` and `to` when neither side uses the primary key. This is useful for joining on non-primary-key attributes.
+
+   ```graphql
+   type OrderItem @table @export {
    	id: Long @primaryKey
+   	orderId: Long @indexed
+   	productSku: Long @indexed
+   	product: Product @relationship(from: productSku, to: sku)
+   }
+
+   type Product @table @export {
+   	id: Long @primaryKey
+   	sku: Long @indexed
    	name: String
    }
    ```
 
-8. **Configure expiration, eviction, and scan behavior** together when building caching tables. These three arguments control the full record lifecycle:
-   - `expiration` — record becomes stale; next request triggers a source fetch
-   - `eviction` — additional time after `expiration` before physical removal
-   - `scanInterval` — how often Harper scans for records to evict; clock-aligned, not startup-aligned
+4. **Query across relationships using dot-syntax**: Filter by related table attributes using chained dot notation. This behaves as an INNER JOIN.
+
+   ```
+   GET /RealityShow?network.name=Bravo
+   GET /Product/?brand.name=Microsoft
+   GET /Brand/?products.name=Keyboard
+   ```
+
+5. **Select nested relationship fields with `select()`**: Relationship attributes are not included by default. Use `select()` to include them in results. When selecting without a filter on the related table, this acts as a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+
+   ```
+   GET /Product/?brand.name=Microsoft&select(name,brand)
+   GET /Product/?brand.name=Microsoft&select(name,brand{name})
+   GET /Product/?name=Keyboard&select(name,brand{name,id})
+   ```
 
 #### Examples
 
-**Caching table with tuned expiration:**
+**Many-to-one relationship** — a show belongs to a network:
 
 ```graphql
-# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
-type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
-	id: ID @primaryKey
-	temperature: Float
+type RealityShow @table @export {
+	id: Long @primaryKey
+	networkId: Long @indexed
+	network: Network @relationship(from: networkId)
+	title: String @indexed
 }
-```
 
-**Table in a named database with expiration and an indexed field:**
-
-```graphql
-type Event @table(database: "analytics", expiration: 86400) {
+type Network @table @export {
 	id: Long @primaryKey
 	name: String @indexed
 }
 ```
 
-**Session cache with auto-expiry:**
+Query:
+
+```
+GET /RealityShow?network.name=Bravo
+```
+
+**One-to-many relationship** — a network has many shows:
 
 ```graphql
-type Session @table(expiration: 3600) {
+type Network @table @export {
 	id: Long @primaryKey
-	userId: String
+	name: String @indexed
+	shows: [RealityShow] @relationship(to: networkId)
 }
 ```
 
-**Table with audit timestamps:**
+**Many-to-many with array foreign keys** — a product has multiple resellers:
 
 ```graphql
-type Order @table @export(name: "orders") {
+type Product @table @export {
 	id: Long @primaryKey
-	createdAt: Long @createdTime
-	updatedAt: Long @updatedTime
-	status: String @indexed
+	name: String
+	resellerIds: [Long] @indexed
+	resellers: [Reseller] @relationship(from: resellerIds)
 }
 ```
 
-**Overriding the table name and disabling replication:**
+Query with nested select:
+
+```
+GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+```
+
+**Foreign key to foreign key join** — order item joined on SKU:
 
 ```graphql
-type Product @table(table: "products") {
+type OrderItem @table @export {
 	id: Long @primaryKey
-	name: String
+	orderId: Long @indexed
+	productSku: Long @indexed
+	product: Product @relationship(from: productSku, to: sku)
 }
 
-type LocalRecord @table(replicate: false) {
+type Product @table @export {
 	id: Long @primaryKey
-	value: String
+	sku: Long @indexed
+	name: String
 }
 ```
 
 #### Notes
 
-- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
-- Eviction removes non-indexed record data but does **not** remove a record from its secondary indexes. Indexes remain functional for evicted records; Harper fetches the full record from the source on demand when a query matches an evicted record.
-- `scanInterval` is clock-aligned to the server's local timezone. The server's startup time does not affect when eviction runs.
-- If replication is disabled on a table and later re-enabled, it will not catch up on writes made while replication was disabled.
-- Null values are indexed by `@indexed` fields, enabling queries such as `GET /Product/?category=null`.
-
-### 1.3 Defining Relationships
-
-Instructions for the agent to follow when defining relationships between Harper tables.
-
-#### When to Use
-
-Use this skill when you need to link data across different tables, enabling automatic joins and efficient related-data fetching via REST APIs.
-
-#### How It Works
-
-1. **Identify the Relationship Type**: Determine if it's one-to-one, many-to-one, or one-to-many.
-2. **Use the `@relationship` Directive**: Apply it to a field in your GraphQL schema.
-   - **Many-to-One (Current table holds FK)**: Use `from`.
-     ```graphql
-     type Book @table @export {
-     	authorId: ID
-     	author: Author @relationship(from: "authorId")
-     }
-     ```
-   - **One-to-Many (Related table holds FK)**: Use `to` and an array type.
-     ```graphql
-     type Author @table @export {
-     	books: [Book] @relationship(to: "authorId")
-     }
-     ```
-3. **Query with Relationships**: Use dot syntax in REST API calls for filtering or the `select()` operator for including related data.
-   - Example Filter: `GET /Book/?author.name=Harper`
-   - Example Select: `GET /Author/?select(name,books(title))`
+- The `@relationship` directive requires the referenced attribute to be `@indexed` on the foreign key side.
+- Self-referential relationships are supported, enabling parent-child hierarchies within a single table.
+- The array order of foreign key values (e.g., `resellerIds`) is preserved when resolving many-to-many relationships.
+- When using `select()` without a filter on the related table, the join behaves as a LEFT JOIN — missing or null foreign keys result in the relationship property being omitted rather than causing an error.
 
 ### 1.4 Vector Indexing
 
-Instructions for the agent to follow when enabling and querying vector indexes for similarity search in Harper using the HNSW algorithm.
+Instructions for the agent to enable HNSW vector indexes on table fields and query them for similarity search in Harper.
 
 #### When to Use
 
-Apply this rule when adding a vector index to a Harper table schema or writing similarity search queries against high-dimensional vector fields. Use it whenever you need approximate nearest-neighbor search, distance-threshold filtering, or distance-scored results.
+Apply this rule when adding a vector similarity search capability to a Harper table — for example, storing text embeddings and querying for nearest neighbors, filtering by distance threshold, or tuning index construction and search parameters. Use it alongside [adding-tables-with-schemas.md](adding-tables-with-schemas.md) when defining the schema that hosts the vector field.
 
 #### How It Works
 
-1. **Declare the vector index on a `[Float]` field**: Add `@indexed(type: "HNSW")` to any `[Float]` attribute in a `@table` type. See [adding-tables-with-schemas.md](adding-tables-with-schemas.md) for general schema setup.
+1. **Declare the vector index on a field**: Add `@indexed(type: "HNSW")` to a `[Float]` field inside a `@table` type. This creates an HNSW (Hierarchical Navigable Small World) index for approximate nearest-neighbor search.
 
    ```graphql
    type Document @table {
@@ -235,7 +383,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    }
    ```
 
-2. **Query by nearest neighbors using `sort`**: Call `Document.search()` with a `sort` object containing `attribute` (the indexed field name) and `target` (the query vector). Include `limit` to cap results.
+2. **Query by nearest neighbors using `sort`**: Call `.search()` with a `sort` descriptor that specifies the indexed `attribute` and a `target` vector. Use `limit` to cap results.
 
    ```javascript
    let results = Document.search({
@@ -254,7 +402,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-4. **Filter by distance threshold**: To return only records within a similarity cutoff (without ranking), place `target` directly on the condition alongside `comparator` and `value`. Omit `sort`.
+4. **Filter by distance threshold**: To return only records within a similarity cutoff (without ranking), place `target` directly on the condition alongside `comparator` and `value`. This bounds result quality rather than ranking by similarity.
 
    ```javascript
    let results = Document.search({
@@ -267,7 +415,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-5. **Include computed distance in results**: Use the special `$distance` field in `select` to return the distance from the target vector. Works with both `sort`-based and `conditions`-based queries.
+5. **Include computed distance in results**: Use the special `$distance` field in `select` to return the distance from the target vector. Available in both `sort`-based and threshold-based queries.
 
    ```javascript
    let results = Document.search({
@@ -277,43 +425,59 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-6. **Tune HNSW parameters**: Pass additional parameters to `@indexed(type: "HNSW", ...)` to control index quality and performance.
+6. **Tune per-query search options**: Pass `distance` and `ef` directly on the `sort` descriptor to override index defaults for a single query.
+
+   ```javascript
+   let results = Document.search({
+   	sort: { attribute: 'textEmbeddings', target: searchVector, distance: 'dotProduct', ef: 200 },
+   	limit: 5,
+   });
+   ```
+
+   - `distance` — overrides the distance function for this query: `"cosine"`, `"euclidean"`, or `"dotProduct"`.
+   - `ef` — overrides the search exploration budget. Higher values improve recall at the cost of latency.
 
-   | Parameter              | Default           | Description                                                                                         |
-   | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
-   | `distance`             | `"cosine"`        | Distance function: `"euclidean"` or `"cosine"` (negative cosine similarity)                         |
-   | `efConstruction`       | `100`             | Max nodes explored during index construction. Higher = better recall, lower = better performance    |
-   | `M`                    | `16`              | Preferred connections per graph layer. Higher = more space, better recall for high-dimensional data |
-   | `optimizeRouting`      | `0.5`             | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive)          |
-   | `mL`                   | computed from `M` | Normalization factor for level generation                                                           |
-   | `efSearchConstruction` | `50`              | Max nodes explored during search                                                                    |
+7. **Configure HNSW index parameters**: Pass parameters directly in the `@indexed` directive. Structural parameters (`distance`, `M`, `efConstruction`, `quantization`) trigger an index rebuild when changed; `efConstructionSearch` does not.
+
+   ```graphql
+   type Document @table {
+   	id: Long @primaryKey
+   	textEmbeddings: [Float]
+   		@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
+   }
+   ```
+
+8. **Enable vector quantization**: Use `quantization: "int8"` to store vectors as 8-bit integers, reducing index size and memory usage. Harper re-ranks nearest-neighbor `sort` results against full-precision vectors automatically.
+
+   ```graphql
+   type Document @table {
+   	id: Long @primaryKey
+   	textEmbeddings: [Float] @indexed(type: "HNSW", quantization: "int8")
+   }
+   ```
 
 #### Examples
 
-**Schema with custom HNSW parameters:**
+Full schema with custom HNSW parameters and a nearest-neighbor query with distance output:
 
 ```graphql
 type Document @table {
 	id: Long @primaryKey
 	textEmbeddings: [Float]
-		@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efSearchConstruction: 100)
+		@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
 }
 ```
 
-**Nearest-neighbor search with distance score:**
-
 ```javascript
+// Nearest-neighbor search with distance scores
 let results = Document.search({
 	select: ['name', '$distance'],
 	sort: { attribute: 'textEmbeddings', target: searchVector },
 	limit: 5,
 });
-```
 
-**Distance-threshold filter (no ranking):**
-
-```javascript
-let results = Document.search({
+// Distance-threshold query (no ranking)
+let closeMatches = Document.search({
 	conditions: {
 		attribute: 'textEmbeddings',
 		comparator: 'lt',
@@ -325,81 +489,242 @@ let results = Document.search({
 
 #### Notes
 
-- The default `distance` function is `cosine`. Pass `distance: "euclidean"` to switch.
-- `efConstruction` controls index build quality; raising it improves recall at the cost of build time.
+##### HNSW Parameters
+
+| Parameter              | Default           | Description                                                                                            |
+| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `distance`             | `"cosine"`        | Distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"`                                        |
+| `efConstruction`       | `100`             | Max nodes explored during index construction. Higher = better recall, lower = better performance       |
+| `M`                    | `16`              | Preferred connections per graph layer. Higher = more space, better recall for high-dimensional data    |
+| `optimizeRouting`      | `0.5`             | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive)             |
+| `mL`                   | computed from `M` | Normalization factor for level generation                                                              |
+| `efConstructionSearch` | auto-scaled       | Max nodes explored during search. When unset, auto-scales with index size; setting it fixes the budget |
+| `quantization`         | —                 | `"int8"` stores vectors quantized to int8                                                              |
+
+- The `distance` option on a per-query `sort` descriptor accepts `"cosine"`, `"euclidean"`, or `"dotProduct"`.
+- When no `ef` is passed and `efConstructionSearch` (or `efConstruction`) is not explicitly set on the index, the search budget auto-scales with index size.
+- `efConstruction` seeds the initial value of `efConstructionSearch`; setting either one fixes the search budget.
+- The correct parameter name is `efConstructionSearch` (not `efSearchConstruction`).
 - `$distance` is available in both `sort`-based ranking and `conditions`-based threshold queries.
-- Use the threshold (`conditions` + `target`) form when you want to bound result quality by a similarity cutoff rather than ranking by similarity.
+- For `quantization: "int8"`, distance-threshold (`lt`/`le`) queries filter on approximate distance; `sort` queries re-rank against full-precision vectors.
 
-### 1.5 Using Blob Datatype
+### 1.5 Using the Blob Data Type
 
-Instructions for the agent to follow when working with the Blob data type in Harper.
+Instructions for the agent to follow when storing and retrieving large binary content using Harper's `Blob` data type.
 
 #### When to Use
 
-Use this skill when you need to store unstructured or large binary data (media, documents) that is too large for standard JSON fields. Blobs provide efficient storage and integrated streaming support.
+Apply this rule when a schema field needs to store large binary content such as images, video, audio, or large HTML — typically content larger than 20KB. Use `Blob` instead of `Bytes` when you need streaming support or want to avoid loading the entire value into memory. See [handling-binary-data.md](handling-binary-data.md) for broader binary data guidance.
 
 #### How It Works
 
-1. **Define Blob Fields**: In your GraphQL schema, use the `Blob` type:
+1. **Declare a `Blob` field in your schema**: Add a field typed as `Blob` to a `@table` type.
+
    ```graphql
    type MyTable @table {
-   	id: ID @primaryKey
+   	id: Any! @primaryKey
    	data: Blob
    }
    ```
-2. **Create and Store Blobs**: Use `createBlob()` from Harper's globals to wrap Buffers or Streams:
+
+2. **Create a blob with `createBlob()`**: Pass a buffer, string, or stream as the first argument. Pass a `BlobOptions` object as the second argument to configure behavior.
+
+   ```javascript
+   let blob = createBlob(largeBuffer);
+   await MyTable.put({ id: 'my-record', data: blob });
+   ```
+
+3. **Read blob data using standard Web API methods**: The `Blob` type implements the Web API `Blob` interface. Use `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, or `.slice()` to access content.
+
    ```javascript
-   import { tables } from 'harper';
-   const blob = createBlob(largeBuffer);
-   await tables.MyTable.put('my-id', { data: blob });
+   let record = await MyTable.get('my-record');
+   let buffer = await record.data.bytes(); // ArrayBuffer
+   let text = await record.data.text(); // string
+   let stream = record.data.stream(); // ReadableStream
    ```
-3. **Use Streaming (Optional)**: For very large files, pass a stream to `createBlob()` to avoid loading the entire file into memory.
-4. **Read Blob Data**: Retrieve the record and use `.bytes()` or streaming interfaces on the blob field:
+
+4. **Use `saveBeforeCommit` for ACID-compliant writes**: By default, blobs are not ACID-compliant — a record can reference a blob before it is fully written. Set `saveBeforeCommit: true` to wait for the full write before the transaction commits.
+
    ```javascript
-   const record = await tables.MyTable.get('my-id');
-   const buffer = await record.data.bytes();
+   let blob = createBlob(stream, { saveBeforeCommit: true });
+   await MyTable.put({ id: 'my-record', data: blob });
+   // put() resolves only after blob is fully written and record is committed
    ```
-5. **Ensure Write Completion**: Use `saveBeforeCommit: true` in `createBlob` options if you need the blob fully written before the record is committed.
-6. **Handle Errors**: Attach error listeners to the blob object to handle streaming failures.
+
+5. **Register an error handler when returning a blob via REST**: Interrupted streams must be handled explicitly to avoid stale records.
+
+   ```javascript
+   export class MyEndpoint extends MyTable {
+   	static async get(target) {
+   		const record = super.get(target);
+   		let blob = record.data;
+   		blob.on('error', () => {
+   			MyTable.invalidate(target);
+   		});
+   		return { status: 200, headers: {}, body: blob };
+   	}
+   }
+   ```
+
+6. **Rely on automatic coercion where applicable**: When a field is typed as `Blob` in the schema, any string or buffer assigned via `put`, `patch`, or `publish` is automatically coerced to a `Blob`. Manual `createBlob()` calls are not required for plain JSON HTTP bodies or MQTT messages in most cases.
+
+##### `BlobOptions` Reference
+
+| Option             | Type      | Default     | Description                                                                                                              |
+| ------------------ | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `type`             | `string`  | `undefined` | MIME type to associate with the blob (e.g., `image/jpeg`). Readable via `blob.type` and used when serving HTTP.          |
+| `size`             | `number`  | `undefined` | Size of the data in bytes, if known ahead of time. Otherwise inferred from a buffer or determined as a stream completes. |
+| `saveBeforeCommit` | `boolean` | `false`     | Wait for the blob to be fully written before committing the transaction.                                                 |
+| `compress`         | `boolean` | `false`     | Compress the stored data with deflate.                                                                                   |
+| `flush`            | `boolean` | `false`     | Flush the file to disk after writing, before the `createBlob` promise chain resolves.                                    |
+
+#### Examples
+
+**Store an image with a MIME type:**
+
+```javascript
+let blob = createBlob(imageBuffer, { type: 'image/jpeg' });
+await Photo.put({ id, data: blob });
+```
+
+**Stream large media with low latency:**
+
+```javascript
+let blob = createBlob(incomingStream);
+// blob exists, but data is still streaming to storage
+await MyTable.put({ id: 'my-record', data: blob });
+
+let record = await MyTable.get('my-record');
+// blob data is accessible as it arrives
+let outgoingStream = record.data.stream();
+```
+
+**Guaranteed write before commit:**
+
+```javascript
+let blob = createBlob(stream, { saveBeforeCommit: true });
+await MyTable.put({ id: 'my-record', data: blob });
+```
+
+#### Notes
+
+- `Blob` stores data separately from the record; `Bytes` does not. Prefer `Blob` for content larger than 20KB.
+- All standard Web API `Blob` methods are available: `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, `.slice()`.
+- Blobs are **not** ACID-compliant by default when created from a stream. Use `saveBeforeCommit: true` to enforce transactional consistency.
+- Always attach an `error` handler on blobs returned as HTTP response bodies to handle interrupted streams.
 
 ### 1.6 Handling Binary Data
 
-Instructions for the agent to follow when handling binary data in Harper.
+Instructions for the agent to follow when storing and serving binary data (images, audio, arbitrary content types) in Harper.
 
 #### When to Use
 
-Use this skill when you need to store binary files (images, audio, etc.) in the database or serve them back to clients via REST endpoints.
+Apply this rule when a Harper resource needs to accept, store, or serve binary payloads such as images, audio files, or calendar data. Use it when REST clients send `base64`-encoded data inside JSON, when raw binary is uploaded via `PUT`/`POST`, or when a resource must stream binary back to the client with the correct `Content-Type`.
 
 #### How It Works
 
-1. **Store Binary Data**: In your resource's `post` or `put` method, convert incoming data to Buffers and then to Blobs using `createBlob` from Harper's globals. Include the MIME type if available:
+1. **Accept base64-encoded binary from JSON clients**: Decode the incoming `base64` string with `Buffer.from` and wrap it using `createBlob`, recording the MIME type. Override `post` in your resource class:
 
    ```typescript
-   async post(target, record) {
-     if (record.data) {
-       record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
-         type: record.contentType || 'application/octet-stream',
-       });
-     }
-     return super.post(target, record);
+   import { type RequestTargetOrId, tables, createBlob } from 'harper';
+
+   export class Photo extends tables.Photo {
+   	static async post(target: RequestTargetOrId, record: any) {
+   		if (record.data) {
+   			record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
+   				type: record.contentType || 'application/octet-stream',
+   			});
+   		}
+   		return super.post(target, record);
+   	}
    }
    ```
 
-2. **Serve Binary Data**: In your resource's `get` method, return a response object with the appropriate `Content-Type` and the binary data in the `body`:
+2. **Serve binary from a resource**: Override `get` to return a response object with the blob's MIME type in the `Content-Type` header and the blob as the body. Harper streams it to the client:
+
    ```typescript
-   async get(target) {
-    const record = await super.get(target);
-    if (record?.data) {
-      return {
-        status: 200,
-        headers: { 'Content-Type': record.data.type || 'application/octet-stream' },
-        body: record.data,
-      };
-    }
-    return record;
+   export class Photo extends tables.Photo {
+   	static async get(target: RequestTargetOrId) {
+   		const record = await super.get(target);
+   		if (record?.data) {
+   			return {
+   				status: 200,
+   				headers: { 'Content-Type': record.data.type || 'application/octet-stream' },
+   				body: record.data,
+   			};
+   		}
+   		return record;
+   	}
    }
    ```
-3. **Use the Blob Type**: Ensure your GraphQL schema uses the `Blob` scalar for binary fields.
+
+3. **Upload raw binary with a non-standard content type**: Make a `PUT` or `POST` with any non-standard `Content-Type` header. Harper automatically stores the body as a record with `contentType` and `data` properties:
+
+   ```http
+   PUT /my-resource/33
+   Content-Type: text/calendar
+
+   BEGIN:VCALENDAR
+   VERSION:2.0
+   ...
+   ```
+
+   Harper stores this as:
+
+   ```json
+   { "contentType": "text/calendar", "data": "BEGIN:VCALENDAR\nVERSION:2.0\n..." }
+   ```
+
+   Retrieving that record returns the response with the stored `Content-Type` and body. If the content type is not from the `text` family, the data is treated as binary (a Node.js `Buffer`).
+
+4. **Upload binary to a specific property**: Use `application/octet-stream` (or any image/binary MIME type) and target a sub-path to store binary directly on a property:
+
+   ```http
+   PUT /my-resource/33/image
+   Content-Type: image/gif
+
+   ...image data...
+   ```
+
+#### Examples
+
+**End-to-end: accept base64 JSON, store as blob, serve as binary**
+
+```typescript
+import { type RequestTargetOrId, tables, createBlob } from 'harper';
+
+export class Photo extends tables.Photo {
+	// Accept base64-encoded uploads in JSON
+	static async post(target: RequestTargetOrId, record: any) {
+		if (record.data) {
+			record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {
+				type: record.contentType || 'application/octet-stream',
+			});
+		}
+		return super.post(target, record);
+	}
+
+	// Stream the blob back with the correct Content-Type
+	static async get(target: RequestTargetOrId) {
+		const record = await super.get(target);
+		if (record?.data) {
+			return {
+				status: 200,
+				headers: { 'Content-Type': record.data.type || 'application/octet-stream' },
+				body: record.data,
+			};
+		}
+		return record;
+	}
+}
+```
+
+#### Notes
+
+- `createBlob` takes a `Buffer` as its first argument and an options object with a `type` property for the MIME type. See [using-blob-datatype.md](using-blob-datatype.md) for full details on the blob data type.
+- Always fall back to `application/octet-stream` when no MIME type is known, both when creating and when serving blobs.
+- When Harper retrieves a record that has both `contentType` and `data` properties, it automatically sets the response `Content-Type` and body — no custom `get` override is required for that case unless you need additional logic.
+- Non-`text` content types cause `data` to be stored and returned as a Node.js `Buffer`.
 
 ## 2. API & Communication
 
@@ -1021,81 +1346,222 @@ export class RefreshJWT extends Resource {
 
 ### 3.1 Custom Resources
 
-Instructions for the agent to follow when creating custom resources in Harper.
+Instructions for the agent to follow when defining custom REST endpoints with JavaScript or TypeScript in Harper.
 
 #### When to Use
 
-Use this skill when the automatic CRUD operations provided by `@table @export` are insufficient, and you need custom logic, third-party API integration, or specialized data handling for your REST endpoints.
+Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering programmatic routes in a Harper application. Use it any time business logic needs to live outside a standard table-backed resource.
 
 #### How It Works
 
-1. **Check if a Custom Resource is Necessary**: Verify if [Automatic APIs](./automatic-apis.md) or [Extending Tables](./extending-tables.md) can satisfy the requirement first.
-2. **Create the Resource File**: Create a `.ts` or `.js` file in the directory specified by `jsResource` in `config.yaml` (typically `resources/`).
-3. **Define the Resource Class**: Export a class extending `Resource` from `harper` and define **static** methods for the HTTP verbs you handle. In Harper 5 the static methods are the HTTP handlers (mapped 1:1 to verbs); they receive a pre-parsed `RequestTarget`, and write handlers also receive the request body as an awaitable `data` argument:
+1. **Import `Resource` from the `harper` package**: Always import explicitly rather than relying on globals.
 
-   ```typescript
-   import { Resource } from 'harper';
+   ```javascript
+   import { tables, Resource } from 'harper';
+   ```
+
+2. **Define a class that `extends Resource`**: Use `export class` so Harper can expose it as an endpoint. Implement HTTP methods as `static` methods on the class.
 
-   export class MyResource extends Resource {
-   	// v5 handlers are static and map 1:1 to HTTP verbs.
-   	static async get(target: any) {
-   		return { message: 'Hello from custom GET!' };
+   ```javascript
+   export class CustomEndpoint extends Resource {
+   	static get(target) {
+   		return {
+   			data: doSomething(),
+   		};
    	}
    }
    ```
 
-4. **Implement HTTP Methods**: Add static methods (`get`, `post`, `put`, `patch`, or `delete`) to handle the corresponding requests. Read/delete handlers receive `(target)`; write handlers receive `(target, data)` where `data` is awaitable.
-5. **Route Nesting and Naming**: You can control the URL structure by how you export your resources:
-   - **Direct Class Export**: `export class Foo extends Resource` creates endpoints at `/Foo/`. Class names are case-sensitive in the URL.
-   - **Nested Objects**: `export const Bar = { Foo };` creates endpoints at `/Bar/Foo/`.
-   - **Lowercase and Hyphens**: Use object keys to define custom paths: `export const bar = { 'foo-baz': Foo };` exposes endpoints at `/bar/foo-baz/`.
-6. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:
-   ```typescript
-   import { tables } from 'harper';
-   // ... inside a method
-   const results = await tables.MyTable.list();
+3. **Add async `static` methods for each HTTP verb you need**: Methods receive `target` (contains `target.id`, etc.) and, for write operations, `data`.
+
+   ```javascript
+   export class MyExternalData extends Resource {
+   	static async get(target) {
+   		const response = await fetch(`https://api.example.com/${target.id}`);
+   		return response.json();
+   	}
+
+   	static async put(target, data) {
+   		return fetch(`https://api.example.com/${target.id}`, {
+   			method: 'PUT',
+   			body: JSON.stringify(await data),
+   		});
+   	}
+   }
+   ```
+
+4. **Control the URL by choosing the export form**: The shape of the export determines the resulting URL path. Path matching is case-sensitive.
+
+   | Export form                              | URL             | Notes                                                           |
+   | ---------------------------------------- | --------------- | --------------------------------------------------------------- |
+   | `export class Foo extends Resource {}`   | `/Foo/`         | Class name becomes the path segment.                            |
+   | `export const Bar = { Foo };`            | `/Bar/Foo/`     | Nest under an object to add a path prefix.                      |
+   | `export const bar = { 'foo-baz': Foo };` | `/bar/foo-baz/` | Use object keys for lowercase, hyphens, or non-identifier URLs. |
+   | `server.resources.set('my-path', Foo);`  | `/my-path/`     | Programmatic registration; useful when the path is dynamic.     |
+
+5. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the class.
+
+   ```javascript
+   server.resources.set('my-path', Foo);
    ```
-7. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).
+
+6. **Optionally use the resource as a cache source for a local table**: Pass the class to `sourcedFrom`.
+   ```javascript
+   tables.MyCache.sourcedFrom(MyExternalData);
+   ```
+
+#### Examples
+
+Wrap an external API and expose it as an endpoint, then back a local cache table with it:
+
+```javascript
+import { tables, Resource } from 'harper';
+
+export class MyExternalData extends Resource {
+	static async get(target) {
+		const response = await fetch(`https://api.example.com/${target.id}`);
+		return response.json();
+	}
+
+	static async put(target, data) {
+		return fetch(`https://api.example.com/${target.id}`, {
+			method: 'PUT',
+			body: JSON.stringify(await data),
+		});
+	}
+}
+
+// Use as a cache source for a local table
+tables.MyCache.sourcedFrom(MyExternalData);
+```
+
+Programmatic registration with a custom path:
+
+```javascript
+import { Resource } from 'harper';
+
+export class CustomEndpoint extends Resource {
+	static get(target) {
+		return {
+			data: doSomething(),
+		};
+	}
+}
+
+server.resources.set('my-path', CustomEndpoint);
+```
+
+#### Notes
+
+- `export class` directly produces a URL from the class name (e.g., `export class Foo extends Resource {}` → `/Foo/`). Do not export the same resource from both a schema file and a JavaScript file — this creates conflicting exports.
+- URL path segments are case-sensitive: `/Foo/` and `/foo/` are different endpoints.
+- For CommonJS modules, use `const { tables, Resource } = require('harper');` instead of the ESM import.
+- When developing a component in its own directory, run `npm link harper` to ensure typings match your installed version. All installed components have `harper` automatically linked.
+- The `static` keyword is required on all HTTP verb methods — Harper dispatches requests through static class methods, not instance methods.
 
 ### 3.2 Extending Tables
 
-Instructions for the agent to follow when extending table resources in Harper.
+Instructions for the agent to follow when adding custom logic to automatically generated table resources in Harper.
 
 #### When to Use
 
-Use this skill when you need to add custom validation, side effects (like webhooks), data transformation, or custom access control to the standard CRUD operations of a Harper table.
+Apply this rule when you need to add computed properties, intercept writes, enforce validation, or otherwise customize the behavior of a Harper table resource beyond what the default generated endpoints provide. Use it any time a `@table` type needs server-side logic attached to its REST handlers.
 
 #### How It Works
 
-1. **Define the Table in GraphQL**: In your `.graphql` schema, define the table using the `@table` directive. **Do not** use `@export` if you plan to extend it.
+1. **Define the schema without `@export`**: Declare the table type in `schema.graphql` and omit the `@export` directive. Leaving `@export` on the schema while also exporting a subclass with the same name produces conflicting endpoints. Let the JavaScript class own the URL instead.
+
    ```graphql
+   # Omit the `@export` directive
    type MyTable @table {
-   	id: ID @primaryKey
-   	name: String
+   	id: Long @primaryKey
+   	# ...
    }
    ```
-2. **Create the Extension File**: Create a `.ts` file in your `resources/` directory.
-3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName` and override the relevant **static** methods. In Harper 5 resource handlers are static and map 1:1 to HTTP verbs: `get(target)`, `post(target, data)`, `put(target, data)`, `patch(target, data)`, `delete(target)`. `target` is a pre-parsed `RequestTarget`; for writes, `data` is the request body and is **awaitable** (`await data`). Delegate to `super` to keep Harper's default behavior — a collection create passes just the record (`super.post(record)`), updates pass the target (`super.put(target, data)` / `super.patch(target, data)`), and reads/deletes pass the target (`super.get(target)`). To return a specific HTTP status from a thrown error, set **`.statusCode`** (e.g. `400`) on the error — a plain `.status` property is ignored.
 
-   ```typescript
-   import { tables } from 'harper';
+2. **Extend the generated table class**: In `resources.js`, extend from the `tables.<TypeName>` global. The class name you export becomes the URL path. The exported class extends tables.
 
+   ```javascript
    export class MyTable extends tables.MyTable {
-   	// Static handler; receives (target, data) — data is awaitable.
-   	static async post(target: any, data: any) {
-   		const record = await data;
-   		if (!record?.name) {
-   			const error: any = new Error('Name is required');
-   			error.statusCode = 400; // HTTP status (use statusCode, NOT status)
-   			throw error;
-   		}
-   		return super.post(record); // create delegates with the record (no id)
+   	static async get(target) {
+   		const record = await super.get(target);
+   		return { ...record, computedField: 'value' };
+   	}
+
+   	static async post(target, data) {
+   		this.create({ ...(await data), status: 'pending' });
    	}
    }
    ```
 
-4. **Override Methods**: Override the static `get`, `post`, `put`, `patch`, or `delete` as needed, delegating to `super.<method>` (see the argument forms above) to preserve Harper's default behavior unless you intend to replace it entirely.
-5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations.
+3. **Call `super` to preserve default behavior**: When delegating to `super`, match the argument form to the operation:
+   - Reads/deletes: `super.get(target)` / `super.delete(target)`
+   - Collection create: `super.post(target, record)` — target carries no id
+   - Updates: `super.put(target, data)` / `super.patch(target, data)`
+
+   Omit the `super` call only if you intend to replace the default behavior entirely.
+
+4. **Set `statusCode` on thrown errors to control HTTP responses**: Uncaught errors are caught by the protocol handler and produce error responses for REST. Use `.statusCode` — a plain `.status` property is ignored.
+
+   ```javascript
+   const error = new Error('Name is required');
+   error.statusCode = 400; // use statusCode, NOT status
+   throw error;
+   ```
+
+5. **Configure Harper to load both files**: Ensure your configuration references the schema and resource files.
+
+   ```yaml
+   rest: true
+   graphqlSchema:
+     files: schema.graphql
+   jsResource:
+     files: resources.js
+   ```
+
+#### Examples
+
+Full end-to-end example — schema, resource class, and error handling:
+
+```graphql
+# schema.graphql — omit @export so the JS class owns the endpoint
+type MyTable @table {
+	id: Long @primaryKey
+}
+```
+
+```javascript
+// resources.js
+export class MyTable extends tables.MyTable {
+	static async get(target) {
+		// get the record from the database
+		const record = await super.get(target);
+		// add a computed property before returning
+		return { ...record, computedField: 'value' };
+	}
+
+	static async post(target, data) {
+		// custom action on POST
+		this.create({ ...(await data), status: 'pending' });
+	}
+}
+```
+
+Throwing a controlled HTTP error:
+
+```javascript
+if (!authorized) {
+	const error = new Error('Forbidden');
+	error.statusCode = 403;
+	throw error;
+}
+```
+
+#### Notes
+
+- Always omit `@export` from the schema type when a JavaScript subclass is exporting the same name. The two registrations conflict.
+- `super` must be called with the correct arguments for each operation type — mismatched arguments will not behave as expected.
+- `statusCode` is the only recognized property for controlling HTTP status on thrown errors; `.status` is ignored.
 
 ### 3.3 Programmatic Table Requests
 
@@ -1166,13 +1632,13 @@ Use these exact strings — incorrect comparator names will silently fail or err
 
 ##### Query Object Parameters
 
-| Property     | Description                                                                          |
-| ------------ | ------------------------------------------------------------------------------------ |
-| `conditions` | Array of condition objects                                                           |
-| `limit`      | Maximum number of records to return                                                  |
-| `offset`     | Number of records to skip (for pagination)                                           |
-| `select`     | Array of attribute names to return; supports `$id` and `$updatedtime`                |
-| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort |
+| Property     | Description                                                                                                                                                                                                     |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conditions` | Array of condition objects                                                                                                                                                                                      |
+| `limit`      | Maximum number of records to return                                                                                                                                                                             |
+| `offset`     | Number of records to skip (for pagination)                                                                                                                                                                      |
+| `select`     | Array of fields to return: attribute names (supports `$id` and `$updatedtime`), or an object `{ name, select }` to include fields from a related record — see [Selecting Related Data](#selecting-related-data) |
+| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort                                                                                                                            |
 
 ##### Examples
 
@@ -1221,6 +1687,50 @@ for await (const record of tables.Product.search({
 })) { ... }
 ```
 
+#### Selecting Related Data
+
+When a field is defined as a relationship (via `@relationship` — see [Defining Relationships](defining-relationships.md)), `select` can pull the related record(s) into your results as nested properties. This is the programmatic equivalent of the REST `select(name,author{name})` syntax (see [Querying REST APIs](querying-rest-apis.md)).
+
+**Whole related record** — list the relationship field by name. The related record (or an array of records for a to-many relationship) is attached as a nested property:
+
+```javascript
+for await (const book of tables.Book.search({
+	conditions: [{ attribute: 'id', value: 42 }],
+	select: ['id', 'title', 'author'], // `author` is a relationship field
+})) {
+	console.log(book.author.name); // the full related Author record
+}
+```
+
+**Partial related record** — use an object `{ name, select }` to choose which fields of the related record to return. Unselected fields are omitted:
+
+```javascript
+for await (const book of tables.Book.search({
+	conditions: [{ attribute: ['author', 'name'], comparator: 'equals', value: 'Harper' }],
+	select: ['id', 'title', { name: 'author', select: ['name'] }],
+})) {
+	// book.author.name is present; other Author fields are undefined
+}
+```
+
+**Nesting** — a `select` inside an object entry may itself contain more `{ name, select }` objects, traversing multiple relationships in one query:
+
+```javascript
+select: [
+  'id',
+  'name',
+  {
+    name: 'segments',
+    select: ['id', 'name', { name: 'client', select: ['id', 'name'] }],
+  },
+],
+```
+
+Notes:
+
+- A to-many relationship resolves to an array of records; depending on access pattern you may need to `await` the property before iterating it.
+- Selecting a relationship without filtering on it produces LEFT JOIN behavior (records with no related row are still returned); adding a condition on a related attribute (e.g. `attribute: ['author', 'name']`) produces INNER JOIN behavior.
+
 #### Cautions
 
 Be very careful when performing updates and deletions! You may be dealing with live production data. The wrong request to delete, without approval from a human, could be devastating to a business. Always use the proper approval process.
@@ -1281,15 +1791,15 @@ jsResource:
 
 ### 3.5 Caching External Data Sources in Harper
 
-Instructions for the agent to implement integrated data caching in Harper by wrapping external sources with a cache table and `sourcedFrom`.
+Instructions for the agent to implement integrated data caching from external sources using Harper's cache table directives and `sourcedFrom` API.
 
 #### When to Use
 
-Apply this rule when a Harper application needs to cache responses from an external API, microservice, or database to avoid repeated slow or expensive upstream calls. Use it whenever you need to define TTL-based cache expiration, observe ETag-based conditional responses, or manually invalidate cached entries.
+Apply this rule when an application needs to wrap an external API, microservice, or database with a fast local cache. Use it when you need to define TTL-based cache expiration, connect an upstream data source to a Harper table, or implement on-demand cache invalidation.
 
 #### How It Works
 
-1. **Define a cache table with `expiration`**: In `schema.graphql`, add the `expiration` argument to `@table`. The value is in seconds. Any record older than this threshold is considered stale and will be re-fetched on next access.
+1. **Define a cache table with `expiration`**: Add the `expiration` argument to the `@table` directive in `schema.graphql`. The value is in seconds. When a record becomes stale, the next request fetches a fresh copy from the upstream source.
 
    ```graphql
    type JokeCache @table(expiration: 60) @export {
@@ -1299,7 +1809,7 @@ Apply this rule when a Harper application needs to cache responses from an exter
    }
    ```
 
-2. **Wrap the external source in `resources.js`**: Create an object with a `get(id)` method that fetches from the upstream source. Then call `sourcedFrom` on the table to register it.
+2. **Implement an upstream source object**: In `resources.js`, create an object with a `get(id)` method that fetches data from the external API.
 
    ```javascript
    const jokeAPI = {
@@ -1308,18 +1818,22 @@ Apply this rule when a Harper application needs to cache responses from an exter
    		return response.json();
    	},
    };
+   ```
+
+3. **Connect the source with `sourcedFrom`**: Call `sourcedFrom` on the table to register the upstream source. Harper will call `jokeAPI.get()` automatically when a record is missing or stale.
 
+   ```javascript
    tables.JokeCache.sourcedFrom(jokeAPI);
    ```
 
-   Harper's caching behavior after `sourcedFrom` is registered:
-   - A request arrives for `/JokeCache/1`.
-   - Harper checks if the record with id `1` exists in `JokeCache` and is not stale.
+   Harper's request flow after `sourcedFrom` is registered:
+   - Request arrives for `/JokeCache/1`.
+   - Harper checks if the record exists and is not stale.
    - If fresh, Harper returns it immediately.
    - If missing or stale, Harper calls `jokeAPI.get()`, stores the result in `JokeCache`, and returns it.
    - Multiple simultaneous requests for the same missing or stale record wait on a single upstream call — Harper prevents cache stampedes automatically.
 
-3. **Configure plugins in `config.yaml`**: Enable the schema, REST API, and JS resource plugins.
+4. **Configure plugins in `config.yaml`**: Enable `graphqlSchema`, `rest`, and `jsResource`.
 
    ```yaml
    graphqlSchema:
@@ -1329,29 +1843,7 @@ Apply this rule when a Harper application needs to cache responses from an exter
      files: 'resources.js'
    ```
 
-4. **Observe caching via ETags**: Harper automatically computes an ETag from the record's last-modified timestamp. On the first request you receive a `200` with an `etag` header. Pass that value back in `If-None-Match` on subsequent requests; Harper returns `304 Not Modified` with an empty body if the record is unchanged.
-
-   ```bash
-   curl -i 'http://localhost:9926/JokeCache/1' \
-     -H 'If-None-Match: "abCDefGHij"'
-   ```
-
-5. **Force a cache bypass**: Send `Cache-Control: no-cache` to make Harper skip the local cache and always call the upstream source, regardless of TTL.
-
-   ```bash
-   curl -i 'http://localhost:9926/JokeCache/1' \
-     -H 'Cache-Control: no-cache'
-   ```
-
-6. **Invalidate a cache entry on demand**: Remove `@export` from the schema type, then export a class of the same name in `resources.js` that extends the table and implements a `post` handler calling `this.invalidate(target)`.
-
-   ```graphql
-   type JokeCache @table(expiration: 60) {
-   	id: ID @primaryKey
-   	setup: String
-   	punchline: String
-   }
-   ```
+5. **Implement on-demand invalidation**: To invalidate a cache entry before its TTL expires, export a class extending the table and call `this.invalidate(target)` in a `post` handler. Remove `@export` from the schema when using this pattern — the exported class provides the endpoint.
 
    ```javascript
    export class JokeCache extends tables.JokeCache {
@@ -1365,34 +1857,25 @@ Apply this rule when a Harper application needs to cache responses from an exter
    }
    ```
 
-   Trigger invalidation with a `POST`:
+   Update the schema to remove `@export`:
 
-   ```bash
-   curl -X POST 'http://localhost:9926/JokeCache/1' \
-     -H 'Content-Type: application/json' \
-     -d '{"action": "invalidate"}'
+   ```graphql
+   type JokeCache @table(expiration: 60) {
+   	id: ID @primaryKey
+   	setup: String
+   	punchline: String
+   }
    ```
 
-   The next `GET /JokeCache/1` will fetch fresh data from the upstream source regardless of TTL.
-
 #### Examples
 
-Complete `schema.graphql` and `resources.js` for a cached external API with on-demand invalidation:
-
-```graphql
-type JokeCache @table(expiration: 60) {
-	id: ID @primaryKey
-	setup: String
-	punchline: String
-}
-```
+**Complete `resources.js`**:
 
 ```javascript
 // resources.js
 
 const jokeAPI = {
-	async get() {
-		const id = this.getId();
+	async get(id) {
 		const response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);
 		return response.json();
 	},
@@ -1411,26 +1894,59 @@ export class JokeCache extends tables.JokeCache {
 }
 ```
 
-First request — cache miss, upstream is called, `200` returned:
+**Complete `schema.graphql`**:
 
-```bash
-curl -i 'http://localhost:9926/JokeCache/1'
+```graphql
+type JokeCache @table(expiration: 60) {
+	id: ID @primaryKey
+	setup: String
+	punchline: String
+}
 ```
 
-Second request with ETag — cache hit, `304 Not Modified`:
+**Fetch a cached record**:
 
-```bash
-curl -i 'http://localhost:9926/JokeCache/1' \
-  -H 'If-None-Match: "abCDefGHij"'
+```javascript
+const response = await fetch('http://localhost:9926/JokeCache/1');
+console.log(response.status); // 200
+const etag = response.headers.get('etag'); // e.g. "abCDefGHij"
+const joke = await response.json();
+```
+
+**Use ETag for conditional requests** (returns `304 Not Modified` if unchanged):
+
+```javascript
+const second = await fetch('http://localhost:9926/JokeCache/1', {
+	headers: { 'If-None-Match': etag },
+});
+console.log(second.status); // 304
+```
+
+**Bypass the cache with `Cache-Control: no-cache`**:
+
+```javascript
+const response = await fetch('http://localhost:9926/JokeCache/1', {
+	headers: { 'Cache-Control': 'no-cache' },
+});
+```
+
+**Trigger invalidation via POST**:
+
+```javascript
+await fetch('http://localhost:9926/JokeCache/1', {
+	method: 'POST',
+	headers: { 'Content-Type': 'application/json' },
+	body: JSON.stringify({ action: 'invalidate' }),
+});
 ```
 
 #### Notes
 
 - `expiration` is measured in seconds. Harper also supports separate `eviction` and `scanInterval` arguments on `@table` for fine-grained control over physical record removal.
-- The `@export` directive on the schema type is not required when you export a Resource class of the same name from `resources.js` — the class export serves as the endpoint registration. See [custom-resources.md](custom-resources.md) for details on building Resource classes.
-- Harper's REST layer automatically exposes `@export`-ed tables and Resource classes as HTTP endpoints. See [automatic-apis.md](automatic-apis.md) for how endpoints are structured and named.
-- ETag values include their double quotes as part of the value — include them verbatim when passing the value in `If-None-Match`.
-- `sourcedFrom` must be called after the table reference (`tables.JokeCache`) is available, which is guaranteed when the call is at the top level of `resources.js`.
+- ETags are automatically computed from a record's last-modified timestamp. Include the double quotes when passing an ETag back in `If-None-Match` — they are part of the value.
+- Exporting a class with the same name as a table (e.g., `export class JokeCache extends tables.JokeCache`) registers it as the HTTP endpoint for that table; `@export` in the schema is not required separately.
+- For defining custom upstream source behavior beyond a simple `get`, see [custom-resources.md](custom-resources.md).
+- For details on how `@table` and `@export` expose REST endpoints automatically, see [automatic-apis.md](automatic-apis.md).
 
 ## 4. Infrastructure & Ops