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

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)
+
+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
+   }
+   ```
 
-   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
+#### 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
+}
+```
 
-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.
+**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
+   	networkId: Long @indexed
+   	network: Network @relationship(from: networkId)
+   	title: String @indexed
+   }
+
+   type Network @table @export {
    	id: Long @primaryKey
-   	category: String @indexed
-   	price: Float @indexed
+   	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,
+   });
+   ```
 
-   | 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                                                                    |
+   - `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.
+
+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,243 @@ 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 the `Blob` data type in Harper.
 
 #### 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 streaming support and out-of-record storage are required. 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 your `@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 and store a blob with `createBlob()`**: Pass a buffer or stream to `createBlob()`, then `put` the record.
+
+   ```javascript
+   let blob = createBlob(largeBuffer);
+   await MyTable.put({ id: 'my-record', data: blob });
+   ```
+
+3. **Retrieve blob data using standard Web API methods**: The `Blob` type implements the Web API `Blob` interface. Use `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, or `.slice()` as needed.
+
    ```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` when full write must precede commit**: By default, `Blob` is not ACID-compliant — a record can reference a blob before it is fully written. Set `saveBeforeCommit: true` to block the transaction until the blob is fully saved.
+
    ```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.
+
+   ```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` — no manual `createBlob()` call is needed in those cases.
+
+##### `BlobOptions` reference
+
+Pass an options object as the second argument to `createBlob()`.
+
+| 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 until the blob is fully written before the transaction commits.                                                     |
+| `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 a blob in as it streams out (low-latency passthrough):**
+
+```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();
+```
+
+**Guarantee full write before commit using `saveBeforeCommit`:**
+
+```javascript
+let blob = createBlob(stream, { saveBeforeCommit: true });
+await MyTable.put({ id: 'my-record', data: blob });
+```
+
+#### Notes
+
+- `Blob` stores data separately from the record. If you need the binary data to be a true, ACID-committed part of the record, use a `Bytes` field instead.
+- All standard Web API `Blob` methods — `.text()`, `.arrayBuffer()`, `.stream()`, `.slice()`, and `.bytes()` — are available on retrieved blob fields.
+- Without `saveBeforeCommit: true`, blobs are **not** ACID-compliant by default; a record can reference a blob before it is fully written to storage.
 
 ### 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,209 +1347,427 @@ 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 routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when a specific URL shape is required.
 
 #### 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 `harper`**: Always import from the `harper` package rather than relying on globals.
 
-   ```typescript
-   import { Resource } from 'harper';
+   ```javascript
+   import { tables, Resource } from 'harper';
+   ```
+
+2. **Define a class that `extends Resource`**: Implement HTTP methods as `static` methods. Each method receives a `target` object.
 
-   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. **Use `async` static methods for external calls**: Await fetch or other async operations inside `static` handlers.
+
+   ```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),
+   		});
+   	}
+   }
    ```
-7. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).
+
+4. **Export the class to create an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
+
+   | Export form                                 | URL             | Notes                                                           |
+   | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
+   | `export class Foo extends Resource {}`      | `/Foo/`         | Class name becomes the path segment. Case-sensitive.            |
+   | `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. |
+   | `export { Foo as '/widget/:id' }`           | `/widget/:id`   | Rename the export to set the path directly.                     |
+   | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
+   | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
+
+   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+
+5. **Declare path parameters with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+
+   ```javascript
+   export class Widget extends Resource {
+   	static path = '/widget/:id/action/:action';
+   	static get(target) {
+   		return { id: target.id, action: target.action };
+   	}
+   }
+   ```
+
+   A `static path` takes precedence over the export name. A leading `/` makes the path root-relative (top-level). A leading `./` or bare name resolves relative to the component directory.
+
+6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` when the path cannot be known at export time.
+
+   ```javascript
+   server.resources.set('my-path', Foo);
+   ```
+
+7. **Optionally source a table from a custom resource**: Use the resource as a caching layer for a local table.
+   ```javascript
+   tables.MyCache.sourcedFrom(MyExternalData);
+   ```
+
+#### Examples
+
+##### External API wrapper with GET and PUT
+
+```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);
+```
+
+##### Path parameters with `static path`
+
+```javascript
+import { Resource } from 'harper';
+
+export class Widget extends Resource {
+	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
+	static path = '/widget/:id/action/:action';
+	static get(target) {
+		return { id: target.id, action: target.action };
+	}
+}
+
+export class Files extends Resource {
+	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
+	static path = '/files/*rest';
+	static get(target) {
+		return { path: target.rest };
+	}
+}
+```
+
+##### Programmatic registration
+
+```javascript
+import { Resource } from 'harper';
+
+export class Foo extends Resource {
+	static get(target) {
+		return { data: doSomething() };
+	}
+}
+
+server.resources.set('my-path', Foo);
+```
+
+#### Notes
+
+- A bare `*` wildcard (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
+- Resolution order: exact/static paths always win over parameterized ones. Among parameterized routes, more specific paths win — a literal segment beats `:param`, which beats `*`, compared left to right.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
+- If a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
+- Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
+- Harper runs as a single process — `tables`, `databases`, and other APIs are the same live, process-wide objects regardless of which component accesses them.
 
 ### 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
 
-Instructions for the agent to follow when interacting with Harper tables via code.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object and its query API.
 
 #### When to Use
 
-Use this skill when you need to perform database operations (CRUD, search, subscribe) from within Harper Resources or scripts.
+Apply this rule when writing server-side Harper code that reads from or writes to tables directly — for example, in request handlers, background jobs, or SSR entry points — instead of going through the REST API. Use it whenever you need to construct queries with `conditions`, paginate results, select specific fields, or perform CRDT-safe mutations with `addTo`.
 
 #### How It Works
 
-1. **Access the Table**: Use the global `tables` object followed by your table name (e.g., `tables.MyTable`).
-2. **Perform CRUD Operations**:
-   - **Get**: `await tables.MyTable.get(id)` for a single record or `await tables.MyTable.get({ conditions: [...] })` for multiple.
-   - **Create**: `await tables.MyTable.post(record)` (auto-generates ID) or `await tables.MyTable.put(id, record)`.
-   - **Update**: `await tables.MyTable.patch(id, partialRecord)` for partial updates.
-   - **Delete**: `await tables.MyTable.delete(id)`.
-3. **Use Updatable Records for Atomic Ops**: Call `update(id)` to get a reference, then use `addTo` or `subtractFrom` for atomic increments/decrements:
-   ```typescript
-   const stats = await tables.Stats.update('daily');
-   stats.addTo('viewCount', 1);
-   ```
-4. **Search and Stream**: Use `search(query)` for efficient streaming of large result sets:
-   ```typescript
-   for await (const record of tables.MyTable.search({ conditions: [...] })) {
-     // process record
-   }
+1. **Import `tables`**: Import from the `harper` package. Each table defined in `schema.graphql` with `@table` is available as a named property.
+
+   ```javascript
+   import { tables } from 'harper';
+   const { Product } = tables;
+   // same as: databases.data.Product
    ```
-   See the [Query Conditions](#query-conditions) section below for the full query object reference.
-5. **Real-time Subscriptions**: Use `subscribe(query)` to listen for changes:
-   ```typescript
-   for await (const event of tables.MyTable.subscribe(query)) {
-   	// handle event
+
+2. **Define your schema**: Declare tables in `schema.graphql` using `@table` and `@primaryKey`.
+
+   ```graphql
+   # schema.graphql
+   type Product @table {
+   	id: Long @primaryKey
+   	name: String
+   	price: Float
    }
    ```
-6. **Publish Events**: Use `publish(id, message)` to trigger subscriptions without necessarily persisting data.
 
-#### Query Conditions
+3. **Create and mutate records**: Use `create`, `patch`, `get`, and `update` on the table class.
 
-When passing a query to `search()`, `get()`, or `subscribe()`, use a query object with a `conditions` array.
+   ```javascript
+   // Create a new record (id auto-generated)
+   const created = await Product.create({ name: 'Shirt', price: 9.5 });
 
-##### Condition Object Shape
+   // Modify the record
+   await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
 
-| Property     | Description                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------ |
-| `attribute`  | Field name, or array of field names to traverse a relationship (e.g., `['brand', 'name']`) |
-| `value`      | The value to compare against                                                               |
-| `comparator` | One of the comparator strings below (default: `equals`)                                    |
-| `operator`   | `and` (default) or `or` — applies to a nested `conditions` block                           |
-| `conditions` | Nested array of condition objects for complex AND/OR logic                                 |
+   // Retrieve by primary key
+   const record = await Product.get(created.id);
+   ```
 
-##### Comparator Values
+4. **Query with `search(` and `conditions`**: Pass a query object to `search()` to filter records. Iterate the async result.
 
-Use these exact strings — incorrect comparator names will silently fail or error:
+   ```javascript
+   const query = {
+   	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
+   };
+   for await (const record of Product.search(query)) {
+   	// ...
+   }
+   ```
+
+5. **Use `select` to shape results**: Pass a `select` array to return only specific properties, including nested relationship fields.
+
+   ```javascript
+   const book = await Book.get({ id: 42, select: ['id', 'title', 'author'] });
+   book.author.name; // full related Author record
+
+   // Partial related record
+   const book = await Book.get({
+   	id: 42,
+   	select: ['id', 'title', { name: 'author', select: ['name'] }],
+   });
+   ```
 
-| Comparator           | Meaning                                                    |
-| -------------------- | ---------------------------------------------------------- |
-| `equals`             | Exact match (default)                                      |
-| `not_equal`          | Not equal                                                  |
-| `greater_than`       | `>`                                                        |
-| `greater_than_equal` | `>=`                                                       |
-| `less_than`          | `<`                                                        |
-| `less_than_equal`    | `<=`                                                       |
-| `starts_with`        | String starts with value                                   |
-| `contains`           | String contains value                                      |
-| `ends_with`          | String ends with value                                     |
-| `between`            | Value is between two bounds (pass `value` as `[min, max]`) |
+6. **Use `addTo` for concurrent-safe increments**: Call `addTo` on a mutable resource instance obtained via `update()`. This uses CRDT incrementation, safe across threads and nodes.
 
-##### Query Object Parameters
+   ```javascript
+   static async post(target, data) {
+     const record = await this.update(target.id);
+     record.addTo('quantity', -1); // decrement safely across nodes
+   }
+   ```
 
-| 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 |
+7. **Scope destructive operations carefully**: `update`, `patch`, and `delete` operate directly on stored data. Always use specific `conditions`, validate the affected set before writing, and gate behind authorization controls.
 
-##### Examples
+#### Examples
 
-**Simple filter:**
+##### Nested conditions query
 
 ```javascript
-for await (const record of tables.Product.search({
-  conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
-  limit: 20,
-})) { ... }
+Product.search({
+	conditions: [
+		{ attribute: 'price', comparator: 'less_than', value: 100 },
+		{
+			operator: 'or',
+			conditions: [
+				{ attribute: 'rating', comparator: 'greater_than', value: 4 },
+				{ attribute: 'featured', value: true },
+			],
+		},
+	],
+});
 ```
 
-**AND + nested OR:**
+##### Chained attribute reference (relationship join)
 
 ```javascript
-for await (const record of tables.Product.search({
-  conditions: [
-    { attribute: 'price', comparator: 'less_than', value: 100 },
-    {
-      operator: 'or',
-      conditions: [
-        { attribute: 'rating', comparator: 'greater_than', value: 4 },
-        { attribute: 'featured', value: true },
-      ],
-    },
-  ],
-})) { ... }
-```
-
-**Relationship traversal:**
+Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
+```
+
+##### Deep nested `select`
 
 ```javascript
-for await (const record of tables.Book.search({
-  conditions: [{ attribute: ['brand', 'name'], comparator: 'equals', value: 'Harper' }],
-})) { ... }
+select: [
+	'id',
+	'name',
+	{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
+];
 ```
 
-**Sort and paginate:**
+##### SSR usage
 
-```javascript
-for await (const record of tables.Product.search({
-  conditions: [{ attribute: 'inStock', value: true }],
-  sort: { attribute: 'price', descending: false },
-  limit: 10,
-  offset: 20,
-})) { ... }
+```typescript
+import { tables } from 'harper';
+
+export async function render(url: string): Promise<string> {
+	const product = await tables.Product.get(idFromUrl(url));
+	return renderToString(/* <App product={product} /> */);
+}
 ```
 
-#### Cautions
+#### Notes
+
+##### `conditions` comparator values
+
+| Comparator           | Description            |
+| -------------------- | ---------------------- |
+| `equals`             | Default equality match |
+| `greater_than`       | Strictly greater       |
+| `greater_than_equal` | Greater than or equal  |
+| `less_than`          | Strictly less          |
+| `less_than_equal`    | Less than or equal     |
+| `starts_with`        | String prefix match    |
+| `contains`           | String contains        |
+| `ends_with`          | String suffix match    |
+| `between`            | Range match            |
+| `not_equal`          | Inequality match       |
+
+##### Query object options
 
-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.
+| Property                | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `conditions`            | Array of condition objects to filter records                            |
+| `operator`              | Top-level `and` (default) or `or` for the `conditions` array            |
+| `limit`                 | Maximum number of records to return                                     |
+| `offset`                | Number of records to skip (for pagination)                              |
+| `select`                | Properties to include in each returned record                           |
+| `sort`                  | Sort order object with `attribute`, `descending`, and `next` properties |
+| `explain`               | If `true`, returns conditions reordered as Harper will execute them     |
+| `enforceExecutionOrder` | If `true`, forces conditions to execute in the order supplied           |
+
+##### `select` special properties
+
+- `$id` — Returns the primary key regardless of its name
+- `$updatedtime` — Returns the last-updated timestamp
+- `$distance` — Returns the computed distance from the target vector when the query uses a vector index
+
+##### Relationship join behavior
+
+- Selecting a relationship **without** filtering on it behaves as a **LEFT JOIN** — records with no related row are still returned.
+- Adding a `conditions` entry on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN** — only records with a matching related row are returned.
+
+- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime instead of being bundled.
+- `tables`, `databases`, and other Harper APIs are the same live, process-wide objects regardless of whether accessed as globals or via `import { tables } from 'harper'`.
 
 ### 3.4 TypeScript Type Stripping in Harper
 
@@ -1281,15 +1825,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 +1843,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 +1852,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 +1877,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 +1891,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 +1928,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
 
@@ -1678,6 +2228,34 @@ static:
 - Install dependencies: `npm install --save-dev vite @harperfast/vite @vitejs/plugin-react` (swap in your framework's Vite plugin, e.g. `@vitejs/plugin-vue`).
 - Then `harper dev .` runs the app with HMR and `harper run .` runs the production build. Vite does _not_ need to be executed separately.
 
+#### Reading Harper Data During SSR
+
+The render entry (`src/entry-server.tsx`) runs **inside Harper**, so it can read straight from the database and render the data into the HTML — no client-side fetch/XHR. `tables` is the same live, process-wide registry available everywhere (see [Programmatic Table Requests](programmatic-table-requests.md)); import it and query a table in an async `render`:
+
+```tsx
+import { tables } from 'harper';
+
+export async function render(url: string): Promise<string> {
+	const product = await tables.Product.get(idFromUrl(url));
+	return renderToString(
+		<StrictMode>
+			<App product={product} />
+		</StrictMode>,
+	);
+}
+```
+
+Keep `harper` external in `vite.config.ts` so this import resolves to Harper's running runtime instead of being bundled. `node_modules/harper` is symlinked to the running install, and symlinked deps aren't reliably auto-externalized for SSR:
+
+```typescript
+export default defineConfig({
+	ssr: { external: ['harper'] },
+	// ...plugins, resolve, build
+});
+```
+
+To hydrate on the client without re-fetching, embed the rendered data in the HTML (e.g. an inline `<script type="application/json">`) and read it back before hydration — so the page needs no XHR at all.
+
 #### Deploying to Production
 
 Because `@harperfast/vite` builds on the node and `static` serves the output, deploy the component as-is — no manual build-and-move step is needed: