@harperfast/template-react-ts-ssr-studio 1.13.4 → 1.13.6

package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md

@@ -5,34 +5,29 @@ metadata:
   mode: generate
   sources:
     - reference/v5/rest/querying.md
-  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
-  inputHash: 25b9daabc0a28fd5
+  sourceCommit: 6c3e29dd9149201364b0d74642725c30f0305e3e
+  inputHash: e034fdc191f2cdc0
 ---
 
-# Querying REST APIs
+# Querying Harper REST APIs
 
-Instructions for the agent to filter, sort, select, and paginate records through Harper's URL-based REST query language.
+Instructions for the agent to filter, sort, select, and paginate records using Harper's URL-based query language on REST collection endpoints.
 
 ## When to Use
 
-Apply this rule whenever you need to construct or handle GET requests against Harper collection endpoints that require filtering by attribute value, comparison operators, sorting, field selection, or paginated results. This rule also covers type coercion syntax and relationship joins via dot notation. See [automatic-apis.md](automatic-apis.md) for how REST endpoints are generated from schemas.
+Apply this rule whenever building or modifying REST requests against Harper collection paths that need attribute filtering, comparison operators, sorting, field selection, pagination, or relationship joins. This rule covers all query parameter construction for Harper's automatic REST APIs (see [automatic-apis.md](automatic-apis.md)).
 
 ## How It Works
 
-1. **Filter by attribute**: Add query parameters matching attribute names and values. The queried attribute must be indexed.
+1. **Filter by attribute**: Add query parameters matching attribute name to value. The queried attribute must be indexed.
 
    ```
    GET /Product/?category=software
    GET /Product/?category=software&inStock=true
-   ```
-
-   To filter for null values:
-
-   ```
    GET /Product/?discount=null
    ```
 
-2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in the query string for range and pattern matching.
+2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in the query string for range and string comparisons.
 
    | Operator             | Meaning                                |
    | -------------------- | -------------------------------------- |
@@ -53,21 +48,18 @@ Apply this rule whenever you need to construct or handle GET requests against Ha
    GET /Product/?price=le=20
    GET /Product/?name==Keyboard*
    GET /Product/?category=software&price=gt=100&price=lt=200
-   ```
-
-   For date fields, URL-encode colons as `%3A`:
-
-   ```
    GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
    ```
 
-3. **Chain conditions for range queries**: Omit the attribute name on the second condition to apply it to the same attribute. Only `gt`/`ge` combined with `lt`/`le` is supported.
+3. **Chain conditions for range queries**: Omit the attribute name on the second condition to apply it to the same attribute.
 
    ```
    GET /Product/?price=gt=100&lt=200
    ```
 
-4. **Apply type conversion**: For FIQL comparators (`==`, `!=`, `=gt=`, etc.), Harper converts values automatically. Use explicit type prefixes to force a specific type.
+   Chaining supports `gt`/`ge` combined with `lt`/`le` only.
+
+4. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit type prefixes when needed.
 
    | Syntax                                    | Behavior                                    |
    | ----------------------------------------- | ------------------------------------------- |
@@ -87,80 +79,83 @@ Apply this rule whenever you need to construct or handle GET requests against Ha
    GET /Product/?rating=5|featured=true
    ```
 
-6. **Group conditions**: Use parentheses or square brackets to control evaluation order. Prefer square brackets when building queries from user input, since standard URI encoding safely encodes `[` and `]`.
+6. **Group conditions**: Use parentheses or square brackets to control order of operations. Prefer square brackets when constructing queries from user input.
 
    ```
    GET /Product/?rating=5|(price=gt=100&price=lt=200)
    GET /Product/?rating=5&[tag=fast|tag=scalable|tag=efficient]
    ```
 
-   Build grouped queries in JavaScript:
+   Construct from JavaScript:
 
    ```javascript
    let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;
    ```
 
-7. **Select specific properties with `select()`**: Append `select()` as a query function separated by `&`.
+7. **Select specific properties with `select()`**: Specify which properties to include in the response.
 
-   | Syntax                                 | Returns                                     |
-   | -------------------------------------- | ------------------------------------------- |
-   | `?select(property)`                    | Values of a single property directly        |
-   | `?select(property1,property2)`         | Objects with only the specified properties  |
-   | `?select([property1,property2])`       | Arrays of property values                   |
-   | `?select(property1,)`                  | Objects with a single specified property    |
-   | `?select(property{subProp1,subProp2})` | Nested objects with specific sub-properties |
+   | Syntax                                 | Returns                                           |
+   | -------------------------------------- | ------------------------------------------------- |
+   | `?select(property)`                    | Values of a single property directly              |
+   | `?select(property1,property2)`         | Objects with only the specified properties        |
+   | `?select([property1,property2])`       | Arrays of property values                         |
+   | `?select(property1,)`                  | Objects with a single specified property          |
+   | `?select(property{subProp1,subProp2})` | Nested objects with specific sub-properties       |
+   | `?select(id,products[limit(1)])`       | Parents with a constrained relationship selection |
 
    ```
    GET /Product/?category=software&select(name)
    GET /Product/?brand.name=Microsoft&select(name,brand{name})
    ```
 
-8. **Limit results with `limit(end)` or `limit(start,end)`**: Append as a query function.
+8. **Limit results with `limit(end)` or `limit(start,end)`**: Return records in a zero-based window from `start` (inclusive) to `end` (exclusive). `limit(end)` starts at zero.
 
    ```
    GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
    GET /Product/?rating=gt=3&limit(10,30)
    ```
 
-9. **Sort results with `sort(property)` or `sort(+property,-property,...)`**: Prefix `+` or no prefix = ascending; `-` = descending. List multiple properties to break ties in order.
+9. **Sort results with `sort(property)` or `sort(+property,-property,...)`**: Prefix `+` or no prefix = ascending; `-` = descending. Multiple properties break ties in order.
 
    ```
    GET /Product/?rating=gt=3&sort(+name)
    GET /Product/?sort(+rating,-price)
    ```
 
-10. **Paginate with a total count**: Use `limit(start,end)` for paging and send a `Prefer` request header to receive a total match count.
+10. **Request a total count for pagination**: Send a `Prefer` header on `GET` or `HEAD` requests. Counting requires a bounded `limit()` with page size no larger than 10,000 and window end no larger than 1,000,000.
 
-    | `Prefer` value    | Meaning                                  |
-    | ----------------- | ---------------------------------------- |
-    | `count=exact`     | Exact count of matching records (opt-in) |
-    | `count=estimated` | Fast approximate count                   |
+    | `Prefer` value    | Meaning                                                                                       |
+    | ----------------- | --------------------------------------------------------------------------------------------- |
+    | `count=exact`     | Exact number of matching records. Off by default; requires `exactCount: true` in REST config. |
+    | `count=estimated` | Fast approximate count. Does not require `exactCount`.                                        |
 
     ```
     GET /Product/?category=software&limit(0,25)
     Prefer: count=exact
     ```
 
-    The server responds with:
+    Response headers:
 
-    | Header               | Example           | Description                                            |
-    | -------------------- | ----------------- | ------------------------------------------------------ |
-    | `Content-Range`      | `items 0-24/1234` | 0-based inclusive range out of total matching records  |
-    | `Range-Unit`         | `items`           | Unit used by `Content-Range`                           |
-    | `Preference-Applied` | `count=exact`     | Count mode the server applied (`exact` or `estimated`) |
-
-    The response status is always `200`. When the total cannot be produced, it is reported as `*` (e.g., `Content-Range: items 0-24/*`).
+    ```
+    HTTP/1.1 200 OK
+    Content-Range: items 0-24/1234
+    Range-Unit: items
+    Preference-Applied: count=exact
+    ```
 
-    Enable exact counts in the application's REST configuration:
+    Enable exact counts in REST configuration:
 
     ```yaml
     rest:
       exactCount: true
     ```
 
-    Without this, a `count=exact` request is served as an estimate.
+    - The response status for paginated requests is always `200`; Harper does not use `206 Partial Content`.
+    - A `HEAD` request with a `count` preference returns the count headers with no body.
+    - When CORS is enabled, `Content-Range`, `Range-Unit`, and `Preference-Applied` are added to `Access-Control-Expose-Headers`.
+    - Without `exactCount: true`, a `count=exact` request is served as an estimate. When the total cannot be produced, it is reported as `*` (e.g., `Content-Range: items 0-24/*`). `Preference-Applied` still echoes the requested mode, so an unavailable total (`.../*`) is distinct from a request that asked for no count.
 
-11. **Query across relationships using dot syntax**: Define relationships in the schema with `@relationship`, then filter and select across them.
+11. **Query across relationships**: Use dot-syntax on attributes defined with `@relationship` in the schema.
 
     ```
     GET /Product/?brand.name=Microsoft
@@ -168,32 +163,47 @@ Apply this rule whenever you need to construct or handle GET requests against Ha
     GET /Product/?brand.name=Microsoft&select(name,brand{name})
     ```
 
-    Filtering on a related attribute produces INNER JOIN behavior. Selecting a relationship without filtering produces LEFT JOIN behavior — the property is omitted if the foreign key is null or references a non-existent record.
+    Selecting a relationship without an outer dot-syntax filter behaves as a LEFT JOIN. An outer filter such as `products.price=ge=number:30` removes parents without a qualifying product and also narrows the selected products.
 
-12. **Access a specific property by URL**: Append the property name with dot syntax to the record ID.
+12. **Filter and page nested relationships**: Use square brackets inside `select()` to apply conditions, sort, and pagination to each parent's related records.
 
     ```
-    GET /MyTable/123.propertyName
+    GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
     ```
 
-    This only works for declared schema properties. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors.
+    An outer relationship filter also narrows that relationship's nested results — do not repeat the outer filter inside `[...]` unless you want to narrow further.
+
+    | Nested option      | Behavior                                                        |
+    | ------------------ | --------------------------------------------------------------- |
+    | Conditions         | Qualify children; combine with `&` (AND), `\|` (OR), and groups |
+    | `sort(price)`      | Order eligible children before pagination                       |
+    | `limit(end)`       | Return at most `end` children per parent                        |
+    | `limit(start,end)` | Skip `start` eligible children and return at most `end - start` |
+    | `select(id,price)` | Project fields from returned children                           |
+    - Invalid nested bounds (negative or fractional values) return HTTP 400. `limit(0)` returns no children without reading them.
 
 ## Examples
 
-**Range filter with select and sort:**
+### Range filter with sort and limit
+
+```
+GET /Product/?category=software&price=gt=100&price=lt=200&sort(+price)&limit(0,25)
+```
+
+### Relationship join with nested selection
 
 ```
-GET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)&sort(+price)
+GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
 ```
 
-**Paginated request with exact count:**
+### Paginated request with exact count
 
 ```
 GET /Product/?category=software&limit(0,25)
 Prefer: count=exact
 ```
 
-Response headers:
+Response:
 
 ```
 HTTP/1.1 200 OK
@@ -202,27 +212,21 @@ Range-Unit: items
 Preference-Applied: count=exact
 ```
 
-**Relationship schema and join query:**
+### Nested relationship filter with OR, sort, and pagination
 
-```graphql
-type Product @table @export {
-	id: Long @primaryKey
-	name: String
-	brandId: Long @indexed
-	brand: Brand @relationship(from: "brandId")
-}
-type Brand @table @export {
-	id: Long @primaryKey
-	name: String
-	products: [Product] @relationship(to: "brandId")
-}
 ```
+GET /Brand/?sort(name,id)&limit(0,20)&select(id,name,products[[price=lt=number:30|price=ge=number:60]&sort(-price,id)&limit(1,2)&select(id,name,price)])
+```
+
+### Outer filter inheriting into nested selection
 
 ```
-GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
+GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1)&select(id,name,price)])
 ```
 
-**Many-to-many relationship:**
+### Many-to-many relationship query
+
+Schema:
 
 ```graphql
 type Product @table @export {
@@ -233,21 +237,21 @@ type Product @table @export {
 }
 ```
 
+Query:
+
 ```
 GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
 ```
 
-**OR grouping with user-supplied tags:**
-
-```javascript
-let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;
-```
-
 ## Notes
 
-- The queried attribute must be indexed for basic attribute filtering to execute. For multi-attribute queries, only one attribute needs to be indexed.
-- Null indexing requires indexes created after the feature was introduced. Rebuild existing indexes (remove and re-add) to support `name==null` queries.
-- `limit()` must be a non-negative integer no larger than **10,000**, and the requested window (offset + limit) no larger than **1,000,000**, for count headers to be returned.
-- A `HEAD` request with a `Prefer: count=exact` header returns count headers with no body — it saves bandwidth but still scans the matched set.
-- When CORS is enabled, `Content-Range`, `Range-Unit`, and `Preference-Applied` are added to `Access-Control-Expose-Headers` automatically.
-- Operators `!=` and `=ct=` (contains) do not produce cardinality estimates; the total is reported as `*` when these are used with `count=exact`.
+- Queried attributes must be indexed for filtering to execute; only one attribute in a multi-attribute query needs to be indexed.
+- URL-encode colons in date values as `%3A` (e.g., `listDate=gt=2017-03-08T09%3A30%3A00.000Z`).
+- Square brackets are preferred over parentheses when constructing queries programmatically because standard URI encoding safely encodes `[` and `]`.
+- Brackets inside `select()` after a relationship name (e.g., `select(id,products[limit(1)])`) form a nested relationship query, not a grouping expression.
+- For full-text fields marked `@fullText`, use operators such as `=matches=`, `=matches_phrase=`, `=matches_prefix=`, `=matches_fuzzy=`, and their `=not_*=` negated forms. Full-text queries cannot provide an exact total count.
+- `limit(end)` and `limit(start,end)` inside a nested relationship selection apply per parent, not to the total result set.
+- Always add a unique field as the final sort key (e.g., `sort(name,id)`) to ensure deterministic ordering across pages.
+- Nested filters require a table-backed relationship; filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
+- For streaming JSON-array responses, check for a terminal object shaped like `{ "error": "ErrorName: message" }` and treat the response as failed.
+- Access a specific property of a record using dot syntax on the record ID: `GET /MyTable/123.propertyName`. This only works for declared schema properties. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors and take precedence over a property of the same name.

package/.agents/skills/harper-best-practices/rules/real-time-apps.md

@@ -13,6 +13,8 @@ metadata:
 
 Instructions for the agent to follow when building real-time features in Harper using WebSockets and Pub/Sub.
 
+**Instead of:** Socket.io, `ws`, Pusher, Ably, Redis pub/sub, a separate MQTT broker. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Apply this rule when implementing any feature that requires real-time bidirectional communication, live data streaming, or push-based updates in a Harper application. This includes chat, live dashboards, sensor feeds, and any scenario where clients must receive resource changes as they happen.

package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md

@@ -9,30 +9,30 @@ metadata:
     - reference/v5/database/schema.md#Overview
     - reference/v5/database/schema.md#Type Directives
     - reference/v5/database/schema.md#Field Directives
-  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
-  inputHash: a644f4ea2f289f77
+  sourceCommit: 4aea8b1fffc53ee1dcf4841676350fef58f24056
+  inputHash: af9e326b0cf010d8
 ---
 
-# Schema Design Tooling
+# Schema Design and GraphQL Tooling
 
 Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
 ## When to Use
 
-Apply this rule when creating or modifying Harper schema files (`.graphql`), configuring `graphqlSchema` in `config.yaml`, or deciding which directives to apply to tables and fields. Use it whenever a task involves defining tables, primary keys, indexes, or export behavior.
+Apply this rule when creating or modifying Harper schema files, configuring `graphqlSchema` in `config.yaml`, or deciding which directives to apply to tables and fields. Use it whenever a task involves defining tables, primary keys, indexes, or export behavior.
 
 ## How It Works
 
-1. **Register the schema file** in the component's `config.yaml` using the `graphqlSchema` plugin key:
+1. **Load the schema via `graphqlSchema`**: In the component's `config.yaml`, point to the schema file:
 
    ```yaml
    graphqlSchema:
      files: 'schema.graphql'
    ```
 
-   Both plugins and applications can specify schemas.
+   Both plugins and applications can specify schemas. The schema ensures required tables exist on deployment, enforces types, controls indexing, and defines relationships.
 
-2. **Mark types as tables** using `@table`. The type name becomes the table name by default:
+2. **Mark tables with `@table`**: Apply `@table` to every GraphQL type that should become a Harper database table. The type name becomes the table name by default.
 
    ```graphql
    type Dog @table {
@@ -43,47 +43,60 @@ Apply this rule when creating or modifying Harper schema files (`.graphql`), con
    }
    ```
 
-3. **Designate a primary key** on every table using `@primaryKey`. Primary keys must be unique; duplicate 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 `@table` arguments to override defaults:
 
-   Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
+   | Argument                 | Type      | Default                       | Description                                                                    |
+   | ------------------------ | --------- | ----------------------------- | ------------------------------------------------------------------------------ |
+   | `table`                  | `String`  | type name                     | Override the table name                                                        |
+   | `database`               | `String`  | `"data"`                      | Database to place the table in                                                 |
+   | `expiration`             | `Int`     | —                             | Seconds until a record goes stale                                              |
+   | `eviction`               | `Int`     | `0`                           | Additional seconds after `expiration` before physical removal                  |
+   | `scanInterval`           | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                                 |
+   | `replicate`              | `Boolean` | `true`                        | Enable replication of this table                                               |
+   | `replicaExpiration`      | `Float`   | `3600`                        | Seconds a record fetched from another node is kept as a local replica          |
+   | `replicaRefreshFraction` | `Float`   | `0.5`                         | Fraction of `replicaExpiration` after which a read renews the replica lifetime |
+   | `audit`                  | `Boolean` | `logging.auditLog`            | Enable the table's transaction log                                             |
+   | `cacheControl`           | `String`  | —                             | `Cache-Control` header for anonymous GET/HEAD 200/304 responses                |
+   | `randomAccessFields`     | `Boolean` | `storage.randomAccessFields`  | Pin this table's record encoding                                               |
 
-4. **Index fields for querying** using `@indexed`. Required for filtering by an attribute in REST queries, SQL, or NoSQL operations:
+3. **Designate a primary key with `@primaryKey`**: Apply `@primaryKey` to exactly one field per table. Primary keys must be unique; duplicate inserts are rejected.
 
    ```graphql
-   type Breed @table {
+   type Product @table {
    	id: Long @primaryKey
-   	name: String @indexed
+   	name: String
    }
    ```
 
-   If the field value is an array, each element is individually indexed. Null values are indexed by default.
+   If no primary key is provided on insert, Harper auto-generates one:
+   - **UUID string** — when type is `String` or `ID`
+   - **Auto-incrementing integer** — when type is `Int`, `Long`, or `Any`
+
+   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
 
-5. **Expose tables as REST/MQTT endpoints** using `@export`. The optional `name` parameter sets the URL path segment; without it, the type name is used:
+4. **Index queryable fields with `@indexed`**: Apply `@indexed` to any field that must be filterable via REST queries, SQL, or NoSQL operations.
 
    ```graphql
-   type MyTable @table @export(name: "my-table") {
+   type Product @table {
    	id: Long @primaryKey
+   	category: String @indexed
+   	price: Float @indexed
    }
    ```
 
-   `@export` alone does not serve HTTP traffic — REST must also be enabled for the application via `rest: true` in `config.yaml` or Harper's built-in default. `@export` is a routing directive, not access control; omitting it returns 404 but does not protect the data.
+   If the field value is an array, each element is individually indexed. Null values are indexed by default.
+
+5. **Expose tables externally with `@export`**: Apply `@export` to make a table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment.
 
-6. **Configure `@table` arguments** to control database placement, expiration, replication, and caching behavior. Key arguments:
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
+   ```
 
-   | Argument             | Type      | Default                       | Description                                                    |
-   | -------------------- | --------- | ----------------------------- | -------------------------------------------------------------- |
-   | `table`              | `String`  | type name                     | Override the table name                                        |
-   | `database`           | `String`  | `"data"`                      | Database to place the table in                                 |
-   | `expiration`         | `Int`     | —                             | Seconds until a record goes stale                              |
-   | `eviction`           | `Int`     | `0`                           | Additional seconds after `expiration` before physical removal  |
-   | `scanInterval`       | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                 |
-   | `replicate`          | `Boolean` | `true`                        | Enable replication of this table                               |
-   | `cacheControl`       | `String`  | —                             | `Cache-Control` header on anonymous GET/HEAD 200/304 responses |
-   | `randomAccessFields` | `Boolean` | `storage.randomAccessFields`  | Pin this table's record encoding                               |
+   `@export` alone does not serve HTTP traffic — REST must also be enabled for the application via `rest: true` in `config.yaml` or Harper's built-in default. `@export` is a routing directive, not access control: omitting it returns 404 to callers but the table remains accessible through the Operations API and SQL.
 
-7. **Seal a type** with `@sealed` to prevent records from including properties beyond those declared:
+6. **Prevent extra properties with `@sealed`** (when needed): Apply `@sealed` to reject records that include properties beyond those declared in the schema. By default, Harper allows additional properties.
 
    ```graphql
    type StrictRecord @table @sealed {
@@ -92,13 +105,33 @@ Apply this rule when creating or modifying Harper schema files (`.graphql`), con
    }
    ```
 
-8. **Use timestamp directives** for automatic record lifecycle tracking:
-   - `@createdTime` — assigns Unix epoch milliseconds on record creation
-   - `@updatedTime` — assigns Unix epoch milliseconds on each update
-   - `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); authoritative over the table-level `expiration` default
+7. **Use unique database names for plugins and applications**: All tables default to the `data` database. Specify a distinct `database` argument on `@table` to avoid naming collisions between components.
 
-9. **Use `@embed`** to automatically compute an embedding vector for an attribute whenever the source field is written (requires `source` and `model` arguments; field type must be `[Float]`):
+8. **Apply timestamp and expiration field directives** where needed:
+   - `@createdTime` — auto-assigns a Unix epoch millisecond timestamp on record creation.
+   - `@updatedTime` — auto-assigns a Unix epoch millisecond timestamp on each update.
+   - `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); overrides the table-level `expiration` default.
+   - `@hidden` — suppresses the type or field from MCP tool descriptors and the OpenAPI document. Does not restrict data access.
 
+   ```graphql
+   type Event @table {
+   	id: Long @primaryKey
+   	createdAt: Long @createdTime
+   	updatedAt: Long @updatedTime
+   }
+
+   type Session @table {
+   	id: ID @primaryKey
+   	token: String
+   	expiresAt: Long @expiresAt
+   }
+   ```
+
+   Key `@expiresAt` behaviors:
+   - Takes an absolute Unix epoch millisecond timestamp, not a duration. A full-record `put` that omits the field clears it; a `patch` preserves it.
+   - A per-record value may extend or shorten a record's expiration relative to the table-level `expiration` default. When a record omits the field, the table default (if any) applies.
+
+9. **Use `@embed`** to automatically compute an embedding vector for an attribute whenever the source field is written (requires `source` and `model` arguments; field type must be `[Float]`):
    ```graphql
    type Document @table {
    	id: Long @primaryKey
@@ -106,12 +139,11 @@ Apply this rule when creating or modifying Harper schema files (`.graphql`), con
    	embedding: [Float] @embed(source: "text", model: "default")
    }
    ```
-
-10. **Use `@hidden`** on types or fields to suppress them from MCP tool descriptors and the OpenAPI document. This is a metadata-visibility directive only — it does not restrict data access. Use `attribute_permissions` on roles for field-level access control.
+   The attribute is automatically indexed with an HNSW vector index. A failure to compute the embedding fails the write. An update that does not touch the `source` field leaves the vector unchanged. Setting the `source` field to `null` sets the vector to `null`.
 
 ## Examples
 
-**Minimal two-table schema:**
+**Minimal schema with two tables:**
 
 ```graphql
 type Dog @table {
@@ -127,7 +159,7 @@ type Breed @table {
 }
 ```
 
-**Table with expiration, eviction, and scan tuning:**
+**Caching table with expiration, eviction, and scan tuning:**
 
 ```graphql
 # Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
@@ -147,7 +179,7 @@ type Product @table(cacheControl: "public, max-age=60") @export {
 }
 ```
 
-**Table with multiple `@table` arguments combined:**
+**Table in a named database with expiration:**
 
 ```graphql
 type Event @table(database: "analytics", expiration: 86400) {
@@ -156,29 +188,28 @@ type Event @table(database: "analytics", expiration: 86400) {
 }
 ```
 
-**Session table with per-record expiration:**
+**Replica lifetime tuning:**
 
 ```graphql
-type Session @table {
+# Keep fetched records for a day; a read after six hours renews them
+type Order @table(replicaExpiration: 86400, replicaRefreshFraction: 0.25) {
 	id: ID @primaryKey
-	token: String
-	expiresAt: Long @expiresAt
+	region: String @indexed
 }
 ```
 
-**Table with timestamp tracking and indexed fields:**
+**Random-access field encoding pinned on the table:**
 
 ```graphql
-type Order @table(database: "commerce") @export {
-	id: Long @primaryKey
-	userId: String @indexed
-	status: String @indexed
-	createdAt: Long @createdTime
-	updatedAt: Long @updatedTime
+type Reading @table(randomAccessFields: true) {
+	id: ID @primaryKey
+	sensorId: String @indexed
+	celsius: Float
+	recordedAt: Int
 }
 ```
 
-**`config.yaml` schema registration:**
+**`config.yaml` loading the schema:**
 
 ```yaml
 graphqlSchema:
@@ -187,10 +218,12 @@ graphqlSchema:
 
 ## Notes
 
-- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
-- Disabling replication (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.
-- `cacheControl` emits the header only on anonymous (unauthenticated) GET/HEAD `200`/`304` responses. Authenticated responses receive `Cache-Control: private, no-cache` regardless of the declaration. The header is never emitted on `401` responses.
-- `@expiresAt` requires an absolute Unix epoch millisecond timestamp, not a duration. Negative values are ignored and fall back to the table default. A full-record `put` that omits the field clears it; a `patch` preserves it.
-- Eviction removes non-indexed record data but does not remove a record from its secondary indexes; indexes remain functional for evicted records, with full records fetched on demand.
-- `scanInterval` is clock-aligned to the server's local timezone, not startup-aligned — the server's startup time does not affect when eviction runs.
-- `randomAccessFields` pins the table's encoding at creation time. Editing the argument later does not repin an existing table. Omit it to follow the global `storage.randomAccessFields` setting.
+- Schemas are flexible by default — records may include additional properties. Use `@sealed` to prevent this.
+- `@export` is a routing directive, not an access control mechanism. Use RBAC and `attribute_permissions` to restrict data access.
+- `cacheControl` on `@table` only emits the header for anonymous (unauthenticated) GET/HEAD 200/304 responses. Authenticated responses always receive `Cache-Control: private, no-cache`.
+- `expiration`, `eviction`, and `scanInterval` work together: `expiration` marks a record stale, `eviction` controls physical removal, and `scanInterval` sets how often the sweep runs. Eviction scans are clock-aligned to the server's local timezone, not startup-aligned.
+- Eviction removes non-indexed record data but does not remove a record from its secondary indexes; indexes remain functional for evicted records.
+- `replicaExpiration` and `replicaRefreshFraction` apply only on the RocksDB engine. On LMDB, remote reads remain proxy reads regardless of these settings.
+- Disabling replication on a table (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.
+- `randomAccessFields` on `@table` pins the encoding when the table is created. Editing the argument later does not repin an existing table.
+- `@hidden` is a metadata-visibility directive only — it does not restrict data access. Use `attribute_permissions` on roles for field-level access control.

package/.agents/skills/harper-best-practices/rules/serving-web-content.md

@@ -9,6 +9,8 @@ metadata:
 
 Instructions for the agent to follow when serving web content from Harper.
 
+**Instead of:** Nginx, Vercel, or Netlify for the frontend; a separate Vite dev server. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React/Vue app) directly from your Harper instance — either plain static files or an integrated Vite app with hot module replacement (HMR) in development and a real production build when deployed.

package/.agents/skills/harper-best-practices/rules/typescript-type-stripping.md

@@ -13,6 +13,8 @@ metadata:
 
 Instructions for the agent to run `.ts` files directly in Harper without a build step using Node.js's built-in type stripping.
 
+**Instead of:** `tsc` or `ts-node` build steps for server code. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 Apply this rule when writing Harper resource files in TypeScript. Use it any time you need to reference `.ts` source files from `config.yaml` or import between local TypeScript modules in a Harper project.

package/.agents/skills/harper-best-practices/rules/using-blob-datatype.md

@@ -16,6 +16,8 @@ metadata:
 
 Instructions for the agent to follow when storing and retrieving large binary content using the `Blob` data type in Harper.
 
+**Instead of:** S3 or GCS buckets for app-managed files. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 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](handling-binary-data.md) for broader binary data guidance.

package/.agents/skills/harper-best-practices/rules/vector-indexing.md

@@ -13,6 +13,8 @@ metadata:
 
 Instructions for the agent to enable HNSW vector indexes on table fields and query them for similarity search in Harper.
 
+**Instead of:** Pinecone, Weaviate, pgvector. Use this rule rather than adding that service. See `harper-architecture`.
+
 ## When to Use
 
 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 combining vector search with record-level access control. See [adding-tables-with-schemas.md](adding-tables-with-schemas.md) for how to define the surrounding table schema.