@harperfast/template-react-ts-studio 1.12.2 → 1.12.4

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

@@ -18,14 +18,14 @@ Use this skill when you need to define new data structures or modify existing on
 2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harper/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
 3. **Define Relationships**: Link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
 4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
-   - `GET /{TableName}`: Describes the schema itself.
+   - `GET /{TableName}`: Describes the resource itself — table, database, and declared attributes. No trailing slash.
    - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
-   - `GET /{TableName}/{id}`: Retrieves a single record by its ID.
-   - `POST /{TableName}/`: Creates a new record.
-   - `PUT /{TableName}/{id}`: Updates an existing record.
-   - `PATCH /{TableName}/{id}`: Performs a partial update on a record.
-   - `DELETE /{TableName}/`: Deletes all records or filtered records.
-   - `DELETE /{TableName}/{id}`: Deletes a single record by its ID.
+   - `GET /{TableName}/{id}`: Retrieves a single record by its primary key.
+   - `POST /{TableName}/`: Creates a record and returns `201` with the Harper-assigned primary key in the `Location` response header (the bare key, not a URL). **The trailing slash is required** — `POST /{TableName}` returns `404`, and `POST /{TableName}/{id}` returns `405`.
+   - `PUT /{TableName}/{id}`: Creates **or replaces** the record at `{id}` (upsert). **Properties omitted from the body are removed** — send the complete record, or use `PATCH` to change a subset. Three exceptions survive the replacement: an `@updatedTime` attribute is re-stamped with the time of the write, a `@createdTime` attribute keeps its original value, and the primary key is forced to match the `{id}` in the URL, so a mismatched key in the body cannot create a second record.
+   - `PATCH /{TableName}/{id}`: Merges the request body into the existing record, preserving unspecified properties. The merge is **shallow** — a nested object in the body replaces the stored one wholesale rather than being deep-merged.
+   - `DELETE /{TableName}/{id}`: Deletes a single record by its primary key.
+   - `DELETE /{TableName}/`: Deletes every record matching the query parameters. **With no query parameters it matches — and deletes — every record in the table.** Always pass a filter unless emptying the table is the intent.
 5. **Consider Table Extensions**: If you are going to [extend the table](./extending-tables.md) in your resources, then do not `@export` the table from the schema.
 
 #### Examples
@@ -42,15 +42,26 @@ type ExamplePerson @table @export {
 
 ### 1.2 Schema Design and GraphQL Tooling
 
-Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
+Instructions for the agent to follow when designing Harper database schemas using GraphQL type definitions, core directives, and tooling configuration.
 
 #### 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 types and fields. Use it any time you need to define tables, primary keys, indexes, or exported endpoints.
+Apply this rule when creating or modifying Harper schema files (`.graphql`), configuring schema loading 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. **Declare the schema file** in the component's `config.yaml` using the `graphqlSchema` plugin:
+1. **Create a GraphQL schema file** with Harper-specific directives. Schemas ensure required tables exist on deployment, enforce types and constraints, control indexing, and define relationships.
+
+   ```graphql
+   type Dog @table {
+   	id: Long @primaryKey
+   	name: String
+   	breed: String
+   	age: Int
+   }
+   ```
+
+2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin:
 
    ```yaml
    graphqlSchema:
@@ -59,76 +70,74 @@ Apply this rule when creating or modifying Harper schema files (`.graphql`), con
 
    Both plugins and applications can specify schemas.
 
-2. **Mark types as tables** with `@table`. The type name becomes the table name by default:
+3. **Mark each type as a table** with `@table`. The type name becomes the table name by default.
 
    ```graphql
-   type Dog @table {
+   type MyTable @table {
    	id: Long @primaryKey
-   	name: String
-   	breed: String
-   	age: Int
    }
    ```
 
-3. **Set a primary key** on every table using `@primaryKey`. Primary keys must be unique; duplicate-key inserts are rejected. If no primary key is provided on insert, Harper auto-generates one based on the field type:
-   - `String` or `ID` → UUID string
-   - `Int`, `Long`, or `Any` → auto-incrementing integer
+   Key `@table` arguments:
 
-   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                                |
+   | `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** with `@indexed`. Required for filtering by an attribute in REST queries, SQL, or NoSQL operations:
+4. **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:
+   - **UUID string** — when type is `String` or `ID`
+   - **Auto-incrementing integer** — when type is `Int`, `Long`, or `Any`
+
+   Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
 
    ```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.
-
-5. **Expose a table as an external endpoint** with `@export`. Available via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment:
+5. **Add secondary indexes** with `@indexed` on any attribute that will be used for filtering in REST queries, SQL, or NoSQL operations. If the field value is an array, each element is individually indexed.
 
    ```graphql
-   type MyTable @table @export(name: "my-table") {
+   type Product @table {
    	id: Long @primaryKey
+   	category: String @indexed
+   	price: Float @indexed
    }
    ```
 
-   Without `name`, the type name is used.
-
-6. **Configure `@table` arguments** as needed. All arguments are optional:
-
-   | 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                              |
-
-7. **Apply additional field directives** where needed:
-   - `@createdTime` — auto-assigns creation timestamp (Unix epoch ms)
-   - `@updatedTime` — auto-assigns update timestamp (Unix epoch ms)
-   - `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch ms)
-   - `@embed(source:, model:)` — computes an embedding vector when the source field is written; field type must be `[Float]`
-   - `@hidden` — suppresses the field from MCP tool descriptors and OpenAPI document (not an access-control mechanism)
-
-8. **Use `@sealed`** on a type to prevent records from including properties beyond those declared in the schema:
+6. **Expose tables via REST and other interfaces** using `@export`. Without `@export`, the table has no REST/MQTT route (callers get 404). The optional `name` parameter sets the URL path segment.
 
    ```graphql
-   type StrictRecord @table @sealed {
+   type MyTable @table @export(name: "my-table") {
    	id: Long @primaryKey
-   	name: String
    }
    ```
 
-9. **Use unique database names** in plugins or applications to avoid table naming collisions, since all tables default to the `data` database.
+   `@export` is a routing directive, not access control. The table remains accessible through the Operations API and SQL regardless. REST must also be enabled for the application (via `rest: true` in `config.yaml` or Harper's built-in default).
+
+7. **Apply additional type directives** as needed:
+   - `@sealed` — prevents records from including properties beyond those declared in the schema.
+   - `@hidden` — suppresses the type from MCP tool descriptors and the OpenAPI document. Does not restrict data access.
+
+8. **Apply field directives** for computed and lifecycle behavior:
+   - `@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.
+   - `@embed` — computes an embedding vector when the source field is written (requires `source` and `model` arguments; field type must be `[Float]`).
+   - `@hidden` (field) — suppresses the field from generated specs and MCP tool schemas; does not restrict data access.
 
 #### Examples
 
-**Minimal schema with two tables:**
+**Minimal two-table schema:**
 
 ```graphql
 type Dog @table {
@@ -154,59 +163,62 @@ type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
 }
 ```
 
-**Table with multiple `@table` arguments combined:**
+**Exported table with cache control:**
 
 ```graphql
-type Event @table(database: "analytics", expiration: 86400) {
+type Product @table(cacheControl: "public, max-age=60") @export {
 	id: Long @primaryKey
-	name: String @indexed
+	name: String
+	price: Float
 }
 ```
 
-**Exported table with overridden table name:**
+**Table with lifecycle fields and indexing:**
 
 ```graphql
-type Product @table(table: "products") @export(name: "products") {
+type Event @table(database: "analytics", expiration: 86400) {
 	id: Long @primaryKey
-	category: String @indexed
-	price: Float @indexed
+	name: String @indexed
+	createdAt: Long @createdTime
+	updatedAt: Long @updatedTime
 }
 ```
 
-**Table with timestamps and per-record expiration:**
+**Session table with per-record expiration:**
 
 ```graphql
 type Session @table {
 	id: ID @primaryKey
 	token: String
-	createdAt: Long @createdTime
-	updatedAt: Long @updatedTime
 	expiresAt: Long @expiresAt
 }
 ```
 
-**Table with a hidden internal field:**
+**Sealed table preventing extra properties:**
 
 ```graphql
-type Customer @table {
+type StrictRecord @table @sealed {
 	id: Long @primaryKey
 	name: String
-
-	"""
-	Internal — do not surface to external consumers.
-	"""
-	creditScore: Int @hidden
 }
 ```
 
+**`config.yaml` schema registration:**
+
+```yaml
+graphqlSchema:
+  files: 'schema.graphql'
+```
+
 #### Notes
 
-- `@table`, `@export`, `@sealed`, and `@hidden` are type-level directives; `@primaryKey`, `@indexed`, `@embed`, `@createdTime`, `@updatedTime`, `@expiresAt`, and `@hidden` are field-level directives.
-- `eviction` removes non-indexed record data but does **not** remove a record from its secondary indexes. Indexes remain functional for evicted records; Harper fetches the full record on demand when a query matches an evicted entry.
-- `scanInterval` is clock-aligned to the server's local timezone, not startup-aligned. The server's startup time does not affect when eviction runs.
-- Replication is enabled by default. If you disable replication on a table and re-enable it later, it will not catch up on writes made while replication was disabled.
-- `@hidden` is a metadata-visibility directive only. Use `attribute_permissions` on roles to enforce data access control.
-- A full-record `put` that omits an `@expiresAt` field clears it; a `patch` of other fields preserves it.
+- Schemas are flexible by default — records may include additional properties beyond those declared. Use `@sealed` to prevent this.
+- Use unique `database` names in plugins or applications to avoid table naming collisions, since all tables default to the `"data"` database.
+- Replication is enabled by default. If you disable replication and re-enable it later, the table will not catch up on writes made while replication was disabled.
+- `@hidden` (type or field) is a metadata-visibility directive only. Use table-level role permissions and `attribute_permissions` whitelists to restrict actual data access.
+- `@export` absence causes 404 on REST/MQTT routes but does not protect data from the Operations API or SQL.
+- The `cacheControl` argument emits headers only on anonymous (unauthenticated) GET/HEAD 200/304 responses. Authenticated responses receive `Cache-Control: private, no-cache`.
+- `randomAccessFields` on `@table` pins the record encoding at table creation time. Editing the argument later does not repin an existing table.
 
 ### 1.3 Defining Relationships Between Tables in Harper
 
@@ -754,15 +766,15 @@ export class Photo extends tables.Photo {
 
 ### 2.1 Automatic APIs
 
-Instructions for the agent to follow when enabling and using Harper's automatically generated REST and WebSocket APIs.
+Instructions for the agent to follow when using Harper's automatically generated REST and WebSocket APIs for exported tables and resources.
 
 #### When to Use
 
-Apply this rule when adding REST or WebSocket API access to Harper tables or custom resources. Use it when configuring `config.yaml` to expose endpoints, mapping HTTP methods to resource operations, or implementing real-time WebSocket connections on a resource class.
+Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for Harper tables without writing custom handler code. Use it whenever a schema type needs to be served over HTTP, when configuring real-time subscriptions, or when setting up conditional caching behavior for REST responses.
 
 #### How It Works
 
-1. **Enable the REST plugin**: Add `rest: true` to your application's `config.yaml`. This activates the HTTP REST interface on the application server port (default `9926`) and enables WebSocket support automatically.
+1. **Enable REST in `config.yaml`**: Add `rest: true` to the application configuration file. This registers REST endpoints and, by default, WebSocket subscriptions for all exported resources.
 
    ```yaml
    rest: true
@@ -776,26 +788,47 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
      webSocket: false # disables automatic WebSocket support (enabled by default)
    ```
 
-2. **Export your resource in the schema**: Tables are not exposed by default. Use the `@export` directive in your schema definition to expose a table as a REST endpoint. The exported name defines the base URL path.
+2. **Export the table in the schema**: Add `@export` to the type definition. Without `@export`, Harper registers no REST route and callers receive `404`. Without `rest: true`, even an exported table does not respond to HTTP requests. Both are required.
 
-3. **Use the correct URL structure**: Target resources using these path conventions:
+   ```graphql
+   type Product @table @export {
+   	id: Long @primaryKey
+   	name: String
+   	price: Float
+   }
+   ```
 
-   | Path                                         | Description                                                 |
-   | -------------------------------------------- | ----------------------------------------------------------- |
-   | `/my-resource`                               | Returns resource metadata                                   |
-   | `/my-resource/`                              | Collection — all records; append query parameters to search |
-   | `/my-resource/record-id`                     | Specific record by primary key                              |
-   | `/my-resource/record-id/`                    | Collection of records with the given id prefix              |
-   | `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments                       |
+   Reference the schema file in `config.yaml`:
 
-4. **Map operations to HTTP methods**: Each HTTP method maps to a resource method:
-   - **GET** — Retrieve a record or search. Calls `get()`. Responses include an `ETag` header; send `If-None-Match` on subsequent requests to receive `304 Not Modified` when unchanged.
-   - **PUT** — Create or replace a record (upsert). Calls `put(record)`. The stored record exactly matches the submitted body; omitted properties are removed.
-   - **POST** — Create a record without specifying a primary key. Calls `post(data)`. The assigned key is returned in the `Location` response header.
-   - **PATCH** — Partially update a record, merging only provided top-level properties. Calls the resource's patch handler. Merge is **shallow** — nested objects are replaced entirely, not deep-merged.
-   - **DELETE** — Delete a record by id or all records matching a query.
+   ```yaml
+   graphqlSchema:
+     files: schema.graphql
+   rest: true
+   ```
+
+3. **Use the automatically registered endpoints**: Harper serves the following endpoints on the application HTTP server port (default `9926`) with no route definitions or handler code required.
+
+   | Endpoint                     | Description                                                                 |
+   | ---------------------------- | --------------------------------------------------------------------------- |
+   | `GET /Product`               | Returns resource description (table name, database, attributes)             |
+   | `GET /Product/`              | Returns the record collection; append query parameters to filter            |
+   | `GET /Product/{id}`          | Returns a single record by primary key; `404` if not found                  |
+   | `GET /Product/{id}.property` | Returns a single declared property of one record                            |
+   | `POST /Product/`             | Creates a record; responds `201`; primary key returned in `Location` header |
+   | `PUT /Product/{id}`          | Creates or replaces the record at `{id}` (upsert)                           |
+   | `PATCH /Product/{id}`        | Merges body into existing record (shallow, top-level only)                  |
+   | `DELETE /Product/{id}`       | Deletes the record at `{id}`                                                |
+   | `DELETE /Product/?query`     | Deletes every record matching the query                                     |
+
+4. **Handle `POST` primary key and `Location`**: On a successful `POST`, the new record's primary key is returned in the `Location` response header — the value the body supplied if it carried the primary-key property, otherwise a Harper-assigned key. The header carries the bare key value, not a URL.
 
-5. **Connect via WebSocket**: A WebSocket connection to a resource URL subscribes to that resource and streams change events. See [real-time-apps.md](real-time-apps.md) for full real-time patterns.
+5. **Understand `PUT` write behavior**: `PUT` replaces the stored record exactly. Three exceptions always apply: a `@createdTime` attribute keeps the original value, an `@updatedTime` attribute is re-stamped with the time of the write, and the primary key is forced to match the `{id}` in the URL.
+
+6. **Use conditional requests for caching**: GET responses include an `ETag` header encoding the record's version/last-modification time. Send `If-None-Match` on subsequent requests with the cached `ETag` value. If the record has not changed, Harper returns `304 Not Modified` with no body.
+
+7. **Select content type with `Accept`**: Use the `Accept` header to request a specific response format. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors on property paths and take precedence over property names. See [querying-rest-apis.md](querying-rest-apis.md) for query syntax details.
+
+8. **Connect via WebSocket**: WebSocket support is enabled automatically when `rest` is enabled. Connecting to a resource URL subscribes to changes for that resource. See [real-time-apps.md](real-time-apps.md) for real-time patterns.
 
    ```javascript
    let ws = new WebSocket('wss://server/my-resource/341');
@@ -804,29 +837,84 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
    };
    ```
 
-6. **Implement a custom `connect()` handler** on a resource class to control WebSocket behavior. The method receives `incomingMessages` and must return an async iterable producing messages to send to the client.
-
-7. **Retrieve the OpenAPI spec**: Harper auto-generates an OpenAPI specification for all exported resources, available at:
+9. **Implement a custom `connect()` handler** when default subscription behavior is insufficient. The method must return an async iterable that produces messages to send to the client.
 
-   ```
-   GET /openapi
+   ```javascript
+   export class Echo extends Resource {
+   	async *connect(incomingMessages) {
+   		for await (let message of incomingMessages) {
+   			yield message; // echo each message back
+   		}
+   	}
+   }
    ```
 
 #### Examples
 
-**Simple echo WebSocket server**:
+##### Full schema and config setup
 
-```javascript
-export class Echo extends Resource {
-	async *connect(incomingMessages) {
-		for await (let message of incomingMessages) {
-			yield message; // echo each message back
-		}
-	}
+```graphql
+# schema.graphql
+type Product @table @export {
+	id: Long @primaryKey
+	name: String
+	price: Float
 }
 ```
 
-**Custom `connect()` using the default iterable with `send()` and `close` event**:
+```yaml
+# config.yaml
+graphqlSchema:
+  files: schema.graphql
+rest: true
+```
+
+##### Conditional GET with ETag caching
+
+```
+GET /Product/123
+# Response includes:
+# ETag: "abc123"
+
+GET /Product/123
+If-None-Match: "abc123"
+# Response: 304 Not Modified (no body transferred)
+```
+
+##### POST and read the Location header
+
+```
+POST /Product/
+Content-Type: application/json
+
+{ "name": "Widget", "price": 9.99 }
+
+# Response:
+# 201 Created
+# Location: 7f3a9c
+```
+
+##### PATCH (shallow merge only)
+
+```
+PATCH /Product/123
+Content-Type: application/json
+
+{ "price": 12.99 }
+```
+
+Only `price` is updated; other top-level properties are preserved. Nested objects in the body replace the stored sub-object wholesale — deep merge does not occur.
+
+##### Request MessagePack response
+
+```
+GET /Product/123
+Accept: application/msgpack
+```
+
+Alternatively, use the `.msgpack` suffix on the URL path where supported.
+
+##### WebSocket with custom outgoing messages
 
 ```javascript
 export class Example extends Resource {
@@ -838,7 +926,7 @@ export class Example extends Resource {
 		}, 1000);
 
 		incomingMessages.on('data', (message) => {
-			outgoingMessages.send(message); // echo incoming messages
+			outgoingMessages.send(message);
 		});
 
 		outgoingMessages.on('close', () => {
@@ -850,37 +938,31 @@ export class Example extends Resource {
 }
 ```
 
-**Common REST operations**:
+##### Disable WebSocket while keeping REST
 
-```
-GET /MyTable/123
-GET /MyTable/?name=Harper
-PUT /MyTable/123
-PATCH /MyTable/123
-DELETE /MyTable/?status=archived
-```
-
-```json
-{ "name": "some data" }
+```yaml
+rest:
+  webSocket: false
 ```
 
 #### Notes
 
-- `rest: true` is the minimal config to enable both REST and WebSocket support. Set `webSocket: false` under the `rest` key to disable WebSocket only.
-- The `@export` directive in the schema is required for any table to appear as a REST endpoint — tables are not exported by default.
-- PATCH merges are shallow (top-level only). Nested objects in the request body replace the entire existing sub-object. Dot-path keys (e.g., `"settings.theme"`) are stored as literal keys, not interpreted as paths.
-- For MQTT over WebSocket, set the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
-- In distributed environments, non-retained messages are delivered in arrival order; retained messages (PUT/updated records) keep only the latest timestamp as the winning record.
-- For full query syntax on GET and DELETE, see [querying-rest-apis.md](querying-rest-apis.md).
-- For building real-time features with WebSocket subscriptions, see [real-time-apps.md](real-time-apps.md).
+- The trailing slash is significant: `/Product` addresses the resource itself; `/Product/` addresses its record collection. `POST /Product` (no trailing slash) returns `404`.
+- `HEAD` is served as `GET` with the body omitted. `QUERY` is accepted on the collection path and reads its search from the request body.
+- A `POST` to an existing primary key fails with `409` — it does not overwrite.
+- A component directory with **no configuration file** gets REST enabled by Harper's built-in default. As soon as a `config.yaml` exists it is used verbatim — add `rest: true` explicitly or REST is off.
+- Do not apply `@export` to a schema type and also export a same-named JavaScript subclass of that table — this produces conflicting endpoints.
+- Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`. They are not affected by the `webSocket` option.
+- Every non-hidden exported resource is included in the generated OpenAPI document at `GET /openapi`. Mark a type `@hidden` or set `static hidden = true` on a programmatic Resource to omit it.
+- MQTT over WebSockets requires the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
 
-### 2.2 Querying Harper REST APIs
+### 2.2 Querying REST APIs
 
-Instructions for the agent to filter, sort, select, and paginate records using Harper's URL-based query language on REST collection endpoints.
+Instructions for the agent to filter, sort, select, and paginate Harper REST API collections using URL query parameters.
 
 #### When to Use
 
-Apply this rule when building or debugging REST API calls against Harper tables that require filtering by attribute values, comparison ranges, sorting, field selection, or result pagination. This rule also covers OR logic, grouping, and querying across related tables via dot-syntax joins. See [automatic-apis.md](automatic-apis.md) for how Harper exposes tables as REST endpoints.
+Apply this rule whenever building or modifying code that queries Harper REST collection endpoints. Use it when you need to filter records by attribute values, apply comparison operators, sort or paginate results, or join across related tables. See [automatic-apis.md](automatic-apis.md) for how Harper exposes tables as REST endpoints.
 
 #### How It Works
 
@@ -891,13 +973,7 @@ Apply this rule when building or debugging REST API calls against Harper tables
    GET /Product/?category=software&inStock=true
    ```
 
-2. **Filter for null values**: Use `=null` as the value to match null or non-null records.
-
-   ```
-   GET /Product/?discount=null
-   ```
-
-3. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in query parameters for range and string matching.
+2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in the query string for numeric, string, and date comparisons.
 
    | Operator             | Meaning                                |
    | -------------------- | -------------------------------------- |
@@ -926,13 +1002,13 @@ Apply this rule when building or debugging REST API calls against Harper tables
    GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
    ```
 
-4. **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 for chaining.
+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.
 
    ```
    GET /Product/?price=gt=100&lt=200
    ```
 
-5. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit prefixes to force a type.
+4. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit prefixes to force a type.
 
    | Syntax                                    | Behavior                                    |
    | ----------------------------------------- | ------------------------------------------- |
@@ -946,32 +1022,26 @@ Apply this rule when building or debugging REST API calls against Harper tables
 
    For strict operators (`=`, `===`, `!==`), no automatic type conversion is applied.
 
-6. **Combine conditions with OR logic**: Use `|` instead of `&` to express OR between conditions.
+5. **Combine conditions with OR logic**: Use `|` instead of `&`.
 
    ```
    GET /Product/?rating=5|featured=true
    ```
 
-7. **Group conditions**: Use parentheses or square brackets to control evaluation order. Prefer square brackets when building queries from user input, since `[` and `]` are safely URI-encoded.
+6. **Group conditions**: Use parentheses or square brackets to control order of operations. Prefer square brackets when constructing queries from user input, since standard URI encoding safely encodes `[` and `]`.
 
    ```
    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('|')}]`;
    ```
 
-   Nest groups for complex conditions:
-
-   ```
-   GET /Product/?price=lt=100|[rating=5&[tag=fast|tag=scalable|tag=efficient]&inStock=true]
-   ```
-
-8. **Select specific properties with `select(`**: Append `select(...)` as a query function separated by `&` to control which fields are returned.
+7. **Select specific properties with `select(`**: Append `select(...)` as a query function separated by `&`.
 
    | Syntax                                 | Returns                                     |
    | -------------------------------------- | ------------------------------------------- |
@@ -981,65 +1051,47 @@ Apply this rule when building or debugging REST API calls against Harper tables
    | `?select(property1,)`                  | Objects with a single specified property    |
    | `?select(property{subProp1,subProp2})` | Nested objects with specific sub-properties |
 
-   ```
-   GET /Product/?category=software&select(name)
-   GET /Product/?brand.name=Microsoft&select(name,brand{name})
-   ```
-
-9. **Paginate results with `limit(`**: Use `limit(end)` or `limit(start,end)` to restrict the number of records returned.
-
-   ```
-   GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
-   GET /Product/?rating=gt=3&limit(10,30)
-   ```
-
-10. **Sort results with `sort(`**: Use `sort(property)` or `sort(+property,-property,...)` to order results. Prefix `+` or no prefix = ascending; `-` = descending.
-
-    ```
-    GET /Product/?rating=gt=3&sort(+name)
-    GET /Product/?sort(+rating,-price)
-    ```
-
-11. **Query across relationships using dot-syntax**: Filter on related table attributes using dot-chained property names. Relationships must be defined in the schema with `@relationship`.
+8. **Paginate with `limit(`**: Use `limit(end)` or `limit(start,end)` to control result count and offset.
 
-    ```
-    GET /Product/?brand.name=Microsoft
-    GET /Brand/?products.name=Keyboard
-    ```
+9. **Sort with `sort(`**: Use `sort(property)` or `sort(+property,-property,...)`. Prefix `+` or no prefix = ascending; `-` = descending.
 
-    Use `select()` to include relationship attributes in the response (they are excluded by default):
+10. **Query across relationships**: Use dot-syntax to filter by related table attributes. Relationships must be defined in the schema using `@relationship`. Relationship attributes are not included by default — use `select()` to include them.
 
     ```
-    GET /Product/?brand.name=Microsoft&select(name,brand)
     GET /Product/?brand.name=Microsoft&select(name,brand{name})
     ```
 
-12. **Access a specific property by URL**: Append `.propertyName` to a record ID in the URL path. Only works for properties declared in the schema.
+11. **Query for null values**: Use `=null` as the value to match null or non-null records.
     ```
-    GET /MyTable/123.propertyName
+    GET /Product/?discount=null
     ```
 
 #### Examples
 
-**Range filter with select and limit**:
+**Filter with comparison operators and select:**
 
 ```
-GET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)&limit(20)
+GET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)
 ```
 
-**Sort and paginate**:
+**Paginate and sort:**
 
 ```
-GET /Product/?rating=gt=3&sort(+rating,-price)&limit(10,30)
+GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
+GET /Product/?rating=gt=3&limit(10,30)
+GET /Product/?rating=gt=3&sort(+name)
+GET /Product/?sort(+rating,-price)
 ```
 
-**OR with grouping**:
+**OR logic with grouping:**
 
 ```
 GET /Product/?price=lt=100|[rating=5&[tag=fast|tag=scalable|tag=efficient]&inStock=true]
 ```
 
-**Join query with nested select** — schema first:
+**Relationship join with nested select:**
+
+Define the schema:
 
 ```graphql
 type Product @table @export {
@@ -1055,13 +1107,14 @@ type Brand @table @export {
 }
 ```
 
-Then query:
+Query with join:
 
 ```
 GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
+GET /Brand/?products.name=Keyboard
 ```
 
-**Many-to-many relationship** — schema:
+**Many-to-many relationship:**
 
 ```graphql
 type Product @table @export {
@@ -1072,26 +1125,23 @@ type Product @table @export {
 }
 ```
 
-Query:
-
 ```
 GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
 ```
 
-**Date range with URL-encoded colons**:
+**Access a specific property by record ID:**
 
 ```
-GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
+GET /MyTable/123.propertyName
 ```
 
 #### Notes
 
-- All filtered attributes must be indexed unless at least one other attribute in the same query is indexed.
-- Null queries (`?attr=null`) require indexes created after null indexing support was added. Rebuild existing indexes (remove and re-add) to enable null queries on them.
-- When selecting a related attribute without filtering on it, the join behaves as a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
-- The array order of foreign key values (e.g., `resellerIds`) is preserved when resolving many-to-many relationships.
-- Square brackets (`[`, `]`) are preferred over parentheses for grouping when constructing queries programmatically, because standard URI encoding safely encodes them.
-- `directURLMapping: true` can be set on a resource to change URL path handling semantics; see your schema configuration for details.
+- Only indexed attributes can be used as the primary filter attribute; when combining multiple attributes, only one needs to be indexed.
+- Relationship attributes are excluded from responses by default. Always use `select(` to include them.
+- When selecting a related attribute without filtering on it, the behavior is a LEFT JOIN — the property is omitted if the foreign key is null or references a non-existent record.
+- The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` in URL paths are reserved as content-type selectors and take precedence over a property of the same name.
+- Square brackets are preferred over parentheses when building grouped queries programmatically, because `[` and `]` are safely URL-encoded by standard encoding functions while `(` is not.
 
 ### 2.3 Real-Time Apps with WebSockets and Pub/Sub
 
@@ -1187,138 +1237,59 @@ export class Example extends Resource {
 
 ### 2.4 Checking Authentication
 
-Instructions for the agent to follow when handling user authentication and session management inside Harper Resources.
+Instructions for the agent to handle user authentication, sessions, and JWT token issuance in Harper Resources.
 
 #### When to Use
 
-Apply this rule when implementing authentication checks, login/logout flows, or token issuance inside a custom Resource. Use it any time a Resource needs to identify the current user, establish a session, or issue JWTs to clients. See [custom-resources.md](custom-resources.md) for the general Resource authoring pattern.
+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.
 
 #### How It Works
 
-1. **Check the current user** with `getCurrentUser()`. Call it inside any Resource method to retrieve the authenticated user or `undefined` if no user is authenticated. Guard protected endpoints by returning a `401` when the result is `undefined`.
-
-   ```javascript
-   async get(target) {
-     const user = this.getCurrentUser();
-     if (!user) return new Response(null, { status: 401 });
-     return { username: user.username, role: user.role };
-   }
-   ```
-
-   The returned object exposes `username`, `role`, and `role.permission` flags.
-
-2. **Enable sessions** before using session-based login. Set `authentication.enableSessions: true` in `harperdb-config.yaml`:
-
-   ```yaml
-   authentication:
-     enableSessions: true
-   ```
+##### 1. Reading the Current Authenticated User
 
-3. **Access login and session helpers** via `getContext()`. The context object exposes `context.login` and `context.session` for sign-in/out flows.
-   - Call `context.login(username, password)` to verify credentials and establish a session cookie on success.
-   - To end a session, delete it via `context.session.delete(context.session.id)`.
+**In an instance method**, call `getCurrentUser()` to get the user associated with the current request, or `undefined` if unauthenticated. The returned object exposes `username`, `role`, and `role.permission` flags.
 
-4. **Implement sign-in and sign-out Resources** using the context helpers:
+**In a static verb**, read the user from the `context` argument instead — `context.user`:
 
-   ```javascript
-   export class SignIn extends Resource {
-   	async post(_target, data) {
-   		const context = this.getContext();
-   		try {
-   			await context.login(data.username, data.password);
-   		} catch {
-   			return new Response('Invalid credentials', { status: 403 });
-   		}
-   		return new Response('Logged in', { status: 200 });
-   	}
-   }
-
-   export class SignOut extends Resource {
-   	async post() {
-   		const context = this.getContext();
-   		if (!context.session) return new Response(null, { status: 401 });
-   		await context.session.delete(context.session.id);
-   		return new Response('Logged out', { status: 200 });
-   	}
-   }
-   ```
-
-5. **Issue JWTs for non-browser clients** (CLI tools, mobile apps, service-to-service). Cookie-based sessions are intended for browser clients. For other clients, mint tokens programmatically using `server.operation()`:
-
-   ```javascript
-   import { Resource, server } from 'harper';
-
-   export class IssueTokens extends Resource {
-   	static async get(_target, context) {
-   		const { operation_token, refresh_token } = await server.operation(
-   			{ operation: 'create_authentication_tokens' },
-   			context,
-   			true,
-   		);
-   		return { operation_token, refresh_token };
-   	}
+```javascript
+static async get(_target, context) {
+    const user = context?.user;
+    if (!user) return new Response(null, { status: 401 });
+    return { username: user.username, role: user.role };
+}
+```
 
-   	static async post(_target, data) {
-   		const { username, password } = await data;
-   		if (!username || !password) {
-   			return new Response('username and password required', { status: 400 });
-   		}
-   		const { operation_token, refresh_token } = await server.operation({
-   			operation: 'create_authentication_tokens',
-   			username,
-   			password,
-   		});
-   		return { operation_token, refresh_token };
-   	}
-   }
+##### 2. Reading the Full Context
 
-   export class RefreshJWT extends Resource {
-   	static async post(_target, data) {
-   		const { refresh_token } = await data;
-   		if (!refresh_token) {
-   			return new Response('refresh_token required', { status: 400 });
-   		}
-   		const { operation_token } = await server.operation({
-   			operation: 'refresh_operation_token',
-   			refresh_token,
-   		});
-   		return { operation_token };
-   	}
-   }
-   ```
+**In an instance method**, call `getContext()` to retrieve the current context, which includes:
 
-   Pass `true` as the third argument to `server.operation()` when the operation should run as the current authenticated user. Omit it or pass `false` when the operation supplies its own credentials.
+- `user` — User object with username, role, and authorization information
+- `transaction` — The current transaction
 
-6. **Configure JWT token expiry** in `harperdb-config.yaml` under the `authentication` section:
+**In a static verb**, the context is the trailing argument:
 
-   ```yaml
-   authentication:
-     operationTokenTimeout: 1d
-     refreshTokenTimeout: 30d
-   ```
+- `(target, context)` for `get`/`delete`
+- `(target, data, context)` for `put`/`patch`/`post`
 
-   Duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`).
+When triggered by HTTP, the context also exposes `url`, `method`, `headers`, `responseHeaders`, `pathname`, `host`, `ip`, `body`, `data`, `lastModified`, and `requestContext`.
 
-#### Examples
+##### 3. Handling Sessions and Login
 
-**Protecting a resource endpoint and returning user info:**
+Enable sessions in `harper-config.yaml`:
 
-```javascript
-async get(target) {
-  const user = this.getCurrentUser();
-  if (!user) return new Response(null, { status: 401 });
-  return { username: user.username, role: user.role };
-}
+```yaml
+authentication:
+  enableSessions: true
 ```
 
-**Full session-based sign-in/sign-out flow:**
+Use `context.login` in a static `post` verb to verify credentials and establish a session cookie:
 
 ```javascript
 export class SignIn extends Resource {
-	async post(_target, data) {
-		const context = this.getContext();
+	static async post(_target, data, context) {
+		const { username, password } = (await data) ?? {};
 		try {
-			await context.login(data.username, data.password);
+			await context.login(username, password);
 		} catch {
 			return new Response('Invalid credentials', { status: 403 });
 		}
@@ -1327,18 +1298,161 @@ export class SignIn extends Resource {
 }
 
 export class SignOut extends Resource {
-	async post() {
-		const context = this.getContext();
-		if (!context.session) return new Response(null, { status: 401 });
-		await context.session.delete(context.session.id);
+	static async post(_target, _data, context) {
+		if (!context?.session?.user) return new Response(null, { status: 401 });
+		await context.session.update({ user: null });
 		return new Response('Logged out', { status: 200 });
 	}
 }
 ```
 
-**JWT token refresh endpoint:**
+- `context.login(username, password)` verifies credentials and sets the session cookie on success.
+- To end a session, call `context.session.update({ user: null })` — `update` is the session's only mutator.
+- `context.session` is an empty object (not `undefined`) when sessions are enabled and no session cookie is present; test `context?.session?.user` to detect an established session.
+- Cookie-based sessions are for browser clients. For non-browser clients, use JWT issuance.
+
+##### 4. Creating Authentication Tokens
+
+Call `create_authentication_tokens` with credentials in the body — no `Authorization` header is required when `username` and `password` are supplied:
+
+```json
+{
+	"operation": "create_authentication_tokens",
+	"username": "username",
+	"password": "password"
+}
+```
+
+Response:
+
+```json
+{
+	"operation_token": "<jwt-operation-token>",
+	"refresh_token": "<jwt-refresh-token>"
+}
+```
+
+Pass the `operation_token` as a `Bearer` token on subsequent requests:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <operation_token>' \
+  --data-raw '{
+      "operation": "search_by_hash",
+      "schema": "dev",
+      "table": "dog",
+      "hash_values": [1],
+      "get_attributes": ["*"]
+  }'
+```
+
+##### 5. Refreshing the Operation Token
+
+When the `operation_token` expires, pass the `refresh_token` as `Bearer <refresh_token>` and call `refresh_operation_token`:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <refresh_token>' \
+  --data-raw '{
+    "operation": "refresh_operation_token"
+  }'
+```
+
+Response:
+
+```json
+{
+	"operation_token": "<new-jwt-operation-token>"
+}
+```
+
+When both tokens have expired, call `create_authentication_tokens` again with username and password.
+
+##### 6. Minting Scoped Tokens
+
+A `super_user` can mint a scoped token with embedded permissions using `create_authentication_tokens` with an inline `role`. The minter must be authenticated; no `password` may be included in the body. Use `add_role`-style `permission` structure:
+
+```json
+{
+	"operation": "create_authentication_tokens",
+	"username": "reporting-service",
+	"role": {
+		"permission": {
+			"operations": ["read_only"],
+			"dev": {
+				"tables": {
+					"dog": {
+						"read": true,
+						"insert": false,
+						"update": false,
+						"delete": false,
+						"attribute_permissions": []
+					}
+				}
+			}
+		}
+	},
+	"expires_in": "7d"
+}
+```
+
+Authenticate the mint request with Basic Authentication or an existing `super_user` `operation_token`:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Basic <base64 of super_user:password>' \
+  --data-raw '{
+      "operation": "create_authentication_tokens",
+      "username": "reporting-service",
+      "role": { "permission": { "operations": ["read_only"] } },
+      "expires_in": "7d"
+  }'
+```
+
+Key constraints for scoped tokens:
+
+- `username` is attribution only and must not name an existing user.
+- No refresh token is issued; no user record is created.
+- Scoped tokens cannot be revoked before expiry — choose `expires_in` carefully and prefer short lifetimes.
+- `super_user` and `cluster_user` are always forced to `false` in the embedded role.
+- In **mixed-version** clusters, only nodes with scoped-token support accept these tokens; older nodes reject them with 401.
+
+##### 7. Issuing Tokens from a Custom Resource
+
+Use `server.operation()` to mint tokens programmatically inside a Resource. Pass `authorize: true` as the **third argument** when the operation should run as the current authenticated user:
 
 ```javascript
+import { Resource, server } from 'harper';
+
+export class IssueTokens extends Resource {
+	static async get(_target, context) {
+		// Issue tokens for the current authenticated user
+		const { operation_token, refresh_token } = await server.operation(
+			{ operation: 'create_authentication_tokens' },
+			context,
+			true, // third argument: authorize as current user
+		);
+		return { operation_token, refresh_token };
+	}
+
+	static async post(_target, data) {
+		// Issue tokens from credentials supplied in the body
+		const { username, password } = await data;
+		if (!username || !password) {
+			return new Response('username and password required', { status: 400 });
+		}
+		const { operation_token, refresh_token } = await server.operation({
+			operation: 'create_authentication_tokens',
+			username,
+			password,
+		});
+		return { operation_token, refresh_token };
+	}
+}
+
 export class RefreshJWT extends Resource {
 	static async post(_target, data) {
 		const { refresh_token } = await data;
@@ -1354,12 +1468,76 @@ export class RefreshJWT extends Resource {
 }
 ```
 
+Omit the third argument (or pass `false`) when the operation supplies its own credentials.
+
+##### 8. Configuring Token Expiry
+
+Set timeouts in `harper-config.yaml` under the `authentication` section:
+
+```yaml
+authentication:
+  operationTokenTimeout: 1d # Default: 1 day
+  refreshTokenTimeout: 30d # Default: 30 days
+```
+
+Valid duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`). The `expires_in` field on scoped token minting accepts the same format.
+
+#### Examples
+
+##### Full Sign-In / Sign-Out Resource
+
+```javascript
+export class SignIn extends Resource {
+	static async post(_target, data, context) {
+		const { username, password } = (await data) ?? {};
+		try {
+			await context.login(username, password);
+		} catch {
+			return new Response('Invalid credentials', { status: 403 });
+		}
+		return new Response('Logged in', { status: 200 });
+	}
+}
+
+export class SignOut extends Resource {
+	static async post(_target, _data, context) {
+		if (!context?.session?.user) return new Response(null, { status: 401 });
+		await context.session.update({ user: null });
+		return new Response('Logged out', { status: 200 });
+	}
+}
+```
+
+##### Reading the Current Authenticated User in a Static Verb
+
+```javascript
+static async get(_target, context) {
+    const user = context?.user;
+    if (!user) return new Response(null, { status: 401 });
+    return { username: user.username, role: user.role };
+}
+```
+
+##### Minting Tokens via cURL
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+      "operation": "create_authentication_tokens",
+      "username": "username",
+      "password": "password"
+  }'
+```
+
 #### Notes
 
-- `getCurrentUser()` and `getContext()` are instance methods; call them with `this` inside non-static Resource methods.
-- `enableSessions` must be `true` in config before `context.login` or `context.session` will function.
-- Cookie-based sessions target browser clients. Use JWT issuance via `server.operation()` for all other client types.
-- When both `operation_token` and `refresh_token` have expired, the client must call `create_authentication_tokens` again with credentials.
+- JWT authentication is **preferred over Basic Auth** when you want to avoid sending credentials on every request, your client can store tokens, or you have multiple sequential requests. For simple or **server-to-server** scenarios, use **Basic Authentication**.
+- Always use **HTTPS** in production to protect tokens in transit.
+- Treat tokens like passwords. If a token is compromised, it remains valid until expiry — use shorter `operationTokenTimeout` values in high-security environments.
+- `context.login` and `context.session` require `enableSessions: true` in `harperdb-config.yaml`; they are for browser clients only.
+- The `server.operation()` third argument (`authorize: true`) attributes the operation to — and permission-checks against — the current authenticated user. Omit it when supplying credentials directly in the operation body.
+- In **mixed-version** clusters, scoped tokens are only accepted by nodes that support them; older nodes return 401.
 
 ## 3. Logic & Extension
 
@@ -1369,11 +1547,11 @@ Instructions for the agent to follow when defining custom REST endpoints with Ja
 
 #### When to Use
 
-Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when a specific URL shape is required.
+Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed resource or when a specific URL shape is required.
 
 #### How It Works
 
-1. **Import `Resource` from `harper`**: Always import from the `harper` package rather than relying on globals.
+1. **Import `Resource` from the `harper` package**: Always import explicitly rather than relying on globals.
 
    ```javascript
    import { tables, Resource } from 'harper';
@@ -1391,7 +1569,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-3. **Use `async` static methods for external calls**: Await fetch or other async operations inside `static` handlers.
+3. **Use `async` static methods to call external services**: Return or forward the response directly.
 
    ```javascript
    export class MyExternalData extends Resource {
@@ -1409,7 +1587,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-4. **Export the class to create an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
+4. **Export the class to expose it as an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
 
    | Export form                                 | URL             | Notes                                                           |
    | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
@@ -1420,12 +1598,17 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
    | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
 
-   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+5. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the resource class.
 
-5. **Declare path parameters with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+   ```javascript
+   server.resources.set('my-path', Foo);
+   ```
+
+6. **Declare dynamic path segments with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
 
    ```javascript
    export class Widget extends Resource {
+   	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
    	static path = '/widget/:id/action/:action';
    	static get(target) {
    		return { id: target.id, action: target.action };
@@ -1433,22 +1616,11 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-   A `static path` takes precedence over the export name. A leading `/` makes the path root-relative (top-level). A leading `./` or bare name resolves relative to the component directory.
-
-6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` when the path cannot be known at export time.
-
-   ```javascript
-   server.resources.set('my-path', Foo);
-   ```
-
-7. **Optionally source a table from a custom resource**: Use the resource as a caching layer for a local table.
-   ```javascript
-   tables.MyCache.sourcedFrom(MyExternalData);
-   ```
+7. **Resolve path precedence correctly**: Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats a `:param`, which beats a `*` wildcard, compared left to right.
 
 #### Examples
 
-##### External API wrapper with GET and PUT
+**Wrapping an external API and using it as a cache source:**
 
 ```javascript
 import { tables, Resource } from 'harper';
@@ -1471,19 +1643,9 @@ export class MyExternalData extends Resource {
 tables.MyCache.sourcedFrom(MyExternalData);
 ```
 
-##### Path parameters with `static path`
+**Catch-all wildcard path:**
 
 ```javascript
-import { Resource } from 'harper';
-
-export class Widget extends Resource {
-	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
-	static path = '/widget/:id/action/:action';
-	static get(target) {
-		return { id: target.id, action: target.action };
-	}
-}
-
 export class Files extends Resource {
 	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
 	static path = '/files/*rest';
@@ -1493,28 +1655,27 @@ export class Files extends Resource {
 }
 ```
 
-##### Programmatic registration
+**Root-relative fixed route:**
 
 ```javascript
-import { Resource } from 'harper';
-
-export class Foo extends Resource {
+export class AcmeChallenge extends Resource {
+	static path = '/.well-known/acme-challenge/:token';
 	static get(target) {
-		return { data: doSomething() };
+		return { token: target.token };
 	}
 }
-
-server.resources.set('my-path', Foo);
 ```
 
 #### Notes
 
-- A bare `*` wildcard (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
-- Resolution order: exact/static paths always win over parameterized ones. Among parameterized routes, more specific paths win — a literal segment beats `:param`, which beats `*`, compared left to right.
-- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
-- If a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
+- URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+- A leading `/` in `static path` makes the path root-relative (top-level), independent of the file's location.
+- A leading `./` or a bare name in `static path` resolves relative to the component directory.
+- A bare `*` (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
+- `static path` takes precedence over the export name when both are present.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as URI templates.
+- When a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
 - Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
-- Harper runs as a single process — `tables`, `databases`, and other APIs are the same live, process-wide objects regardless of which component accesses them.
 
 ### 3.2 Extending Tables
 
@@ -1622,23 +1783,25 @@ if (!authorized) {
 
 ### 3.3 Programmatic Table Requests
 
-Instructions for the agent to interact with Harper tables programmatically using the `tables` object and its query API.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
 
 #### When to Use
 
-Apply this rule when writing server-side code that reads from or writes to Harper tables directly — for example, in request handlers, background jobs, or SSR rendering — without going through the REST API. Use it whenever you need to construct queries with `conditions`, `select`, `sort`, or `search(`.
+Apply this rule when writing server-side Harper component code that reads from or writes to tables directly — for example, in HTTP handlers, background jobs, timers, or SSR render functions. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, `limit`, or `offset`, or when you need explicit transaction control via `transaction()`.
 
 #### How It Works
 
-1. **Import `tables`**: Pull `tables` from the `harper` package. Each property on `tables` corresponds to a table defined in `schema.graphql`.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. Each property is the table class implementing the Resource API.
 
    ```javascript
-   import { tables } from 'harper';
+   import { tables, transaction } from 'harper';
    const { Product } = tables;
-   // same as: databases.data.Product
+   // equivalent to: databases.data.Product
    ```
 
-2. **Define your schema**: Declare tables with `@table` in `schema.graphql`. Each type becomes a property on `tables`.
+   For standalone components, run `npm link harper` so imports resolve to the live runtime.
+
+2. **Define your schema with `@table`**: Tables must be declared in `schema.graphql`. Mark attributes you intend to sort or filter on with `@indexed`.
 
    ```graphql
    type Product @table {
@@ -1648,15 +1811,7 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    }
    ```
 
-3. **Create and modify records**: Use `create`, `patch`, and `get` for basic CRUD.
-
-   ```javascript
-   const created = await Product.create({ name: 'Shirt', price: 9.5 });
-   await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
-   const record = await Product.get(created.id);
-   ```
-
-4. **Query with `search(`**: Pass a query object to `Product.search(query)`. It returns an async iterable.
+3. **Query records with `search(`**: Pass a Query object to `search(`. Iterate results with `for await`.
 
    ```javascript
    const query = {
@@ -1667,7 +1822,7 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    }
    ```
 
-5. **Build `conditions`**: Each condition object filters records. Nest conditions with `operator` for boolean logic.
+4. **Build `conditions`**: Each condition object supports these properties:
 
    | Property     | Description                                                                                                                                              |
    | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1677,29 +1832,31 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    | `conditions` | Nested conditions array                                                                                                                                  |
    | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
 
-6. **Use `select`** to control which properties are returned. Accepts an array of property names, a string for a single property, or nested objects for relationships.
+5. **Control result shape with `select`**: Pass an array of property names, a single string, or nested objects for relationships.
 
    ```javascript
-   // Array of names
+   // Scalar fields only
    Product.search({ select: ['name', 'price'] });
 
-   // Nested relationship select
+   // Partial related record
    Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
-   Special `select` values:
-   - `$id` — returns the primary key regardless of its name
-   - `$updatedtime` — returns the last-updated timestamp
-   - `$distance` — returns the computed distance when querying a vector index
+   Special `select` values: `$id`, `$updatedtime`, `$distance`.
 
-7. **Use `addTo`** for concurrent-safe numeric increments (CRDT incrementation, safe across threads and nodes).
+6. **Paginate with `limit` and `offset`**:
 
    ```javascript
-   const record = await Product.update(target.id);
-   record.addTo('quantity', -1);
+   Product.search({ conditions: [...], limit: 20, offset: 40 });
    ```
 
-8. **Apply `sort`, `limit`, and `offset`** for ordering and pagination. A `sort` attribute must be `@indexed`, or at least one `conditions` entry must be present. Pass `allowFullScan: true` to permit an unconditional ordered scan.
+7. **Sort with `sort`**: The `sort` object accepts `attribute`, `descending` (default `false`), and `next` for tie-breaking. Harper uses an index for sort order — the sort `attribute` must be `@indexed`, **or** at least one entry in `conditions` must be present.
+
+   Sorting by a non-indexed attribute with zero conditions raises:
+
+   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+
+   Note: `@primaryKey` alone is treated as not indexed for sort purposes. To scan the whole table in primary-key order, add an open-ended condition:
 
    ```javascript
    Product.search({
@@ -1708,15 +1865,78 @@ Apply this rule when writing server-side code that reads from or writes to Harpe
    });
    ```
 
-   | Sort 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)            |
+   Alternatively, pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
+
+8. **Debug query planning with `explain` and `enforceExecutionOrder`**:
+   - `explain: true` — returns conditions reordered as Harper will execute them.
+   - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling automatic re-ordering.
+
+9. **Use `addTo` for concurrent-safe numeric updates**: `addTo` uses CRDT incrementation, safe across threads and nodes.
+
+   ```javascript
+   const record = await Product.update(32);
+   record.addTo('quantity', -1);
+   ```
+
+10. **Wrap background work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a 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                | Description                                            |
+    | --------------------- | ------------------------------------------------------ |
+    | `commit()`            | Commits the current transaction                        |
+    | `abort()`             | Aborts and resets the transaction                      |
+    | `resetReadSnapshot()` | Resets the read snapshot to the latest committed state |
+    | `timestamp`           | Timestamp associated with the current transaction      |
+
+    **Atomicity**: all tables in the same database share one transactional context — writes across multiple tables commit atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
+
+    If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — safe to call defensively.
+
+11. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
+
+    ```javascript
+    // vite.config
+    ssr: {
+    	external: ['harper'];
+    }
+    ```
 
 #### Examples
 
-**Nested conditions with `or`:**
+##### Full CRUD sequence
+
+```javascript
+import { tables } from 'harper';
+const { Product } = tables;
+
+// Create
+const created = await Product.create({ name: 'Shirt', price: 9.5 });
+
+// Patch
+await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
+
+// Retrieve by primary key
+const record = await Product.get(created.id);
+
+// Query with conditions
+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`
 
 ```javascript
 Product.search({
@@ -1733,25 +1953,41 @@ Product.search({
 });
 ```
 
-**Chained attribute reference (relationship join):**
+##### Chained attribute reference (join/relationship)
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-**Deep nested `select` across multiple relationships:**
+##### Background job with `transaction()`
 
 ```javascript
-Product.search({
-	select: [
-		'id',
-		'name',
-		{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
-	],
-});
+import { isMainThread } from 'node:worker_threads';
+import { tables, transaction } from 'harper';
+const { MyTable } = tables;
+
+if (isMainThread) {
+	let running = false;
+	setInterval(async () => {
+		if (running) return;
+		running = true;
+		try {
+			let data = await (await fetch('https://example.com/data')).json();
+			await transaction(async (txn) => {
+				for (let item of data) {
+					await MyTable.put(item, txn);
+				}
+			});
+		} catch (error) {
+			logger.error('hourly import failed', error);
+		} finally {
+			running = false;
+		}
+	}, 3600000);
+}
 ```
 
-**SSR usage — read directly from `tables` in a render function:**
+##### SSR render with `tables`
 
 ```typescript
 import { tables } from 'harper';
@@ -1764,12 +2000,10 @@ export async function render(url: string): Promise<string> {
 
 #### Notes
 
-- Scope destructive operations (`update`, `patch`, `delete`) with specific `conditions` and validate the affected set before writing. These operate on live data and are not easily reversible.
-- Sorting by a bare `@primaryKey` with no conditions raises `HdbError: <attribute> is not indexed and not combined with any other conditions`. Add an open-ended condition or pass `allowFullScan: true`.
-- Selecting a relationship field without filtering on it behaves as a **LEFT JOIN**. Adding a condition on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN**.
-- A to-many relationship resolves to an array; `await` the property before iterating when needed.
-- `tables` and `databases.data` reference the same live objects — a record written through one component is immediately visible to all others.
-- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime.
+- `tables` and `databases` do **not** automatically apply role permissions — calls run in a trusted server-side context. Apply your own authorization controls before exposing results.
+- Destructive operations (`update`, `patch`, `delete`) act on live data and are not easily reversible. Scope them with specific `conditions` and validate the affected set before writing.
+- `tables` is the same live, process-wide object whether accessed as a global or via `import { tables } from 'harper'`. A record written through one component is immediately visible to every other.
+- Run `npm link harper` for components in their own directory to ensure typings match the running installation.
 
 ### 3.4 TypeScript Type Stripping in Harper
 
@@ -1988,11 +2222,11 @@ 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 remote Harper Fabric cluster.
+Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cloud cluster.
 
 #### When to Use
 
-Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. This includes first-time deploys, redeployments, rollbacks, and CI/CD pipeline deployments. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) to set up a cluster before deploying.
+Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. This includes first-time deploys, redeployments, rollbacks, CI/CD pipeline deploys, and provisioning credentials for private repositories. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for setting up the cluster before deploying.
 
 #### How It Works
 
@@ -2003,7 +2237,7 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
    # Provide cluster username and password when prompted
    ```
 
-2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials need to be repeated.
+2. **Deploy the application**: After login, run `harper deploy` without repeating credentials. Set `restart=true` and `replicated=true` for a production deploy.
 
    ```bash
    harper deploy \
@@ -2014,30 +2248,42 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
      replicated=true
    ```
 
-3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and upload the current local directory.
+3. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables before calling `harper deploy`.
 
-   | Value                                                | Effect                                           |
-   | ---------------------------------------------------- | ------------------------------------------------ |
-   | _(omitted)_                                          | Packages and deploys the current local directory |
-   | `"@harperdb/status-check"`                           | npm package                                      |
-   | `"HarperDB/status-check"`                            | GitHub shorthand                                 |
-   | `"https://github.com/HarperDB/status-check"`         | GitHub URL                                       |
-   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                             |
-   | `"https://example.com/application.tar.gz"`           | Tarball URL                                      |
+   ```bash
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
+
+4. **Choose a package source**: The `package` field accepts any valid npm dependency value. Select the form that matches your source:
+
+   | Source                  | `package` value                                      |
+   | ----------------------- | ---------------------------------------------------- |
+   | Current local directory | Omit `package`                                       |
+   | npm package             | `"@harperdb/status-check"`                           |
+   | GitHub (public)         | `"HarperFast/status-check"` or full URL              |
+   | Private repo (SSH)      | `"git+ssh://git@github.com:HarperDB/secret-app.git"` |
+   | Tarball                 | `"https://example.com/application.tar.gz"`           |
 
    For git tags, use the `semver` directive:
 
    ```
-   HarperDB/application-template#semver:v1.0.0
+   HarperFast/application-template#semver:v1.0.0
    ```
 
-4. **Deploy by reference (optional)**: Instead of uploading a snapshot, send a pinned git reference so the cluster fetches and builds that exact commit. Use `by_ref=true` to resolve the current commit from the local repository automatically.
+5. **Deploy by reference for reproducible deploys**: Pass `by_ref=true` to send a pinned git SHA instead of uploading a snapshot. The cluster fetches and builds from that exact commit.
 
    ```bash
    harper deploy by_ref=true restart=true replicated=true
    ```
 
-   Use `ref` to deploy a specific commit, tag, or branch (resolved to a full SHA before sending):
+   Use `ref` to target a specific commit, tag, or branch (resolved to a full SHA before sending):
 
    ```bash
    # Deploy a specific tag
@@ -2047,53 +2293,32 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
    harper deploy ref=9f8c2a1 restart=true replicated=true
    ```
 
-   **Key `by_ref` parameters:**
+   **Key constraints for `ref` values:**
+   - Must name something a clone can fetch: `refs/heads/*` and `refs/tags/*`, or a bare branch or tag name.
+   - Anything else (e.g., `refs/pull/123/head`) is rejected up front.
+   - If a ref can't be resolved, the deploy stops — run `git fetch` and retry, or pass a full commit SHA.
+   - Commit and push before deploying: the cluster clones from the remote and only sees pushed commits.
 
-   | Parameter    | Required | Description                                                                                                                 |
-   | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
-   | `by_ref`     | —        | Build the package reference from the local repository                                                                       |
-   | `ref`        | optional | Deploy a specific commit, tag, or branch instead of `HEAD`. Implies `by_ref`.                                               |
-   | `credential` | optional | Set to `true` to authenticate the clone with the stored credential for the repository's host. Omit for public repositories. |
-
-   > Commit and push before deploying by reference. The cluster clones from the remote and only sees pushed commits. Run `git fetch` if the unpushed-commit check fires for a commit you know you pushed.
-
-5. **Authenticate for CI/CD**: Use environment variables instead of `harper login` for automated pipelines.
+6. **Deploy private repositories by reference**: Pass `credential=true` alongside `by_ref=true`. The CLI attaches a credentials reference; the cluster resolves the secret in memory at clone time — no token travels in the operation body or lands on disk.
 
    ```bash
-   export HARPER_CLI_USERNAME=<username>
-   export HARPER_CLI_PASSWORD=<password>
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     target=<remote> \
-     restart=true \
-     replicated=true
+   harper deploy by_ref=true credential=true restart=true replicated=true
    ```
 
-6. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source to provision a deploy credential. Run this with an administrative credential, not the CI identity.
+7. **Provision a deploy credential for private sources**: Run `harper deploy setup=true` once per component and source. This is interactive and requires **super_user** — run it with an administrative credential, not the CI identity.
 
    ```bash
    harper deploy setup=true
    ```
 
-   Then pass `credential=true` on subsequent deploys:
-
-   ```bash
-   harper deploy by_ref=true credential=true restart=true replicated=true
-   ```
+   This 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`, in the component-scoped tier.
+   4. Grants the component permission to resolve it with `grant_secret`.
+   5. Prints the `credentials` reference for the deploy to use.
 
-7. **Use inline auth for one-off commands (not recommended for production)**: Pass `auth_username` and `auth_password` directly. These take precedence over environment variables and saved login tokens.
-
-   ```bash
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     auth_username=<username> \
-     auth_password=<password> \
-     target=<remote> \
-     restart=true \
-     replicated=true
-   ```
+   Use a **fine-grained** personal access token (PAT) scoped to **Contents: Read-only** on the specific repository. Avoid session tokens from `gh` CLI — they typically carry `repo`, `read:org`, `gist`, and `workflow` scopes across your whole account.
 
 #### Examples
 
@@ -2103,63 +2328,50 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
 harper login https://my-cluster.harperdbcloud.com
 harper deploy \
   project=my-app \
-  package="@myorg/my-app" \
+  package="HarperFast/my-app" \
   target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy current directory as a snapshot:**
+**CI/CD deploy using environment variables:**
 
 ```bash
+export HARPER_CLI_USERNAME=admin
+export HARPER_CLI_PASSWORD=secret
 harper deploy \
   project=my-app \
+  package="HarperFast/my-app" \
   target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy a pinned tag by reference:**
-
-```bash
-harper deploy ref=v1.2.0 restart=true replicated=true
-```
-
-**Deploy a private repository by reference with a stored credential:**
-
-```bash
-harper deploy by_ref=true credential=true restart=true replicated=true
-```
-
-**GitHub Actions — deploy the pull request head commit explicitly:**
+**Deploy by reference in GitHub Actions (pull request):**
 
 ```bash
 harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
 ```
 
-**CI/CD deploy using environment variables:**
+**Deploy a private repo by reference with a provisioned credential:**
 
 ```bash
-export HARPER_CLI_USERNAME=<username>
-export HARPER_CLI_PASSWORD=<password>
-harper deploy \
-  project=my-app \
-  package="HarperDB/my-app#semver:v1.0.0" \
-  target=https://my-cluster.harperdbcloud.com \
-  restart=true \
-  replicated=true
+# Provision once (run as super_user)
+harper deploy setup=true
+
+# Deploy subsequently
+harper deploy by_ref=true credential=true restart=true replicated=true
 ```
 
 #### Notes
 
-- `harper login` stores an authentication token so subsequent `harper deploy` commands do not require credentials to be repeated.
-- Inline `auth_username`/`auth_password` parameters take precedence over environment variables, which take precedence over saved login tokens.
-- For SSH-based private repos, register keys with the `add_ssh_key` operation before deploying.
-- `by_ref` deploys build from source on each cluster node. If your application requires a build step that cannot run on the node, deploy a built payload (omit `by_ref`) instead.
-- `harper deploy setup=true` requires **super_user** privileges. Provision credentials with an administrative account, not the CI identity.
-- Tags and branches passed to `ref` are resolved to a full commit SHA locally before the deploy is sent. If resolution fails, run `git fetch` and retry, or pass a full commit SHA directly.
-- The `refs/pull/<n>/head` style refs are rejected; use `ref=${{ github.event.pull_request.head.sha }}` in GitHub Actions pull request workflows instead.
-- Deploy credentials provisioned via `harper deploy setup=true` are stored scoped to the component and reused on every subsequent deploy, including rollbacks.
+- `auth_username` and `auth_password` can be passed directly as deploy parameters for one-off commands, but this is not recommended for production. Dedicated authentication parameters take precedence over environment variables and saved login tokens.
+- The `enc:v1:` envelope means the plaintext token never leaves your machine — only ciphertext is stored and replicated.
+- Deploy credentials are stored scoped to the component, never in the global `processEnv` tier. If a global secret exists at the derived name, it is converted to the component-scoped tier automatically.
+- Because stored credentials are durable, later deploys and rollbacks reuse them without re-entering anything.
+- The unpushed-commit check is skipped under GitHub Actions; the dirty-tree warning still applies.
+- Deploying by reference means the cluster installs and builds from source. If your application requires a build step that cannot run on the node, deploy the built output as a payload deploy instead.
+- For SSH-based private repos, use the `add_ssh_key` operation to register keys before deploying.
 
 ### 4.2 Creating a Harper Fabric Account and Cluster
 
@@ -2598,11 +2810,11 @@ myApp:
 
 ### 4.7 v5 Upgrade: Breaking Changes and Migration Guide
 
-Instructions for the agent to apply all required breaking-change fixes and recommended updates when migrating a Harper application to v5.
+Instructions for the agent to apply when migrating a Harper application to v5, covering all breaking changes and required code updates.
 
 #### When to Use
 
-Apply this rule whenever upgrading an existing Harper application to v5, encountering v5 runtime errors related to module imports, `Table.get` return values, transaction context, process spawning, or VM module loading. Also apply when configuring `harperdb-config.yaml` for a v5 deployment.
+Apply this rule when upgrading an existing Harper application to v5, when encountering runtime errors related to renamed packages, changed APIs, or security restrictions after a v5 upgrade, or when scaffolding new v5-compatible application code.
 
 #### How It Works
 
@@ -2612,22 +2824,20 @@ Apply this rule whenever upgrading an existing Harper application to v5, encount
    import { tables } from 'harper';
    ```
 
-2. **Enable `allowInstallScripts` if packages require install scripts**: Harper v5 uses `--ignore-scripts` by default when installing packages. If your application requires installation scripts (e.g., to install additional binaries), set the `allowInstallScripts` option when deploying.
+2. **Enable `allowInstallScripts` if packages require install scripts**: Harper v5 uses `--ignore-scripts` by default when installing packages. If a package requires execution of install scripts (e.g., to install native binaries), set the `allowInstallScripts` option when deploying.
 
-3. **Update `Table.get` usage — return value is now a plain frozen record object**: `Table.get` no longer returns an instance of the table class. The returned object is frozen and does not have table instance methods.
-   - Replace `wasLoadedFromSource()` with `target.loadedFromSource`:
+3. **Update `Table.get` usage — return value is now a frozen record object**: `Table.get` now returns a plain record object, not a table class instance. The record is frozen; you cannot add or mutate properties directly.
+   - Replace direct property mutation:
 
      ```javascript
-     // OLD — no longer works
-     const record = await Table.get(id);
-     if (record.wasLoadedFromSource()) {
-     	// record was loaded from origin (not cache)
-     }
+     let record = await Table.get(id);
+     record = { ...record, property: 'changed' };
      ```
 
+   - Replace `wasLoadedFromSource()` with `loadedFromSource` on the `target` object:
+
      ```javascript
-     // NEW
-     const target = new RequestTarget(); // note that this is passed in if you are overriding the `get` method
+     const target = new RequestTarget();
      target.id = id;
      const record = await Table.get(target);
      if (target.loadedFromSource) {
@@ -2635,107 +2845,86 @@ Apply this rule whenever upgrading an existing Harper application to v5, encount
      }
      ```
 
-   - The record object still has `getUpdatedTime` and `getExpiresAt` methods available.
+   The record objects still expose `getUpdatedTime` and `getExpiresAt` methods.
 
-   - **Handle frozen records**: The record object is frozen — you cannot add or remove properties directly. Copy and spread instead:
+4. **Update transaction and context handling using `getContext`**: Harper v5 uses asynchronous context tracking. Context and the current transaction are automatically carried to all downstream calls — you no longer pass context explicitly. Import `getContext` and `transaction` from `harper`:
 
-     ```javascript
-     // OLD — throws in v5
-     const record = await Table.get(id);
-     record.property = 'changed';
-     ```
+   ```javascript
+   import { getContext, transaction } from 'harper';
+   ```
 
-     ```javascript
-     // NEW
-     let record = await Table.get(id);
-     record = { ...record, property: 'changed' };
-     ```
+   If your code previously omitted context to escape a transaction (e.g., to poll for updated data), explicitly commit the transaction and/or wrap each read in a new `transaction()` call:
 
-4. **Update transaction and context handling**: Harper v5 uses asynchronous context tracking. Context and the current transaction are automatically carried to all calls, including `Table.get`. Code that previously omitted context to escape a transaction must now explicitly commit or start a new transaction.
-   - Import `getContext` and `transaction` from `harper`:
+   ```javascript
+   import { setTimeout as delay } from 'node:timers/promises';
+   import { getContext, transaction } from 'harper';
+   class MyResource {
+   	static async get(target) {
+   		await getContext().transaction.commit();
+   		while ((await transaction(() => Table.get(target))).status !== 'ready') {
+   			await delay(100);
+   		}
+   		return Table.get(target);
+   	}
+   }
+   ```
 
-     ```javascript
-     import { getContext, transaction } from 'harper';
-     ```
+5. **Register allowed spawn commands via `allowedSpawnCommands`**: `spawn` and `execFile` may only launch executables listed in `applications.allowedSpawnCommands` in `harperdb-config.yaml`. Only the first token of the command is matched. `exec` is not usable through the substituted module; `execSync` always throws.
 
-   - Explicitly commit the current transaction before reading updated data:
+   ```yaml
+   applications:
+     allowedSpawnCommands:
+       - npm
+       - node
+   ```
 
-     ```javascript
-     import { setTimeout as delay } from 'node:timers/promises';
-     import { getContext, transaction } from 'harper';
-     class MyResource {
-     	static async get(target) {
-     		await getContext().transaction.commit();
-     		while ((await transaction(() => Table.get(target))).status !== 'ready') {
-     			await delay(100);
-     		}
-     		return Table.get(target);
-     	}
-     }
-     ```
+   Additionally, `spawn`, `execFile`, and `fork` now require a `name` property in the `options` argument to prevent process multiplication across threads.
 
-5. **Register allowed spawn commands via `allowedSpawnCommands`**: Any `spawn` or `execFile` call may only launch executables listed in `applications.allowedSpawnCommands` in `harperdb-config.yaml`. The `exec` function is not usable through the substituted module, and `execSync` always throws. The `spawn`, `execFile`, and `fork` functions also require a `name` property in the `options` argument to prevent process multiplication across threads.
+6. **Use `saveBeforeCommit` instead of `blob.save()`**: The `blob.save()` method has been removed. Pass the `saveBeforeCommit` flag in the options to the `Blob` constructor instead.
 
-6. **Replace `blob.save()` with `saveBeforeCommit`**: The `blob.save()` method has been removed. Use the `saveBeforeCommit` flag in the options passed to the `Blob` constructor instead.
+7. **Handle `headers` on returned response objects**: If you return an object from a REST method with a `headers` property, Harper v5 will use it as the response headers.
 
-7. **Configure the `moduleLoader` and `lockdown` settings**: Harper v5 loads application modules through Node.js's VM module API. Control all behavior in the `applications` section of `harperdb-config.yaml`:
+8. **Configure the VM module loader and `lockdown` in `harperdb-config.yaml`**: v5 loads application modules through Node.js's VM module API. Control all behavior under the `applications` key:
 
    ```yaml
    applications:
-     lockdown: freeze-after-load # default; see below
-     moduleLoader: vm-current-context # vm-current-context (default) | vm | native | compartment
-     dependencyLoader: auto # auto (default) | app | native
-     allowedDirectory: app # app (default) | any
-     allowedSpawnCommands: # see "Spawning new processes" above
+     lockdown: freeze-after-load
+     moduleLoader: vm-current-context
+     dependencyLoader: auto
+     allowedDirectory: app
+     allowedSpawnCommands:
        - npm
        - node
-     # allowedBuiltinModules: [] # if omitted, all Node.js built-ins are allowed
    ```
 
    **`moduleLoader` options:**
 
    | Value                | Behavior                                                                                                                         |
    | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-   | `vm-current-context` | Default. VM loader in Harper's own context; shares intrinsics with Harper for best compatibility.                                |
-   | `vm`                 | VM loader in a separate per-application context with its own intrinsics; stronger isolation but can cause `instanceof` failures. |
-   | `native`             | Standard Node.js `import()` with no VM loader; application-specific context (tagged logging, per-app `config`) not available.    |
-   | `compartment`        | SES Compartment-based loading; for specialized sandboxing only.                                                                  |
+   | `vm-current-context` | Default. VM loader in Harper's own context; shares intrinsics with Harper. Best compatibility.                                   |
+   | `vm`                 | VM loader in a separate per-application context with its own intrinsics. Stronger isolation but may cause `instanceof` failures. |
+   | `native`             | Standard Node.js `import()`. No VM loader; application-specific context (`logger`, `config`) unavailable.                        |
+   | `compartment`        | SES Compartment-based loading. For specialized sandboxing only.                                                                  |
 
    **`lockdown` options:**
 
-   | Value               | Behavior                                                      |
-   | ------------------- | ------------------------------------------------------------- |
-   | `freeze-after-load` | Default. Freezes intrinsics after all components have loaded. |
-   | `freeze`            | Freezes intrinsics before loading any application code.       |
-   | `ses`               | Full SES lockdown via the `ses` package; strictest.           |
-   | `none`              | No lockdown. Use as a temporary workaround only.              |
-   - To disable the VM loader entirely and restore pre-v5 behavior:
-
-     ```yaml
-     applications:
-       moduleLoader: native
-     ```
-
-   - To restrict which Node.js built-ins are accessible:
+   | Value               | Behavior                                                |
+   | ------------------- | ------------------------------------------------------- |
+   | `freeze-after-load` | Default. Freezes intrinsics after all components load.  |
+   | `freeze`            | Freezes intrinsics before loading any application code. |
+   | `ses`               | Full SES lockdown via the `ses` package. Strictest.     |
+   | `none`              | No lockdown. Use as a temporary workaround only.        |
 
-     ```yaml
-     applications:
-       allowedBuiltinModules:
-         - fs
-         - path
-         - http
-     ```
-
-   - To allow loading modules from outside the application directory:
+   To disable the VM loader entirely and restore pre-v5 behavior:
 
-     ```yaml
-     applications:
-       allowedDirectory: any
-     ```
+   ```yaml
+   applications:
+     moduleLoader: native
+   ```
 
 #### Examples
 
-**Full transaction context migration:**
+**Full transaction polling pattern (v5):**
 
 ```javascript
 import { setTimeout as delay } from 'node:timers/promises';
@@ -2743,9 +2932,7 @@ import { getContext, transaction } from 'harper';
 
 class MyResource {
 	static async get(target) {
-		// Explicitly commit the transaction to see updated data
 		await getContext().transaction.commit();
-		// Start a new transaction for each get to see the latest data
 		while ((await transaction(() => Table.get(target))).status !== 'ready') {
 			await delay(100);
 		}
@@ -2754,11 +2941,9 @@ class MyResource {
 }
 ```
 
-**`Table.get` with `loadedFromSource` check:**
+**Checking `loadedFromSource` after `Table.get`:**
 
 ```javascript
-import { tables } from 'harper';
-
 const target = new RequestTarget();
 target.id = id;
 const record = await Table.get(target);
@@ -2780,14 +2965,27 @@ applications:
     - node
 ```
 
+**Restricting allowed built-in modules:**
+
+```yaml
+applications:
+  allowedBuiltinModules:
+    - fs
+    - path
+    - http
+```
+
 #### Notes
 
-- Use `getContext` (imported from `harper`) to access the current transaction anywhere in application code without passing context explicitly through every call.
-- Harper functions and APIs should be accessed through the `harper` package rather than through global variables.
-- Use `static` methods on Resources/Tables to implement endpoints, and access request information from the request `target` argument or via `getContext`.
-- `lockdown: none` is only a temporary workaround for dependencies that mutate intrinsic prototypes at runtime; do not leave it set in production.
-- Under `lockdown: ses`, the constrained (https-only) `fetch` is applied only in `vm` mode. In `vm-current-context` and `native` modes, application code uses the standard global `fetch`.
-- In production, `allowedDirectory: app` is the default; dev mode installs default to `allowedDirectory: any`.
+- Always import Harper APIs from `'harper'`, not from global variables or `'harperdb'`.
+- `getContext` is exported from `'harper'` and provides access to the current transaction without passing context explicitly.
+- Record objects returned by `Table.get` are frozen — spread into a new object before modifying.
+- `loadedFromSource` is a property on the `target` object, replacing the removed `wasLoadedFromSource()` instance method.
+- `saveBeforeCommit` replaces the removed `blob.save()` method.
+- The `headers` property on a returned REST response object is used as response headers.
+- Under `lockdown: ses`, the constrained `fetch` applies only in `vm` mode. In `vm-current-context` and `native` modes, application code uses the standard global `fetch`.
+- In production, `allowedDirectory: app` is the default; modules outside the application directory tree will throw. Set `allowedDirectory: any` only if legitimately required.
+- `dependencyLoader: native` is a narrower option than `moduleLoader: native` — it uses native loading only for npm packages while keeping the VM loader for first-party application source files.
 
 ### 4.8 Delegating to the Built-in Agent