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

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

@@ -8,6 +8,8 @@ Guidelines for building scalable, secure, and performant applications on Harper.
 
 Instructions for the agent to follow when adding tables to a Harper database.
 
+**Instead of:** Postgres, MySQL, MongoDB, DynamoDB, Supabase, Firebase. Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Use this skill when you need to define new data structures or modify existing ones in a Harper database.
@@ -40,26 +42,26 @@ type ExamplePerson @table @export {
 }
 ```
 
-### 1.2 Schema Design 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.
 
 #### 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 {
@@ -70,47 +72,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.
 
-6. **Configure `@table` arguments** to control database placement, expiration, replication, and caching behavior. Key arguments:
+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.
 
-   | 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                               |
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
+   ```
 
-7. **Seal a type** with `@sealed` to prevent records from including properties beyond those declared:
+   `@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.
+
+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 {
@@ -119,13 +134,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
@@ -133,12 +168,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 {
@@ -154,7 +188,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
@@ -174,7 +208,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) {
@@ -183,29 +217,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:
@@ -214,25 +247,29 @@ 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.
 
 ### 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.
+Instructions for the agent to define and query relationships between Harper tables using the `@relationship` directive in GraphQL schemas.
+
+**Instead of:** ORM relations and join tables (Prisma, Drizzle, Sequelize). Use this rule rather than adding that service. See `harper-architecture`.
 
 #### When to Use
 
-Apply this rule when adding foreign key relationships between schema tables, enabling join queries, or returning nested related records in query results. Use it any time a schema type needs to reference records in another table via a foreign key attribute.
+Apply this rule when writing Harper schemas that require join queries across tables, or when query results must include related records as nested properties. Use it whenever a foreign key exists in one table that references another, or when modeling one-to-many, many-to-one, or many-to-many associations.
 
 #### How It Works
 
-1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on the field in the table that holds the foreign key. The `from` parameter names the attribute on this table that stores the foreign key referencing the target table's primary key.
+1. **Declare a many-to-one relationship with `from`**: Place `@relationship(from: attribute)` on a field when the foreign key lives in the current table and references the primary key of the target table. The result type is a single object.
 
    ```graphql
    type RealityShow @table @export {
@@ -248,17 +285,7 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    }
    ```
 
-   If the foreign key attribute is an array, the relationship becomes many-to-many:
-
-   ```graphql
-   type RealityShow @table @export {
-   	id: Long @primaryKey
-   	networkIds: [Long] @indexed
-   	networks: [Network] @relationship(from: networkIds)
-   }
-   ```
-
-2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on the table whose primary key is referenced by the foreign key in the target table. The `to` parameter names the attribute on the target table that holds the foreign key. The result type **must** be an array.
+2. **Declare a one-to-many relationship with `to`**: Place `@relationship(to: attribute)` on a field when the foreign key lives in the target table and references the primary key of the current table. The result type **must** be an array.
 
    ```graphql
    type Network @table @export {
@@ -268,14 +295,14 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    }
    ```
 
-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. Harper resolves the relationship by searching the target table's `to` attribute for matches using this record's `from` attribute value. The result type must be an array.
+3. **Declare a foreign-key-to-foreign-key relationship with `@relationship(from: attribute, to: attribute)`**: Specify both `from` and `to` when neither side uses the primary key. Harper resolves the relationship by searching the target table's `to` attribute for matches using the current record's `from` attribute value. The result type must be an array.
 
    ```graphql
    type OrderItem @table @export {
    	id: Long @primaryKey
    	orderId: Long @indexed
    	productSku: Long @indexed
-   	products: [Product] @relationship(from: productSku, to: sku)
+   	products: [Product] @relationship(from: productSku, to: sku) # matches products by sku, not primary key
    }
 
    type Product @table @export {
@@ -285,14 +312,25 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    }
    ```
 
-4. **Query across relationships using dot-syntax**: Filter records by related table attributes using chained dot notation. This behaves as an INNER JOIN — only records with a matching related record are returned.
+4. **Declare a many-to-many relationship using an array foreign key with `from`**: When the foreign key field is an array, `@relationship(from: attribute)` establishes a many-to-many relationship. The result type must be an array.
+
+   ```graphql
+   type RealityShow @table @export {
+   	id: Long @primaryKey
+   	networkIds: [Long] @indexed
+   	networks: [Network] @relationship(from: networkIds)
+   }
+   ```
+
+5. **Query across relationships using dot-syntax**: Filter records by related table attributes using dot-chained attribute names. This behaves as an INNER JOIN — only parents with a qualifying related record are returned.
 
    ```
+   GET /RealityShow?network.name=Bravo
    GET /Product/?brand.name=Microsoft
    GET /Brand/?products.name=Keyboard
    ```
 
-5. **Include relationship fields in results using `select()`**: Relationship attributes are not returned by default. Use `select()` to include them, optionally specifying nested fields with `{}`.
+6. **Include relationship fields in results using `select()`**: Relationship attributes are not included by default. Use `select()` to project them, optionally with a nested field list using `{}`.
 
    ```
    GET /Product/?brand.name=Microsoft&select(name,brand)
@@ -300,24 +338,27 @@ Apply this rule when adding foreign key relationships between schema tables, ena
    GET /Product/?name=Keyboard&select(name,brand{name,id})
    ```
 
-   When selecting a relationship without filtering on it, Harper performs a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+   Selecting a relationship without an outer dot-syntax filter on it behaves as a LEFT JOIN: parents remain even when there are no related records.
 
-6. **Model many-to-many without a junction table**: Store an array of foreign key values and use `@relationship(from: ...)` pointing to that array attribute. The array order of the foreign key values is preserved when resolving the relationship.
+7. **Filter and page nested relationship results using `[]` inside `select()`**: Apply conditions, sort, and pagination to each parent's related records by placing them inside square brackets in the `select()` expression.
 
-   ```graphql
-   type Product @table @export {
-   	id: Long @primaryKey
-   	name: String
-   	resellerIds: [Long] @indexed
-   	resellers: [Reseller] @relationship(from: "resellerIds")
-   }
    ```
+   GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
+   ```
+
+   An outer relationship filter (e.g., `products.price=ge=number:30`) removes parents without a qualifying child **and** narrows the nested candidates. A filter inside `products[...]` only narrows projected children without removing their parent.
 
-7. **Define self-referential relationships** for parent-child hierarchies by pointing `@relationship` back at the same table type.
+   | 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; omit to return whole child records. |
 
 #### Examples
 
-**Full schema with bidirectional relationships:**
+##### Schema with bidirectional relationships
 
 ```graphql
 type Product @table @export {
@@ -334,30 +375,88 @@ type Brand @table @export {
 }
 ```
 
-**Querying with joins and nested select:**
+##### Many-to-many without a junction table
 
+```graphql
+type Product @table @export {
+	id: Long @primaryKey
+	name: String
+	resellerIds: [Long] @indexed
+	resellers: [Reseller] @relationship(from: "resellerIds")
+}
 ```
-GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
-GET /Brand/?products.name=Keyboard
+
+```
+GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+```
+
+The array order of `resellerIds` is preserved when resolving the relationship.
+
+##### Nested filtering and pagination scenarios
+
+Schema for the following examples:
+
+```graphql
+type Brand @table @export {
+	id: Int @primaryKey
+	name: String @indexed
+	products: [Product] @relationship(to: "brandId")
+}
+
+type Product @table @export {
+	id: ID @primaryKey
+	brandId: Int @indexed
+	name: String
+	price: Int @indexed
+}
 ```
 
-**Many-to-many query with nested select:**
+**Keep every brand; show its cheapest product costing at least 30** (LEFT JOIN behavior — Budget Basics returns with an empty product list):
 
 ```
-GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
+```
+
+**Return only qualifying brands; inherit the outer price filter** (INNER JOIN behavior — Budget Basics is removed):
+
+```
+GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1)&select(id,name,price)])
+```
+
+**Page through each brand's qualifying products** (offset applies independently per brand):
+
+```
+GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1,2)&select(id,name,price)])
+```
+
+**Bound parent pages with stable sorting**:
+
+```
+GET /Brand/?products.price=ge=number:30&sort(name,id)&limit(0,20)&select(id,name,products[sort(price,id)&limit(1)&select(id,name,price)])
+```
+
+**Combine OR filters with child sorting and pagination**:
+
+```
+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)])
 ```
 
 #### Notes
 
-- Every attribute named in `from` or `to` must exist on the respective table and be annotated with `@indexed` to support join queries.
-- The `to`-only and `from`+`to` forms both require the result field type to be an array (e.g., `[RealityShow]`).
-- The `from`-only form on a non-array attribute produces a many-to-one relationship; on an array attribute it produces many-to-many.
-- Self-referential relationships are supported for hierarchical data within a single table.
+- Index all foreign key fields (e.g., `brandId`, `price`) and outer filter fields to support efficient join queries.
+- Use a unique field as the final sort key (e.g., `sort(price,id)`) to ensure deterministic ordering when values are equal.
+- A nested `limit()` bounds children per parent, not the number of parents. Apply a separate outer `limit()` to bound the parent result set.
+- Nested filters require a table-backed relationship. Filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
+- Invalid `limit()` bounds (negative or fractional values) return HTTP 400. `limit(0)` returns no children without reading them.
+- A condition traversing another relationship qualifies the immediate child only; it does not narrow that child's projected descendants. Place grandchild constraints in the grandchild's own bracket selection.
+- Schemas can define self-referential relationships to enable parent-child hierarchies within a single table.
 
 ### 1.4 Vector Indexing
 
 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.
@@ -549,6 +648,8 @@ let results = Document.search(
 
 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.
@@ -651,6 +752,8 @@ await MyTable.put({ id: 'my-record', data: blob });
 
 Instructions for the agent to follow when storing and serving binary data (images, audio, arbitrary content types) 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 Harper resource needs to accept, store, or serve binary payloads such as images, audio files, or calendar data. Use it when clients send raw binary via `PUT`/`POST`, or when they send `base64`-encoded data inside a JSON body.
@@ -767,6 +870,8 @@ export class Photo extends tables.Photo {
 
 Instructions for the agent to follow when using Harper's automatically generated REST and WebSocket APIs for exported tables and resources.
 
+**Instead of:** Hand-written CRUD routes (Express, Fastify, Next.js API routes). Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for Harper tables and custom resources. Use it whenever you need to configure the REST plugin, understand the auto-generated endpoint surface, or wire up real-time WebSocket connections. See [querying-rest-apis.md](querying-rest-apis.md) for query syntax and [real-time-apps.md](real-time-apps.md) for real-time patterns.
@@ -958,30 +1063,25 @@ export class InternalLog extends Resource {
 - Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`; they are not affected by the `webSocket` option.
 - See [querying-rest-apis.md](querying-rest-apis.md) for full query syntax on collection endpoints and [real-time-apps.md](real-time-apps.md) for real-time subscription patterns.
 
-### 2.2 Querying REST APIs
+### 2.2 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                                |
    | -------------------- | -------------------------------------- |
@@ -1002,21 +1102,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                                    |
    | ----------------------------------------- | ------------------------------------------- |
@@ -1036,80 +1133,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
@@ -1117,32 +1217,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
@@ -1151,27 +1266,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 {
@@ -1182,29 +1291,31 @@ 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.
 
 ### 2.3 Real-Time Apps with WebSockets and Pub/Sub
 
 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.
@@ -1297,6 +1408,8 @@ export class Example extends Resource {
 
 Instructions for the agent to handle user authentication, sessions, and JWT token issuance in Harper Resources.
 
+**Instead of:** Hand-rolled sessions, `passport`, `jsonwebtoken`, `bcrypt`. Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Apply this rule when implementing login/logout flows, reading the current authenticated user, issuing or refreshing JWT tokens, or minting scoped tokens from a custom Resource. Use it whenever a Resource must gate behavior on identity or credentials. See [custom-resources.md](custom-resources.md) for the broader Resource authoring model.
@@ -1603,6 +1716,8 @@ curl --location --request POST 'http://localhost:9925' \
 
 Instructions for the agent to follow when defining custom REST endpoints with JavaScript or TypeScript in Harper.
 
+**Instead of:** Express, Fastify, or Koa route handlers; serverless functions. Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Apply this rule when you need to create custom HTTP endpoints, wrap external APIs, or register routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when you need fine-grained control over URL shape and path parameters.
@@ -1773,6 +1888,8 @@ server.resources.set('my-path', Foo);
 
 Instructions for the agent to follow when adding custom logic to automatically generated table resources in Harper.
 
+**Instead of:** Middleware and controllers wrapped around CRUD routes. Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Apply this rule when you need to override or augment the default HTTP handler behavior (GET, POST, PUT, PATCH, DELETE) for a Harper table resource. Use it when a table needs computed properties, input transformation, authorization checks, or custom error responses.
@@ -1867,149 +1984,155 @@ export class MyTable extends tables.MyTable {
 
 ### 3.3 Programmatic Table Requests
 
-Instructions for the agent to follow when interacting with Harper tables programmatically using the `tables` object.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
+
+**Instead of:** ORM and query-builder clients (Prisma, Drizzle, Knex). Use this rule rather than adding that service. See `harper-architecture`.
 
 #### When to Use
 
-Apply this rule when writing server-side Harper component code that reads from or writes to tables using the programmatic API — for example, in HTTP handlers, background jobs, timers, or SSR entry points. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, pagination, or transactions outside of the REST layer.
+Apply this rule when writing server-side Harper code that reads, writes, searches, or transactionally modifies table data through the `tables` object. Use it when building background jobs, SSR renderers, or any code that calls `search(`, `addTo`, `select`, `sort`, or `transaction()` directly rather than through REST endpoints.
 
 #### How It Works
 
-1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a property of `tables`. Each property is the table class implementing the Resource API.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. This is equivalent to `databases.data.<TableName>`.
 
    ```javascript
-   import { tables, transaction } from 'harper';
+   import { tables, Resource } from 'harper';
    const { Product } = tables;
    // same as: databases.data.Product
    ```
 
-   For components in their own directory, run:
+   CommonJS is also supported: `const { tables, Resource } = require('harper');`
+
+   For components in their own directory, link the package first:
 
    ```bash
    npm link harper
    ```
 
-   All installed components have `harper` automatically linked.
+   When bundling for SSR with Vite, keep `harper` external so it resolves to the runtime:
 
-2. **Define your schema with `@table`**: Every type you want to access via `tables` must carry the `@table` directive. Mark queryable fields with `@indexed`.
+   ```javascript
+   // vite.config
+   ssr: {
+   	external: ['harper'];
+   }
+   ```
+
+2. **Define your schema with `@table` (and `@indexed` where needed)**: Tables must be declared in `schema.graphql`. Mark attributes that will be used as sort keys or standalone condition attributes with `@indexed`.
 
    ```graphql
    type Product @table {
    	id: Long @primaryKey
    	name: String
-   	price: Float
+   	price: Float @indexed
    }
    ```
 
-3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable.
+3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable; iterate the result with `for await`. Use a `conditions` array to filter records. Each condition specifies `attribute`, `value`, and an optional `comparator`.
+
+   | Property     | Description                                                                                                                                                                         |
+   | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `attribute`  | Property name, or array for chained/joined properties                                                                                                                               |
+   | `value`      | The value to match                                                                                                                                                                  |
+   | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal`, or a full-text comparator |
+   | `conditions` | Nested conditions array                                                                                                                                                             |
+   | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                                                 |
 
    ```javascript
-   const query = {
+   for await (const record of Product.search({
    	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-   };
-   for await (const record of Product.search(query)) {
+   })) {
    	// process record
    }
    ```
 
-4. **Build `conditions`**: Each condition object supports the following properties:
+4. **Use `select` to control which properties are returned**: Pass an array of property names, a string for a single property, or nested objects for relationships.
+
+   ```javascript
+   const book = await Book.get({
+   	id: 42,
+   	select: ['id', 'title', { name: 'author', select: ['name'] }],
+   });
+   ```
 
-   | Property     | Description                                                                                                                                              |
-   | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | `attribute`  | Property name, or array for chained/joined properties (e.g. `['brand', 'name']`)                                                                         |
-   | `value`      | The value to match                                                                                                                                       |
-   | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal` |
-   | `conditions` | Nested conditions array                                                                                                                                  |
-   | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
+   Special `select` properties:
+   - `$id` — returns the primary key regardless of its name
+   - `$updatedtime` — returns the last-updated timestamp
+   - `$distance` — returns computed vector distance when using a vector index
+   - `$score` — returns BM25 relevance score for full-text queries
+   - `$highlights` — returns full-text fragments and matching spans
 
-5. **Apply `select` to shape results**: Pass an array of property names, a string for a single property, or nested objects for relationships.
+5. **Use `sort` with an `@indexed` attribute or combine with `conditions`**: Harper requires either an `@indexed` sort attribute or at least one `conditions` entry when sorting. Sorting by a non-indexed attribute with zero conditions raises:
 
-   ```javascript
-   // Flat select
-   Product.search({ select: ['name', 'price'] });
+   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
 
-   // Nested relationship select
-   Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
-   ```
+   Note: `@primaryKey` alone is treated as not indexed for sort purposes. To iterate a whole table in primary-key order, add an open-ended condition:
 
-   Special `select` values: `$id`, `$updatedtime`, `$distance`.
+   ```javascript
+   Product.search({
+   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+   	sort: { attribute: 'id' },
+   });
+   ```
 
-6. **Apply `sort`**: Harper uses an index to provide sort order.
+   `sort` object properties:
 
    | Property     | Description                                                |
    | ------------ | ---------------------------------------------------------- |
    | `attribute`  | Property name (or array for chained relationship property) |
    | `descending` | Sort descending if `true` (default: `false`)               |
    | `next`       | Secondary sort to resolve ties (same structure)            |
-   - If the sort `attribute` is `@indexed`, no condition is required.
-   - If the sort `attribute` is not indexed, at least one entry in `conditions` (on **any** attribute) is required.
-   - Sorting by a non-indexed attribute with zero conditions raises:
-     > `HdbError: <attribute> is not indexed and not combined with any other conditions`
-   - The bare `@primaryKey` is treated as not indexed for sort purposes. To iterate in primary-key order, add an open-ended condition:
-
-     ```javascript
-     Product.search({
-     	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
-     	sort: { attribute: 'id' },
-     });
-     ```
-
-   - Pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
 
-7. **Paginate with `limit` and `offset`**:
+6. **Apply `limit` and `offset` for pagination**: Add these to the Query object to bound result sets.
 
    ```javascript
-   Product.search({ conditions: [...], limit: 20, offset: 40 });
+   Product.search({
+   	conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
+   	limit: 20,
+   	offset: 40,
+   });
    ```
 
-8. **Debug with `explain` and `enforceExecutionOrder`**:
+7. **Use `explain` and `enforceExecutionOrder` for debugging and optimization**:
    - `explain: true` — returns conditions reordered as Harper will execute them.
    - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling Harper's automatic re-ordering.
 
-9. **Use `addTo` for concurrent-safe increments**: `addTo(property, value)` uses CRDT incrementation, safe across threads and nodes.
+8. **Use `addTo` for concurrent-safe numeric updates**: Increments or decrements a property using CRDT incrementation, safe across threads and nodes.
 
    ```javascript
    static async post(target, data) {
      const record = await this.update(target.id);
-     record.addTo('quantity', -1);
+     record.addTo('quantity', -1); // decrement safely across nodes
    }
    ```
 
-10. **Wrap background work in `transaction()`**: Harper auto-starts transactions for HTTP handlers. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural transaction context.
+9. **Wrap background or timer work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural request context. Always `await` the call and `catch` errors.
 
-    ```javascript
-    await transaction(async (txn) => {
-    	for (let item of data) {
-    		await MyTable.put(item, txn);
-    	}
-    });
-    ```
-
-    The `txn` object exposes:
-
-    | Member                | Type            | Description                                            |
-    | --------------------- | --------------- | ------------------------------------------------------ |
-    | `commit()`            | `() => Promise` | Commits the current transaction                        |
-    | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
-    | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
-    | `timestamp`           | `number`        | Timestamp associated with the current transaction      |
+   ```javascript
+   await transaction(async (txn) => {
+   	for (let item of data) {
+   		await MyTable.put(item, txn);
+   	}
+   });
+   ```
 
-    On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
+   The `txn` object exposes:
 
-11. **Understand atomicity**: Transactions span a single database. All tables within the same database share one transactional context — reads return a consistent snapshot and writes across multiple tables commit atomically. Cross-database operations get separate transactions with no cross-database atomicity guarantee.
+   | Member                | Type            | Description                                            |
+   | --------------------- | --------------- | ------------------------------------------------------ |
+   | `commit()`            | `() => Promise` | Commits the current transaction                        |
+   | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
+   | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
+   | `timestamp`           | `number`        | Timestamp associated with the current transaction      |
 
-12. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
+   On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
 
-    ```javascript
-    // vite.config
-    ssr: {
-    	external: ['harper'];
-    }
-    ```
+10. **Understand atomicity boundaries**: All tables within the same database share a single transactional context — reads return a consistent snapshot and writes are committed atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
 
 #### Examples
 
-**Full CRUD flow:**
+##### Basic CRUD and search
 
 ```javascript
 import { tables } from 'harper';
@@ -2025,14 +2148,15 @@ await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) /
 const record = await Product.get(created.id);
 
 // Search with conditions
-for await (const record of Product.search({
+const query = {
 	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-})) {
+};
+for await (const record of Product.search(query)) {
 	// process record
 }
 ```
 
-**Nested conditions with `or`:**
+##### Nested conditions with `or`
 
 ```javascript
 Product.search({
@@ -2049,13 +2173,32 @@ Product.search({
 });
 ```
 
-**Chained attribute reference (join):**
+##### Chained attribute reference (join/relationship)
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-**Background job with `transaction()`:**
+##### Selecting and constraining related records
+
+```javascript
+const brand = await Brand.get({
+	id: 42,
+	select: [
+		'id',
+		{
+			name: 'products',
+			conditions: [{ attribute: 'price', comparator: 'greater_than_equal', value: 30 }],
+			sort: { attribute: 'price' },
+			offset: 0,
+			limit: 1,
+			select: ['id', 'price'],
+		},
+	],
+});
+```
+
+##### Background job with `transaction()`
 
 ```javascript
 import { isMainThread } from 'node:worker_threads';
@@ -2065,7 +2208,7 @@ const { MyTable } = tables;
 if (isMainThread) {
 	let running = false;
 	setInterval(async () => {
-		if (running) return;
+		if (running) return; // the previous run has not committed yet
 		running = true;
 		try {
 			let data = await (await fetch('https://example.com/data')).json();
@@ -2079,11 +2222,11 @@ if (isMainThread) {
 		} finally {
 			running = false;
 		}
-	}, 3600000);
+	}, 3600000); // every hour
 }
 ```
 
-**SSR with Harper data:**
+##### SSR with Vite
 
 ```typescript
 import { tables } from 'harper';
@@ -2094,19 +2237,28 @@ export async function render(url: string): Promise<string> {
 }
 ```
 
+Keep `harper` external in `vite.config` so it resolves to the runtime:
+
+```javascript
+ssr: {
+	external: ['harper'];
+}
+```
+
 #### Notes
 
-- `tables` and `databases` calls run in a trusted server-side context and do **not** automatically apply the target table's role permissions.
-- Programmatic `update`, `patch`, and `delete` calls operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
-- If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — making it safe to call defensively.
-- Always `await` the `transaction()` call and `catch` errors when outside a request context; an unawaited call means a failed write is never observed.
-- Guard against timer overlap: if a job can outlast its interval, use a `running` flag to skip a tick rather than opening two transactions over the same rows.
-- CommonJS is also supported: `const { tables, Resource } = require('harper');`
+- Calls through `tables` run in a trusted server-side context and do **not** automatically apply the target table's role permissions. Set `checkPermission: true` on the query and pass the authenticated `context` as the second argument when authorization is required.
+- `update`, `patch`, and `delete` operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
+- Pass `allowFullScan: true` to permit an unconditional ordered scan without conditions. If order doesn't matter, omit `sort` entirely — `search({})` iterates without an index requirement.
+- If `transaction()` is called with a context that already has an active transaction, it reuses that transaction and executes the callback immediately — safe to call defensively.
+- Guard timer-based jobs against overlap: a timer fires on schedule regardless of whether the previous run has committed. Use a `running` flag to skip a tick when the previous run is still active.
 
 ### 3.4 TypeScript Type Stripping in Harper
 
 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.
@@ -2161,6 +2313,8 @@ jsResource:
 
 Instructions for the agent to implement integrated data caching from external sources using Harper's cache table directives and `sourcedFrom` API.
 
+**Instead of:** Redis or Memcached cache-aside layers. Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 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.
@@ -2320,11 +2474,13 @@ await fetch('http://localhost:9926/JokeCache/1', {
 
 ### 4.1 Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying a Harper application to a Harper Fabric cluster, or any remote Harper instance, with the `harper` CLI, and when checking, staging, or going back to a release.
+Instructions for the agent to deploy a Harper application to Harper Fabric using the CLI, verify certification, and roll back using a previous release's `deployment_id`.
+
+**Instead of:** Docker Compose stacks; deploying several services separately. Use this rule rather than adding that service. See `harper-architecture`.
 
 #### When to Use
 
-Apply this rule when deploying to a remote cluster, choosing how it restarts, reading a deploy's `certification`, staging a release to make live later, or rolling back to a previous release. To deploy from CI with no stored credential, see [deploying-from-ci.md](deploying-from-ci.md). To set up the cluster first, see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md).
+Apply this rule when deploying a Harper application to a remote Harper Fabric cluster, checking whether a rolling deploy was certified on each node, or restoring a previous release without rebuilding. Also apply it when provisioning credentials for private-source deploys or staging a build for later activation.
 
 #### How It Works
 
@@ -2335,10 +2491,9 @@ Apply this rule when deploying to a remote cluster, choosing how it restarts, re
    # Provide cluster username and password when prompted
    ```
 
-   - For CI/CD on GitHub Actions, use workload identity (OIDC) instead, so the pipeline stores no Harper credential. From v5.4.0, `harper deploy setup=true provider=github-actions` sets it up in one command: see [deploying-from-ci.md](deploying-from-ci.md). Elsewhere, give the pipeline a refresh token from `harper login --for-ci` rather than a password.
-   - For a one-off command, `auth_username=` and `auth_password=` also work, and take precedence over environment variables and saved login tokens. Don't use them in production.
+   For CI/CD pipelines, use workload identity (OIDC) or a refresh token from `harper login --for-ci` instead of a password. See [deploying-from-ci.md](deploying-from-ci.md) for a complete GitHub Actions workflow. For a one-off command, `auth_username=` and `auth_password=` also work, and take precedence over environment variables and saved login tokens. Don't use them in production.
 
-2. **Deploy with a restart**: Run `harper deploy`, with `restart=true` or `restart=rolling` so the release is certified before it serves (step 3).
+2. **Deploy the application**: Run `harper deploy` with the required parameters. Omit `package` to upload the current directory; supply a reference for npm, GitHub, or tarball sources.
 
    ```bash
    harper deploy \
@@ -2349,54 +2504,38 @@ Apply this rule when deploying to a remote cluster, choosing how it restarts, re
      replicated=true
    ```
 
-   - On Harper Pro and Fabric, a deploy goes to every node in the cluster unless you pass `replicated=false`. Harper core on its own does not replicate.
-   - `project` defaults to the current directory's name for a directory deploy, or is derived from the package for a package deploy.
-   - A bare `target` host defaults to `https://<host>:9925`.
-   - Pass `json=true` to print the result as JSON instead of YAML.
-   - Every result carries a `deployment_id`, staged or not. It names this release when you go back to it later (step 4).
+   A bare `target` host defaults to `https://<host>:9925`. Use `restart=rolling` for a staggered, zero-downtime restart across the cluster. Pass `replicated=false` to deploy only to the node you called. Pass `json=true` to print the result as JSON instead of YAML.
 
-3. **Choose the restart, and read `certification`**: `restart=true` restarts Harper after deploying. On a cluster, use `restart=rolling`, the staggered, zero-downtime restart: the command exits `0` once the node you called has taken the release and started the rolling restart's job, and returns its `restartJobId`.
+3. **Choose a package source**: The `package` field accepts any valid npm dependency value.
 
-   Both certify the release in a canary worker before rolling it out. The canary replaces worker 0 and loads every component, but is held out of traffic until it reports whether the deployed component loaded. Until then, the workers already running keep serving the previous release. A deploy that succeeds, and is not staged, reports the result in `certification`:
+   | Source             | Value                                                                                         |
+   | ------------------ | --------------------------------------------------------------------------------------------- |
+   | npm package        | `package="@harperdb/status-check"`                                                            |
+   | GitHub (public)    | `package="HarperFast/status-check"` or `package="https://github.com/HarperFast/status-check"` |
+   | Private repo (SSH) | `package="git+ssh://git@github.com:HarperDB/secret-app.git"`                                  |
+   | Tarball            | `package="https://example.com/application.tar.gz"`                                            |
 
-   | `certification` | Meaning                                                                                                                                                                                             |
-   | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | `certified`     | The canary loaded the release, and the rollout went on.                                                                                                                                             |
-   | `uncertified`   | The rollout went on unchecked: the component ran nothing as it loaded (`loadComponent: dev-only`, an absent `if-installed` component, or safe mode), or no worker was replaced.                     |
-   | `unavailable`   | The deploy restarted unchecked: no worker on this node loads the component, its `isolated` setting changed, it was already live, or it was deployed from a local directory (`package: file:<dir>`). |
-   | `not-requested` | The deploy did not restart.                                                                                                                                                                         |
-   - **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes. The error's `certification` is an object whose `status` is `rejected`, or `interrupted` for a restart that stopped before the canary decided.
-   - **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed. Deploy a fix, or once the cause is fixed, activate the same `deployment_id` again with `restart`.
-   - **A rolling deploy exits before every node has taken the release.** The other nodes stage it, and the job activates it on each in turn, each with a canary of its own. A node that rejects it keeps the previous release, or fails closed if it had none. Nothing is rolled back on the others, and the job fails naming each node that did not activate it. The deployment record reports `success` while the job runs and after it fails, so poll the job instead: `harper get_job id=<restartJobId>` ends `COMPLETE`, or `ERROR` with a `message` listing each node's outcome under `activated`.
-   - **Poll the node that received the deploy.** A job is recorded only on the node that ran it, so any other node answers `get_job` with an empty array. A role with an `operations` allowlist, or a token with an `operations` scope, must list `get_job` to poll it.
-   - Another deploy or `drop_component` of the component on that node is refused with `409` until the rollout has finished.
-   - A node running a version before v5.4.0 activates the release without a canary.
+   For git tags, use the `semver` directive: `HarperFast/application-template#semver:v1.0.0`. For an SSH-based private repo, register the key with `add_ssh_key` first.
 
-4. **Go back to a previous release by its `deployment_id`**: When a deploy replaces the live release, Harper keeps the replaced one under the `deployment_id` that deployed it. Activating that id puts back the exact installed release with no fetch, rebuild, or reinstall, where deploying an older commit installs it again from source. Find the id with `list_deployments`, then deploy it. On a cluster, restart with `rolling` and poll its job (step 3):
+4. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source. (With `provider=github-actions`, it sets up GitHub Actions OIDC deploys instead.) This requires `super_user` privileges and is interactive. It calls `get_secrets_public_key`, `set_secret`, and `grant_secret`. Run it with an administrative credential rather than the CI identity it provisions for:
 
    ```bash
-   harper list_deployments project=my-app status=success
-   harper deploy project=my-app deployment_id=<id> restart=rolling
+   harper deploy setup=true
    ```
 
-   ```json
-   {
-   	"operation": "deploy_component",
-   	"project": "my-app",
-   	"deployment_id": "<id of the deployment you want back>",
-   	"restart": "rolling"
-   }
-   ```
+   The command:
+   1. Fetches the cluster's public key with `get_secrets_public_key`.
+   2. Encrypts the token locally into an `enc:v1:` envelope.
+   3. Stores only the ciphertext with `set_secret`, scoped to the component, never in the global `processEnv` tier.
+   4. Grants the component permission to resolve it with `grant_secret`.
 
-   - `list_deployments` returns records newest first. Filter by `project` and `status`; omit `limit` to return every matching record. A deploy in progress reads `pending`, or `loading`, until its `completed_at` is set.
-   - The newest `success` is not necessarily the release every node is serving: a rolling deploy's record says `success` before the other nodes have taken the release, and keeps saying it if one rejects it.
-   - Redeploy an older commit by `ref` (step 7) only when the release is no longer kept.
-   - The activation restores the root config entry that deployment published. The release it replaces is kept in turn, so you can go forward again the same way.
-   - Kept releases and staged builds count against `deployment.stagingRetention.maxCount` (default `5`). Each kept release is a full installed copy of the component, `node_modules` included, so budget disk for it. `0` keeps no replaced release.
-   - A release made live before v5.3.0, or deployed from a `file:` directory, is not kept.
-   - Each node answers for itself. A node that never had the release, or no longer keeps it, answers `404`, which `deploy_component` reports as a failed peer. `409` means the build is there but can't be activated.
+   Use a **fine-grained** personal access token with **Contents: Read-only** on the target repository. Avoid broad tokens: the `gh` CLI session token typically carries `read:org`, `gist`, and `workflow` scopes across your whole account. Then deploy with `credential=true`:
+
+   ```bash
+   harper deploy by_ref=true credential=true restart=true replicated=true
+   ```
 
-5. **Stage a release to make live later**: `activate=false` (`activate: false` in the operation) builds and installs the release on each node without making it live, so the slow, fallible part happens when you choose and the cut-over is quick. The result's `deployment_id` names the staged build:
+5. **Stage a release to make live later**: `activate=false` (`activate: false` in the operation) builds and installs the release on each node without making it live, so the slow, fallible part happens when you choose and the cut-over is quick. Cannot be combined with `restart`.
 
    ```json
    {
@@ -2407,6 +2546,8 @@ Apply this rule when deploying to a remote cluster, choosing how it restarts, re
    }
    ```
 
+   The response names the artifact waiting to be activated:
+
    ```json
    {
    	"deployment_id": "a3f8c2d1-...",
@@ -2414,147 +2555,214 @@ Apply this rule when deploying to a remote cluster, choosing how it restarts, re
    }
    ```
 
-   Make it live by deploying that `deployment_id`, as in step 4. Nothing changes until then, and `get_deployment` reports it as `staged`.
-   - Pass `restart` on the activation, not the stage: `restart` is rejected alongside `activate: false`.
-   - The activation takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host`. They are rejected, because the staged build already decided them.
-   - Activating the release that is already live succeeds without a swap, so if an activation fails partway (a peer was unreachable, or the root config entry wasn't written), retry the same `deployment_id`. A node that already switched answers success, one still holding the build switches now, and one that holds neither answers `404`; the retry also finishes what the failed attempt left half done. With `restart`, a node where the release is already live still restarts every worker, isolated applications' included. Without it, the node marks the component as needing a restart.
-   - A staged build outlives later deploys: stage v2, deploy v3, and activating v2's id returns the component to v2.
-   - `file:` directory sources cannot be staged.
-   - Upgrade every node before staging. A node before v5.3.0 doesn't recognize `activate: false`, and serves the release immediately. A peer that doesn't confirm staging fails the operation with the node names.
+   Nothing about the running component changes, and `get_deployment` reports it as `staged`. Make it live by deploying that `deployment_id`, as in step 6. The activation takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host`. They are rejected, because the staged build already decided them.
 
-6. **Choose a package source**: The `package` field accepts any valid npm dependency value:
+6. **Activate a staged build or roll back**: Pass `deployment_id` with `restart` to make a staged build live, or to restore a release a later deploy replaced, with no rebuild or reinstall. Pass `restart` here rather than on the stage.
 
-   | Source                  | `package` value                                                                               |
-   | ----------------------- | --------------------------------------------------------------------------------------------- |
-   | Current local directory | Omit `package`                                                                                |
-   | npm package             | `package="@harperdb/status-check"`                                                            |
-   | GitHub (public)         | `package="HarperFast/status-check"` or `package="https://github.com/HarperFast/status-check"` |
-   | Private repo (SSH)      | `package="git+ssh://git@github.com:HarperDB/secret-app.git"`                                  |
-   | Tarball                 | `package="https://example.com/application.tar.gz"`                                            |
+   ```bash
+   harper deploy project=<name> deployment_id=<id> restart=true
+   ```
 
-   For git tags, use the `semver` directive: `HarperFast/application-template#semver:v1.0.0`. For an SSH-based private repo, register the key with `add_ssh_key` first.
+   Use `list_deployments` to find the `deployment_id` of the release to restore:
 
-7. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`. Pass `ref` to deploy a specific tag or commit instead of `HEAD`; it implies `by_ref`.
+   ```json
+   { "operation": "list_deployments", "project": "my-app", "status": "success", "limit": 20 }
+   ```
+
+   - A `404` response means the id never existed on that node, was pruned, or the release was replaced and not kept. A `409` means the build exists but cannot be activated (e.g., belongs to another component, or files changed after staging).
+   - Kept releases and staged builds count against `deployment.stagingRetention.maxCount` (`stagingRetention` default: `5`). Each kept release is a full installed copy of the component, `node_modules` included, so budget disk for it. `0` keeps no replaced releases.
+
+7. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`. Defaults to `HEAD`.
 
    ```bash
    harper deploy by_ref=true restart=true replicated=true
+   ```
+
+   Deploy a specific tag or commit with `ref`:
+
+   ```bash
    harper deploy ref=v1.2.0 restart=true replicated=true
    harper deploy ref=9f8c2a1 restart=true replicated=true
    ```
 
-   - A `ref` is resolved to a full commit SHA before the deploy is sent, from the local checkout or the remote. A full commit SHA is accepted directly. If a `ref` can't be resolved, the deploy stops: run `git fetch` and retry, or pass a full SHA.
+   - Tags and branches are resolved to a full commit SHA before the deploy is sent. A `ref` that cannot be resolved stops the deploy — run `git fetch` and retry, or pass a full commit SHA.
    - Any other `ref` must name something a clone can fetch: `refs/heads/*` or `refs/tags/*`, or a bare branch or tag name. A qualified ref outside those, such as `refs/pull/123/head`, is rejected up front.
-   - Commit and push first: the cluster clones from the remote. `by_ref` warns when the working tree is dirty, and when the commit isn't on any remote branch. The second check is skipped under GitHub Actions.
    - On a GitHub Actions `pull_request` run, `by_ref` deploys the pull request's head commit. If the event payload isn't readable, the deploy stops; pass the commit explicitly.
-   - The cluster installs and builds from source on each node, so commit your lockfile if the build must be reproducible. If the build can't run on the node, deploy the built output as a payload instead.
+   - Commit and push first — the cluster clones from the remote and only sees pushed commits.
+
+8. **Check certification after a rolling deploy**: A deploy with `restart=rolling` certifies the release in a canary worker before rolling it out. The deploy response includes a `certification` field:
+
+   | `certification` | Meaning                                                                                                                                                                         |
+   | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `certified`     | The canary loaded the release; rollout proceeded.                                                                                                                               |
+   | `uncertified`   | The rollout went on unchecked: the component ran nothing as it loaded (`loadComponent: dev-only`, an absent `if-installed` component, or safe mode), or no worker was replaced. |
+   | `unavailable`   | Deploy restarted unchecked (no worker loads the component, `isolated` setting changed, already live, or `file:` directory source).                                              |
+   | `not-requested` | The deploy did not restart.                                                                                                                                                     |
+   - **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes. The error carries the decision as an object in `certification` with `status` set to `rejected`, or to `interrupted` for a restart that stopped before the canary decided.
+   - **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed and says why. Deploy a fix, or activate the same `deployment_id` again with `restart`.
+   - Another deploy or `drop_component` of the component on that node is refused with `409` until the rollout has finished.
 
-8. **Deploy a private repository by reference**: Pass `credential=true` with `by_ref=true`. The CLI attaches a `credentials` reference, and the cluster resolves the secret in memory at clone time, so no token travels in the operation body or lands on disk.
+9. **Wait for a rolling deploy to finish**: A `deploy_component` with `"restart": "rolling"` returns a `restartJobId`. Poll it with `get_job` to learn whether every node took the release.
 
-   ```bash
-   harper deploy by_ref=true credential=true restart=true replicated=true
+   ```json
+   { "operation": "get_job", "id": "4a982782-929a-4507-8794-26dae1132def" }
    ```
 
-   Provision that credential once per component and source with `harper deploy setup=true`. (With `provider=github-actions`, it sets up GitHub Actions deploys instead: see [deploying-from-ci.md](deploying-from-ci.md).) It is interactive, and its operations require **super_user**, so run it with an administrative credential, not the CI identity it provisions for. It:
-   1. Fetches the cluster's public key with `get_secrets_public_key`.
-   2. Encrypts the token locally into an `enc:v1:` envelope, so the plaintext never leaves your machine.
-   3. Stores only the ciphertext with `set_secret`, scoped to the component, never in the global `processEnv` tier.
-   4. Grants the component permission to resolve it with `grant_secret`.
-   5. Prints the `credentials` reference for the deploy to use.
-
-   Use a **fine-grained** personal access token with **Contents: Read-only** on that one repository. Avoid the `gh` CLI's session token: it typically carries `repo`, `read:org`, `gist`, and `workflow` scopes across your whole account. The sealed token is durable, and later deploys reuse it.
+   `get_job` returns status `COMPLETE`, `IN_PROGRESS`, or `ERROR`. It answers only on the node that ran the job. A deploy-only role that waits for rolling deploys must include `get_job` in its operations allowlist.
+   - `list_deployments` returns records newest first. Filter by `project` and `status`; omit `limit` to return every matching record. A deploy in progress reads `pending`, or `loading`, until its `completed_at` is set.
 
 #### Examples
 
-**Deploy after logging in, and wait for a rolling restart:**
+##### Full rolling deploy from a pinned tag
 
 ```bash
+# Authenticate once
 harper login https://my-cluster.harperdbcloud.com
+
+# Deploy a pinned release with rolling restart
 harper deploy \
   project=my-app \
-  package="HarperFast/my-app" \
+  ref=v1.2.0 \
   target=https://my-cluster.harperdbcloud.com \
   restart=rolling \
-  json=true > deploy.json
-# Poll the node that received the deploy until the job is COMPLETE or ERROR
-harper get_job id=<restartJobId from deploy.json> json=true
+  replicated=true
 ```
 
-**Roll back to the release a deploy replaced, node by node:**
+##### Stage a build, then activate in a maintenance window
 
-```bash
-harper list_deployments project=my-app status=success
-harper deploy project=my-app deployment_id=<previous deployment_id> restart=rolling json=true
-# Then poll its restartJobId with get_job, as above
+```json
+{
+	"operation": "deploy_component",
+	"project": "my-app",
+	"package": "npm:@my-org/my-app@1.2.3",
+	"activate": false
+}
 ```
 
-**Stage a release now, and make it live in a maintenance window:**
+Response:
 
-```bash
-harper deploy project=my-app package=npm:@my-org/my-app@1.2.3 activate=false
-# Later, with the deployment_id the stage returned
-harper deploy project=my-app deployment_id=<staged deployment_id> restart=rolling
+```json
+{
+	"deployment_id": "a3f8c2d1-...",
+	"message": "Staged: my-app. Deploy it with deploy_component deployment_id=a3f8c2d1-..."
+}
 ```
 
-**Deploy a pull request's head commit by reference in GitHub Actions:**
+Activate later:
 
-```bash
-harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
+```json
+{
+	"operation": "deploy_component",
+	"project": "my-app",
+	"deployment_id": "a3f8c2d1-...",
+	"restart": true
+}
 ```
 
-**Deploy a private repository by reference:**
+##### Roll back to a previous release
 
-```bash
-# Once, as super_user
-harper deploy setup=true
+```json
+{
+	"operation": "list_deployments",
+	"project": "my-app"
+}
+```
+
+Then:
 
-# Every deploy
-harper deploy by_ref=true credential=true restart=true replicated=true
+```json
+{
+	"operation": "deploy_component",
+	"project": "my-app",
+	"deployment_id": "<id of the deployment you want back>",
+	"restart": true
+}
 ```
 
+##### Rejected canary — error response shape
+
+```json
+{
+	"error": "my-app was not deployed: release 9b2e... failed to load in its canary worker: my-app.jsResource: ... Deployment a3f8c2d1..., the release it replaced, is live again. No other node received it. Deploy a fix, or activate deployment 9b2e... again once the cause is fixed.",
+	"deployment_id": "9b2e...",
+	"certification": {
+		"status": "rejected",
+		"reason": "my-app.jsResource: ...",
+		"failures": [
+			{ "key": "my-app.jsResource", "name": "ResourceLoadError", "message": "...", "stack": "..." }
+		],
+		"restored": "a3f8c2d1...",
+		"failed_closed": false
+	}
+}
+```
+
+#### Notes
+
+- `harper login` stores a token; subsequent `harper deploy` calls to the same target need no credentials. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for cluster setup.
+- For GitHub Actions, prefer OIDC workload identity over stored tokens. See [deploying-from-ci.md](deploying-from-ci.md).
+- `restart=rolling` and `activate=false` cannot be combined.
+- `deployment_id` activation takes no `package`, `payload`, `credentials`, install options, `urlPath`, or `host` — supplying them is rejected.
+- `file:` directory sources (`package: file:<dir>`) cannot be staged and are not kept as rollback targets.
+- `stagingRetention.maxCount` (default `5`) caps staged builds and kept replaced releases together per component.
+- `get_job` on a `restartJobId` answers only on the node that received the deploy; any other node returns an empty array.
+- A rolling deploy's record reads `rolling_out` until the job has visited every node; filter `list_deployments` without `status` and check each record's `status` for a finished value (`success`, `partial`, `failed`, `staged`). `completed_at` alone does not confirm a finished state, since a `rolling_out` record already has it.
+- `enc:v1:` envelopes store only ciphertext — plaintext never leaves your machine and never appears in operation logs or replication.
+- Tags used in `refs/tags` are resolved to a commit SHA before the deploy is sent; a tag that moves mid-deploy cannot cause nodes to run different code.
+- `super_user` is required to run `harper deploy setup=true`.
+
 ### 4.2 Deploying a Harper Application from GitHub Actions with OIDC
 
-Instructions for the agent to configure and execute credential-free Harper deployments from GitHub Actions using OIDC trusted publishing, including one-command setup and complete workflow examples.
+Instructions for the agent to configure and use OIDC trusted publishing so a GitHub Actions workflow can deploy to Harper with no stored credential.
 
 #### When to Use
 
-Apply this rule when asked to deploy from CI, to set up or fix a deploy workflow (including the `.github/workflows/deploy.yaml` that create-harper projects ship), or to move a pipeline off a stored Harper credential such as `HARPER_CLI_REFRESH_TOKEN`. Use it when setting up OIDC trust for the first time, writing or debugging a deploy workflow, or revoking/rotating pipeline access.
+Apply this rule when wiring up a GitHub Actions workflow to deploy a Harper application without storing a `HARPER_CLI_REFRESH_TOKEN` or any other durable credential in CI. Use it both for the one-command setup path (branch-triggered deploys) and for the manual policy path (tag-triggered releases). Also apply it when diagnosing a rejected OIDC exchange or revoking pipeline access.
 
 #### How It Works
 
-##### One-Command Setup (Branch-Based Deploys)
+##### One-Command Setup (branch-triggered deploys)
 
-1. **Run setup once** from the project checkout, signed in as a `super_user`:
+1. **Run setup once** from the project's checkout, signed in as a `super_user`:
 
    ```bash
-   harper login https://my-cluster.example.com:9925
    harper deploy setup=true provider=github-actions project=my-app
    ```
 
-   If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=` explicitly — otherwise the policy pins `deploy.yaml` and runs of your workflow cannot match it:
+   If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=`:
 
    ```bash
    harper deploy setup=true provider=github-actions project=my-app workflow=.github/workflows/deploy.yml
    ```
 
-2. **Understand what setup does** — in order:
-   - Resolves the GitHub repository's numeric id and canonical name from the `origin` remote (or `repo=<owner>/<name>`). Pass `repository_id=<id>` when the API is unavailable (e.g., private repo without `gh`).
-   - **The workflow is checked before anything is written.** It must be able to run on `main` (`branch=`) and run a job in the `production` environment (`environment=`) with `permissions: id-token: write`; one that never could stops setup. What it can't decide is reported as not verified.
-   - Creates a role and a user named `<project>-ci-deploy` with permissions limited to `deploy_component`, `get_job`, and `registration_info`, and a trust policy named `github-actions-<project>`.
-   - Reads the policy back and compares it claim by claim with what it intended to write.
-   - Sets the repository's `HARPER_CLI_TARGET` Actions variable via `gh` if one does not already exist.
+2. **Understand what setup does** — it executes these steps automatically:
+   - Resolves the GitHub repository's numeric `repository_id` from the `origin` remote (or `repo=<owner>/<name>`). Pass `repository_id=<id>` explicitly for private repos without `gh`.
+   - Validates the workflow file: it must be able to run on `main` (or `branch=`), run a job in the `production` environment (`environment=`), and grant `id-token: write`. Setup stops before writing anything if the workflow could never match or never request a token.
+   - Creates a role and a user named `<project>-ci-deploy` with permissions limited to `deploy_component`, `get_deployment`, `get_job`, and `registration_info`, plus the trust policy `github-actions-<project>`.
+   - Reads the policy back and compares it claim by claim.
+   - Sets the repository's `HARPER_CLI_TARGET` variable via `gh` if one does not already exist.
 
-3. **Handle idempotency**: setup only creates — it never updates. A role, user, or policy that already exists but differs stops setup and names what differs. To replace a policy:
+3. **Handle idempotency**: setup only creates — it never overwrites. A role, user, or policy that already exists but differs stops setup before writing. To replace a policy:
 
    ```bash
    harper drop_oidc_trust id=github-actions-<project>
-   harper deploy setup=true provider=github-actions project=my-app
    ```
 
-##### Manual Setup (Tag-Based or Custom Deploys)
+   Then run setup again.
 
-Use this path when deploying on version tags, because a branch-pinned policy cannot match a tag ref.
+---
 
-1. **Create a deploy-only role and user**:
+##### Manual Setup (tag-triggered deploys)
+
+Use this path when the workflow deploys on version tags, because a branch pin cannot match a tag ref.
+
+1. **Log in as `super_user`**:
+
+   ```bash
+   harper login https://my-cluster.example.com:9925
+   ```
+
+2. **Create a deploy-only role and user** named `<project>-ci-deploy`:
 
    ```bash
    harper add_role role=ci_deploy permission='{"operations":["deploy_component","get_job","get_deployment","registration_info"]}'
@@ -2562,12 +2770,12 @@ Use this path when deploying on version tags, because a branch-pinned policy can
    ```
 
    - `deploy_component` — the deploy itself.
-   - `get_job` — required for the wait step; an `operations` allowlist refuses anything not listed, so without it the wait step fails with `403`.
-   - `get_deployment` — reads the deployment record.
-   - `registration_info` — version check `harper deploy` makes before uploading.
+   - `get_deployment` — required for `harper deploy restart=rolling` to wait on every node; without it that wait fails with `403`.
+   - `get_job` — required for the wait step; without it the wait step fails with `403`.
+   - `registration_info` — version check before upload; omitting it logs a refused operation on every run.
    - `restart_service` is not needed: Harper starts the rolling restart's job itself. The password is required to create the user but a GitHub Actions pipeline never uses it, so this command discards it.
 
-2. **Add a trust policy** pinned to `repository_id`, `workflow_path`, and `environment` (use this shape when the tag is unknown at policy-write time):
+3. **Add a trust policy** pinning `repository_id`, `workflow_path`, and `environment` (use this shape for tag-triggered workflows where `workflow_ref` cannot be pinned):
 
    ```bash
    harper add_oidc_trust \
@@ -2579,45 +2787,40 @@ Use this path when deploying on version tags, because a branch-pinned policy can
    ```
 
    Key claim rules:
-   - `repository_id` is immutable — survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
-   - `workflow_path` pins the workflow file. Harper derives it from the token's `workflow_ref` by removing the `@<ref>` suffix, so it is `<owner>/<repo>/<path>`.
+   - `repository_id` is immutable and survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
+   - `workflow_path` is derived from `workflow_ref` by removing the `@<ref>` suffix; format is `<owner>/<repo>/<path>`.
    - `environment` is the ref gate. Without it, anyone who can push a branch can mint a token.
    - `audience` must be the exact target URL with its port and a **trailing slash**.
    - A workflow that deploys on a push to `main` can pin `workflow_ref` (`my-org/my-app/.github/workflows/deploy.yml@refs/heads/main`) instead, which gates the ref by itself.
 
-3. **Configure the GitHub environment**: in **Settings → Environments → production**, set **Deployment branches and tags** to the `v*` tag pattern. Add required reviewers if a release needs approval.
+4. **Configure the GitHub environment**: in **Settings → Environments → production**, set **Deployment branches and tags** to the `v*` tag pattern. Add required reviewers if a release needs approval.
 
-4. **Store the target as a repository variable** (not a secret — it is not sensitive):
+5. **Store the target as a repository variable** (not a secret):
 
    ```bash
    gh variable set HARPER_CLI_TARGET --repo my-org/my-app --body https://my-cluster.example.com:9925/
    ```
 
+---
+
 ##### How OIDC Authentication Works in the Workflow
 
-Once a trust policy exists, every `harper` command in the deploy job authenticates through it automatically when all four conditions hold:
+A job authenticates automatically when all four conditions hold:
 
-1. **The job may request an identity token.** On GitHub Actions that is `permissions: id-token: write` on the job.
-2. **`HARPER_CLI_TARGET` is the policy's `audience`.** The CLI requests its token for the target it connects to, so the target must be the URL the policy names, with its port and trailing slash. Use `vars.HARPER_CLI_TARGET` — it is not sensitive, so a repository variable rather than a secret.
-3. **The run matches the policy's claims**: its repository, its workflow file and branch, and its environment.
+1. **The job declares `permissions: id-token: write`.**
+2. **`HARPER_CLI_TARGET` is the policy's `audience`.** The CLI requests its token for the target it connects to, so the target must be the URL the policy names, with its port and trailing slash. It is not sensitive, so use `vars.HARPER_CLI_TARGET` rather than a secret.
+3. **The run matches the policy's claims**: its `repository_id`, `workflow_path`/`workflow_ref`, and `environment`.
 4. **Nothing else is configured to authenticate.** `auth_username=`/`auth_password=`, credentials in the target URL, `HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`, `HARPER_CLI_REFRESH_TOKEN` or `HARPER_CLI_OPERATION_TOKEN`, and a saved `harper login` all outrank the exchange.
 
-What each command may then do is up to the role of the user the policy names: a role that lists only `deploy_component`, `get_job` and `registration_info`, like the one setup creates, refuses anything else with a `403`.
+Nothing in the workflow names the policy. Every `harper` command in the job (`harper deploy`, `harper get_job`, etc.) authenticates through it automatically.
 
 The exchange runs only when GitHub sets `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, which it does for a job that declares `permissions: id-token: write`. Without them, the CLI falls through to its other credential sources rather than reporting a failure.
 
-Nothing in the workflow names the policy. The CLI prints to stderr which policy authenticated it and as whom:
-
-```
-Requesting a GitHub Actions identity token for https://my-instance.harperdb.io:9925/...
-Authenticated as 'ci-deploy' via OIDC trust policy 'my-app-prod'.
-```
-
-Diagnose a rejected exchange with `list_oidc_trust` (check for `invalid_reason` on each entry) and the instance's `oidc-trust` log. The server deliberately does not report which check failed.
+---
 
 ##### Policy Specificity for GitHub Actions
 
-For `https://token.actions.githubusercontent.com`, a policy must satisfy all three of these:
+For `issuer=https://token.actions.githubusercontent.com`, every policy must satisfy all three requirements:
 
 | Requirement            | Satisfied by one of                                                      | Left open otherwise                             |
 | ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
@@ -2627,21 +2830,68 @@ For `https://token.actions.githubusercontent.com`, a policy must satisfy all thr
 
 Additional constraints:
 
-- `repository_id` is preferred over `repository` — it is immutable and survives renames.
-- A tag-triggered release cannot pin `workflow_ref` since the tag is unknown when the policy is written. Pin `workflow_path` and gate on `environment`.
 - `ref_type: tag` is not accepted as a ref gate, `sub` is not accepted as a pin, and `job_workflow_ref` pins the workflow without gating the ref. `pull_request_target` runs are denied unless the policy constrains `event_name`.
 
-##### Revoking Access
+---
+
+##### Diagnosing a Rejected Exchange
+
+Run `list_oidc_trust` (requires `super_user`) to list all policies including disabled ones:
+
+```json
+{ "operation": "list_oidc_trust" }
+```
+
+`list_oidc_trust` returns `{ "policies": [ ... ] }`. Each entry includes `id`, `issuer`, `audience`, `claims`, `user`, `enabled`, and optionally `invalid_reason`. Check `invalid_reason` first when diagnosing a rejected exchange — it is set when the policy is malformed or its user was deleted or deactivated after the policy was written. The exchange itself will not report what failed.
+
+Check the instance's `oidc-trust` log for server-side detail.
+
+---
 
-- **Stop future runs**: `harper drop_oidc_trust id=github-actions-<project>` (does not revoke already-issued tokens, which are valid up to one hour).
-- **Stop an already-issued token**: `harper alter_user username=<project>-ci-deploy active=false`.
-- **No CI secret to rotate** — there is none.
+##### Revoking Pipeline Access
+
+- **Stop future runs** — drop the policy:
+
+  ```bash
+  harper drop_oidc_trust id=github-actions-<project>
+  ```
+
+  This does not revoke tokens already issued (they are stateless JWTs valid for one hour).
+
+- **Stop a token already in circulation** — deactivate the user:
+
+  ```bash
+  harper alter_user username=<project>-ci-deploy active=false
+  ```
+
+  Use both together when responding to a suspected compromise.
+
+---
+
+##### Providing a Durable Credential for a Private Source
+
+Do not use the workflow's ephemeral `GITHUB_TOKEN` for Harper's stored credential — it expires when the job ends, and later installs (a new node joining, a reinstall after restore) would fail. Instead use a durable token:
+
+- For a private repository: a fine-grained personal access token with **Contents: read-only** scoped to the application repository.
+- For GitHub Packages: a token with the `read:packages` scope.
+
+Store it in Harper once from your machine:
+
+```bash
+# Private git repository
+harper deploy setup=true provider=github project=my-app
+
+# GitHub Packages
+harper deploy setup=true provider=npm project=my-app registry=https://npm.pkg.github.com scope=@my-org
+```
+
+The name is derived from the component and the host: `deploy.my-app.git.github.com` for the repository, and `deploy.my-app.npm.pkg.github.com` for GitHub Packages. Reference it by that name in the workflow — the token never appears in your pipeline.
 
 #### Examples
 
 ##### Path A: Deploy a Tagged Release (`v1.2.3`) from the Repository
 
-Push a semver tag (`v1.2.3`), and every node clones and installs that commit. `by_ref=true` deploys `git+https://github.com/<owner>/<repo>.git#<sha>`, where the SHA is the commit the tag points to (`GITHUB_SHA`), and every node clones that exact commit even if the tag moves later. For a private repository, add `credential=true` to attach the stored credential (`deploy.my-app.git.github.com`). If the repository needs a build step to be runnable, don't reach for `install_allow_scripts`: use Path B.
+Push a semver tag (`v1.2.3`), and every node clones and installs that commit. `by_ref=true` deploys `git+https://github.com/<owner>/<repo>.git#<sha>`, where the SHA is the commit the tag points to (`GITHUB_SHA`), and every node clones that exact commit even if the tag is moved later. If this repository needs a build step to be runnable, do not reach for `install_allow_scripts` — use Path B instead.
 
 ```yaml
 # .github/workflows/deploy.yml
@@ -2671,6 +2921,8 @@ jobs:
         run: harper deploy project=my-app by_ref=true restart=rolling json=true > deploy.json
       - name: Wait for every node to take the release
         run: |
+          # From v5.4.0 a certified rolling deploy waited for every node itself.
+          [ "$(jq -r '.rollout.status // empty' deploy.json)" != success ] || exit 0
           JOB_ID=$(jq -r '.restartJobId // empty' deploy.json)
           [ -n "$JOB_ID" ] || { echo "The rolling deploy returned no restartJobId"; exit 1; }
           LAST="could not be read"
@@ -2691,14 +2943,17 @@ jobs:
 Key details:
 
 - **No secrets.** `HARPER_CLI_TARGET` is the only thing the workflow is given. `id-token: write` lets the CLI request an identity token, and `environment: production` puts the `environment` claim the trust policy requires into it.
-- **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`.
+- **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`, where `actions/checkout` otherwise leaves it for every later step.
 - **`harper@^5.3`** pins the CLI's major version. 5.3 is the first CLI that authenticates with the identity token.
 - **`replicated` isn't needed.** On Harper Fabric and Harper Pro, a deploy goes to every node unless you pass `replicated=false`. Each node fetches and installs the package itself.
-- **`restart=rolling`** restarts nodes one at a time. Use `restart=true` for a single-node or dev instance.
-- **`json=true`** prints the deploy's result as JSON on stdout; progress and authentication messages go to stderr.
-- **The wait step** polls `restartJobId` via `get_job` until `COMPLETE` or `ERROR`, checking `.[0].status`. It retries a poll that fails (such as one that reaches a node while it restarts) and gives up after 60 polls (~10 minutes).
-- **`certification`**: on v5.4.0 and later, `restart=rolling` loads the release in a canary worker on each node before that node serves it, so a release that fails to load is rejected. The `certification` field in the deploy result reflects this. With `restart=rolling` on v5.4.0 and later, the deploy can report `success` before the rolling job has visited all nodes — wait on the job, not the record.
-- **The job lives on one node.** Through a **load-balanced** cluster URL, polls must eventually reach that node. Routing that always sends polls to a different node than the deploy causes the wait step to fail saying the job was not on the node that answered.
+- **`restart=rolling`** restarts nodes one at a time so the cluster keeps serving throughout. Use `restart=true` for a single-node or dev instance.
+- **`certification`**: on v5.4.0 and later, `restart=rolling` loads the release in a canary worker on each node before that node serves it, so a release that fails to load is rejected. The `certification` field in the deploy result reflects whether this ran.
+- **`restartJobId`**: present in the deploy JSON when a rolling job was started but the deploy did not wait for it itself. The wait step polls `.[0].status` from `get_job` until `COMPLETE` or `ERROR`.
+- **Load-balanced clusters**: the deployment record wait works through a load-balanced URL (the record replicates), but `get_job` polls do not — Harper does not replicate jobs. If your load balancer never routes back to the node that received the deploy, use one node's direct URL for both the deploy and the wait, and as the trust policy's `audience`.
+
+For a private repository, add `credential=true` to the deploy command.
+
+---
 
 ##### Path B: Build in CI, Publish to GitHub Packages, Deploy the Artifact
 
@@ -2767,6 +3022,7 @@ jobs:
             restart=rolling json=true > deploy.json
       - name: Wait for every node to take the release
         run: |
+          [ "$(jq -r '.rollout.status // empty' deploy.json)" != success ] || exit 0
           JOB_ID=$(jq -r '.restartJobId // empty' deploy.json)
           [ -n "$JOB_ID" ] || { echo "The rolling deploy returned no restartJobId"; exit 1; }
           LAST="could not be read"
@@ -2784,56 +3040,28 @@ jobs:
           exit 1
 ```
 
-Two jobs keep the identity token isolated: `publish` installs, builds, tests and publishes with `contents: read` and `packages: write` only — it cannot request an identity token. `deploy` runs once `publish` finishes (`needs: publish`), holds `environment: production` and `id-token: write`, and installs only the Harper CLI before deploying.
-
-Credential roles:
+Split into two jobs so the job with `id-token: write` runs none of your build code. Only the `deploy` job names `environment: production`, so only its token carries the `environment` claim the trust policy requires.
 
-- **Publishing** and installing private `@my-org` dependencies use the workflow's ephemeral `GITHUB_TOKEN` (`packages: write` includes read). Both happen entirely inside `publish`.
-- **Installing on Harper nodes** uses the durable `read:packages` token stored as `deploy.my-app.npm.pkg.github.com` — because installs can happen long after this workflow ends.
+---
 
-For `my-app`, the credential names are `deploy.my-app.git.github.com` for the repository and `deploy.my-app.npm.pkg.github.com` for GitHub Packages. Store a durable credential once from your machine:
-
-```bash
-harper deploy setup=true provider=github project=my-app
-# or for GitHub Packages:
-harper deploy setup=true provider=npm project=my-app registry=https://npm.pkg.github.com scope=@my-org
-```
-
-For a private repository, use a GitHub fine-grained personal access token with **Contents: read-only** scoped to the application repository. For GitHub Packages, use a token with the `read:packages` scope. Do not use the workflow's ephemeral `GITHUB_TOKEN` for the durable credential — it expires when the job ends.
-
-##### Check the Deployment Record
+##### Checking the Deployment Record
 
 ```bash
 harper get_deployment deployment_id="$(jq -r .deployment_id deploy.json)" json=true
 ```
 
-Only the node you called writes that record, so with `restart=rolling` on v5.4.0 and later it can report `success` before the job has visited the other nodes, and keeps reporting it if one of them rejects the release. Wait on the job, not the record, to confirm all nodes took the release. `list_deployments` gives the history of what was deployed and when.
-
-##### List and Inspect Trust Policies
-
-```bash
-harper list_oidc_trust
-```
-
-Returns `{ "policies": [ ... ] }`. Each entry includes `id`, `issuer`, `audience`, `claims`, `user`, `enabled`, and optionally `invalid_reason`. Check `invalid_reason` first when diagnosing a rejected exchange — it is set when the policy is malformed or its user was deleted or deactivated.
-
-##### Drop a Trust Policy
+Use `list_deployments` to see the history of what was deployed and when, and filter by commit with `sha`.
 
-```bash
-harper drop_oidc_trust id=github-actions-<project>
-```
+- **Go back to a previous release** by activating its `deployment_id`, with no rebuild or reinstall: `harper deploy project=my-app deployment_id=<id> restart=rolling`. To deploy a release that is no longer kept, re-run the deploy with its tag or version.
 
 #### Notes
 
-- `HARPER_CLI_REFRESH_TOKEN` and any other stored credential outrank the OIDC exchange. Remove them from the workflow if switching to OIDC.
-- **Go back to a previous release** by activating its `deployment_id`, with no rebuild or reinstall: `harper deploy project=my-app deployment_id=<id> restart=rolling`. To deploy a release that is no longer kept, re-run the deploy with its tag or version.
-- **Rotating the deploy credential**: run `harper deploy setup=true` again with the same name and a new value. The pipeline doesn't change.
-- **Revoking the pipeline's access**: `harper drop_oidc_trust` stops new runs; `harper alter_user` also stops a token already issued (valid up to one hour).
-- The `<project>-ci-deploy` user created by setup can deploy any component on the cluster, not only the named project. Access control comes down to who can merge to the branch.
-- The `audience` in `add_oidc_trust` must be the exact target URL with its port and a trailing slash.
-- For tag-triggered workflows, `provider=github-actions` setup is not sufficient — it pins a branch. Write the policy manually using `add_oidc_trust` with `workflow_path` and `environment` claims.
-- `token.actions.githubusercontent.com` is the required `issuer` value for GitHub Actions OIDC policies.
-- Git-host credentials require git ≥ 2.31 on the Harper nodes and are not supported on Windows nodes. Registry credentials have no such constraints.
+- `audience` in `add_oidc_trust` must include the port and a **trailing slash** — e.g., `https://my-cluster.example.com:9925/`. A URL without the trailing slash will not match.
+- `HARPER_CLI_REFRESH_TOKEN` and any other configured credential (`auth_username=`/`auth_password=`, `HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`, `HARPER_CLI_OPERATION_TOKEN`, a saved `harper login`) outrank the OIDC exchange. Remove stored credentials from the runner before enabling OIDC.
+- `list_oidc_trust`, `drop_oidc_trust`, and `alter_user` all require `super_user`.
+- `drop_oidc_trust` does not revoke already-issued operation tokens (one-hour JWTs). Pair it with `alter_user username=<project>-ci-deploy active=false` to stop tokens already in circulation.
+- `ref_type: tag` is not accepted as a ref gate. Gate tag-triggered workflows with `environment` instead, and set **Deployment branches and tags** to `v*` in the environment's settings.
+- Every step in a job with `id-token: write` can request an identity token — GitHub gives each one `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`. Run none of the repository's code in that job.
 - See [deploying-to-harper-fabric.md](deploying-to-harper-fabric.md) for cluster-level deployment context.
 
 ### 4.3 Creating a Harper Fabric Account and Cluster
@@ -2982,6 +3210,8 @@ don't have `deploy:setup-ci`. To move one over:
 
 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.
@@ -3089,6 +3319,8 @@ On deploy the plugin runs `vite build` at startup (and rebuilds when `files` cha
 
 Instructions for the agent to follow when implementing logging in Harper applications, including direct logger usage, tagged loggers, and console capture behavior.
 
+**Instead of:** Separate log shippers for app logs (pino or winston transports). Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Apply this rule when writing any JavaScript component, plugin, or resource that needs to emit structured log entries, filter logs by component, or capture existing `console.log` output into Harper's log system. Use it whenever you need to understand log levels, log entry format, or the `logger` global API.
@@ -3245,6 +3477,8 @@ Tagged entries appear in `hdb.log` with the tag in the header:
 
 Instructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.
 
+**Instead of:** `dotenv`. Use this rule rather than adding that service. See `harper-architecture`.
+
 #### When to Use
 
 Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use this whenever a `.env` file must be loaded at application startup.