@harperfast/template-react-ts-studio 1.12.8 → 1.12.9

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

@@ -9,21 +9,30 @@ metadata:
     - reference/v5/database/schema.md#Overview
     - reference/v5/database/schema.md#Type Directives
     - reference/v5/database/schema.md#Field Directives
-  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
-  inputHash: ecb06058191ba29f
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: a644f4ea2f289f77
 ---
 
-# Schema Design and GraphQL Tooling
+# Schema Design Tooling
 
-Instructions for the agent to follow when designing Harper database schemas using GraphQL type definitions, core directives, and tooling configuration.
+Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
 ## When to Use
 
-Apply this rule when creating or modifying Harper schema files (`.graphql`), configuring 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.
+Apply this rule when creating or modifying Harper schema files (`.graphql`), configuring `graphqlSchema` in `config.yaml`, or deciding which directives to apply to tables and fields. Use it whenever a task involves defining tables, primary keys, indexes, or export behavior.
 
 ## How It Works
 
-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.
+1. **Register the schema file** in the component's `config.yaml` using the `graphqlSchema` plugin key:
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   ```
+
+   Both plugins and applications can specify schemas.
+
+2. **Mark types as tables** using `@table`. The type name becomes the table name by default:
 
    ```graphql
    type Dog @table {
@@ -34,79 +43,71 @@ Apply this rule when creating or modifying Harper schema files (`.graphql`), con
    }
    ```
 
-2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin:
+3. **Designate a primary key** on every table using `@primaryKey`. Primary keys must be unique; duplicate inserts are rejected. If no primary key is provided on insert, Harper auto-generates one:
+   - `String` or `ID` → UUID string
+   - `Int`, `Long`, or `Any` → auto-incrementing integer
 
-   ```yaml
-   graphqlSchema:
-     files: 'schema.graphql'
-   ```
-
-   Both plugins and applications can specify schemas.
+   Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
 
-3. **Mark each type as a table** with `@table`. The type name becomes the table name by default.
+4. **Index fields for querying** using `@indexed`. Required for filtering by an attribute in REST queries, SQL, or NoSQL operations:
 
    ```graphql
-   type MyTable @table {
+   type Breed @table {
    	id: Long @primaryKey
+   	name: String @indexed
    }
    ```
 
-   Key `@table` arguments:
+   If the field value is an array, each element is individually indexed. Null values are indexed by default.
 
-   | 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. **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.
+5. **Expose tables as REST/MQTT endpoints** using `@export`. The optional `name` parameter sets the URL path segment; without it, the type name is used:
 
    ```graphql
-   type Product @table {
+   type MyTable @table @export(name: "my-table") {
    	id: Long @primaryKey
-   	name: String
    }
    ```
 
-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.
+   `@export` alone does not serve HTTP traffic — REST must also be enabled for the application via `rest: true` in `config.yaml` or Harper's built-in default. `@export` is a routing directive, not access control; omitting it returns 404 but does not protect the data.
+
+6. **Configure `@table` arguments** to control database placement, expiration, replication, and caching behavior. Key arguments:
+
+   | Argument             | Type      | Default                       | Description                                                    |
+   | -------------------- | --------- | ----------------------------- | -------------------------------------------------------------- |
+   | `table`              | `String`  | type name                     | Override the table name                                        |
+   | `database`           | `String`  | `"data"`                      | Database to place the table in                                 |
+   | `expiration`         | `Int`     | —                             | Seconds until a record goes stale                              |
+   | `eviction`           | `Int`     | `0`                           | Additional seconds after `expiration` before physical removal  |
+   | `scanInterval`       | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                 |
+   | `replicate`          | `Boolean` | `true`                        | Enable replication of this table                               |
+   | `cacheControl`       | `String`  | —                             | `Cache-Control` header on anonymous GET/HEAD 200/304 responses |
+   | `randomAccessFields` | `Boolean` | `storage.randomAccessFields`  | Pin this table's record encoding                               |
+
+7. **Seal a type** with `@sealed` to prevent records from including properties beyond those declared:
 
    ```graphql
-   type Product @table {
+   type StrictRecord @table @sealed {
    	id: Long @primaryKey
-   	category: String @indexed
-   	price: Float @indexed
+   	name: String
    }
    ```
 
-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.
+8. **Use timestamp directives** for automatic record lifecycle tracking:
+   - `@createdTime` — assigns Unix epoch milliseconds on record creation
+   - `@updatedTime` — assigns Unix epoch milliseconds on each update
+   - `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); authoritative over the table-level `expiration` default
+
+9. **Use `@embed`** to automatically compute an embedding vector for an attribute whenever the source field is written (requires `source` and `model` arguments; field type must be `[Float]`):
 
    ```graphql
-   type MyTable @table @export(name: "my-table") {
+   type Document @table {
    	id: Long @primaryKey
+   	text: String
+   	embedding: [Float] @embed(source: "text", model: "default")
    }
    ```
 
-   `@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.
+10. **Use `@hidden`** on types or fields to suppress them from MCP tool descriptors and the OpenAPI document. This is a metadata-visibility directive only — it does not restrict data access. Use `attribute_permissions` on roles for field-level access control.
 
 ## Examples
 
@@ -136,7 +137,7 @@ type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
 }
 ```
 
-**Exported table with cache control:**
+**Exported table with public cache control:**
 
 ```graphql
 type Product @table(cacheControl: "public, max-age=60") @export {
@@ -146,14 +147,12 @@ type Product @table(cacheControl: "public, max-age=60") @export {
 }
 ```
 
-**Table with lifecycle fields and indexing:**
+**Table with multiple `@table` arguments combined:**
 
 ```graphql
 type Event @table(database: "analytics", expiration: 86400) {
 	id: Long @primaryKey
 	name: String @indexed
-	createdAt: Long @createdTime
-	updatedAt: Long @updatedTime
 }
 ```
 
@@ -167,12 +166,15 @@ type Session @table {
 }
 ```
 
-**Sealed table preventing extra properties:**
+**Table with timestamp tracking and indexed fields:**
 
 ```graphql
-type StrictRecord @table @sealed {
+type Order @table(database: "commerce") @export {
 	id: Long @primaryKey
-	name: String
+	userId: String @indexed
+	status: String @indexed
+	createdAt: Long @createdTime
+	updatedAt: Long @updatedTime
 }
 ```
 
@@ -185,10 +187,10 @@ graphqlSchema:
 
 ## Notes
 
-- 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.
+- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
+- Disabling replication (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.
+- `cacheControl` emits the header only on anonymous (unauthenticated) GET/HEAD `200`/`304` responses. Authenticated responses receive `Cache-Control: private, no-cache` regardless of the declaration. The header is never emitted on `401` responses.
+- `@expiresAt` requires an absolute Unix epoch millisecond timestamp, not a duration. Negative values are ignored and fall back to the table default. A full-record `put` that omits the field clears it; a `patch` preserves it.
+- Eviction removes non-indexed record data but does not remove a record from its secondary indexes; indexes remain functional for evicted records, with full records fetched on demand.
+- `scanInterval` is clock-aligned to the server's local timezone, not startup-aligned — the server's startup time does not affect when eviction runs.
+- `randomAccessFields` pins the table's encoding at creation time. Editing the argument later does not repin an existing table. Omit it to follow the global `storage.randomAccessFields` setting.

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

@@ -8,8 +8,8 @@ metadata:
     - reference/v5/database/api.md#Streaming
     - reference/v5/database/api.md#`BlobOptions`
     - reference/v5/database/api.md#Blob Coercion
-  sourceCommit: f37a8c4021e20d5c74c1d339a6b6c8c196b5603e
-  inputHash: 92e03eb0b830f335
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: 753b85cbdcef9188
 ---
 
 # Using the Blob Data Type
@@ -18,11 +18,11 @@ Instructions for the agent to follow when storing and retrieving large binary co
 
 ## When to Use
 
-Apply this rule when a schema field needs to store large binary content such as images, video, audio, or large HTML — typically content larger than 20KB. Use `Blob` instead of `Bytes` when streaming support and out-of-record storage are required. See [handling-binary-data.md](handling-binary-data.md) for broader binary data guidance.
+Apply this rule when a schema field needs to store large binary content such as images, video, audio, or large HTML — typically content larger than 20KB. Use `Blob` instead of `Bytes` when streaming support and out-of-record storage are required. See [handling-binary-data](handling-binary-data.md) for broader binary data guidance.
 
 ## How It Works
 
-1. **Declare a `Blob` field in your schema**: Add a field typed as `Blob` to your `@table` type.
+1. **Declare a `Blob` field in your schema**: Add a field typed as `Blob` to your table definition.
 
    ```graphql
    type MyTable @table {
@@ -31,14 +31,14 @@ Apply this rule when a schema field needs to store large binary content such as
    }
    ```
 
-2. **Create and store a blob with `createBlob()`**: Pass a buffer or stream to `createBlob()`, then `put` the record.
+2. **Create and store a blob with `createBlob()`**: Pass a buffer, string, or stream to `createBlob()`, then `put` the record.
 
    ```javascript
    let blob = createBlob(largeBuffer);
    await MyTable.put({ id: 'my-record', data: blob });
    ```
 
-3. **Retrieve blob data using standard Web API methods**: The `Blob` type implements the Web API `Blob` interface. Use `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, or `.slice()` as needed.
+3. **Retrieve blob data using standard Web API methods**: Use `.bytes()`, `.text()`, or `.stream()` on the retrieved field.
 
    ```javascript
    let record = await MyTable.get('my-record');
@@ -47,7 +47,7 @@ Apply this rule when a schema field needs to store large binary content such as
    let stream = record.data.stream(); // ReadableStream
    ```
 
-4. **Use `saveBeforeCommit` when full write must precede commit**: By default, `Blob` is not ACID-compliant — a record can reference a blob before it is fully written. Set `saveBeforeCommit: true` to block the transaction until the blob is fully saved.
+4. **Use `saveBeforeCommit` when full write must complete before commit**: By default, blobs are not ACID-compliant — a record can reference a blob before it is fully written. Set `saveBeforeCommit: true` to block the transaction until the blob is fully saved.
 
    ```javascript
    let blob = createBlob(stream, { saveBeforeCommit: true });
@@ -55,13 +55,14 @@ Apply this rule when a schema field needs to store large binary content such as
    // put() resolves only after blob is fully written and record is committed
    ```
 
-5. **Register an error handler when returning a blob via REST**: Interrupted streams must be handled explicitly.
+5. **Register an error handler when returning a blob via REST**: Handle interrupted streams to avoid stale references.
 
    ```javascript
    export class MyEndpoint extends MyTable {
    	static async get(target) {
-   		const record = super.get(target);
-   		let blob = record.data;
+   		const record = await super.get(target);
+   		let blob = record?.data;
+   		if (!blob) return record;
    		blob.on('error', () => {
    			MyTable.invalidate(target);
    		});
@@ -70,19 +71,15 @@ Apply this rule when a schema field needs to store large binary content such as
    }
    ```
 
-6. **Rely on automatic coercion where applicable**: When a field is typed as `Blob` in the schema, any string or buffer assigned via `put`, `patch`, or `publish` is automatically coerced to a `Blob` — no manual `createBlob()` call is needed in those cases.
+6. **Pass `BlobOptions` to control storage behavior**: `createBlob()` accepts an options object as its second argument.
 
-### `BlobOptions` reference
-
-Pass an options object as the second argument to `createBlob()`.
-
-| Option             | Type      | Default     | Description                                                                                                              |
-| ------------------ | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `type`             | `string`  | `undefined` | MIME type to associate with the blob (e.g., `image/jpeg`). Readable via `blob.type` and used when serving HTTP.          |
-| `size`             | `number`  | `undefined` | Size of the data in bytes, if known ahead of time. Otherwise inferred from a buffer or determined as a stream completes. |
-| `saveBeforeCommit` | `boolean` | `false`     | Wait until the blob is fully written before the transaction commits.                                                     |
-| `compress`         | `boolean` | `false`     | Compress the stored data with deflate.                                                                                   |
-| `flush`            | `boolean` | `false`     | Flush the file to disk after writing, before the `createBlob` promise chain resolves.                                    |
+   | Option             | Type      | Default     | Description                                                                         |
+   | ------------------ | --------- | ----------- | ----------------------------------------------------------------------------------- |
+   | `type`             | `string`  | `undefined` | MIME type (e.g., `image/jpeg`). Used when serving HTTP and readable via `blob.type` |
+   | `size`             | `number`  | `undefined` | Size in bytes if known ahead of time; otherwise inferred                            |
+   | `saveBeforeCommit` | `boolean` | `false`     | Wait until blob is fully written before the transaction commits                     |
+   | `compress`         | `boolean` | `false`     | Compress stored data with deflate                                                   |
+   | `flush`            | `boolean` | `false`     | Flush file to disk after writing, before the `createBlob` promise chain resolves    |
 
 ## Examples
 
@@ -97,15 +94,13 @@ await Photo.put({ id, data: blob });
 
 ```javascript
 let blob = createBlob(incomingStream);
-// blob exists, but data is still streaming to storage
 await MyTable.put({ id: 'my-record', data: blob });
 
 let record = await MyTable.get('my-record');
-// blob data is accessible as it arrives
 let outgoingStream = record.data.stream();
 ```
 
-**Guarantee full write before commit using `saveBeforeCommit`:**
+**Wait for full write before commit:**
 
 ```javascript
 let blob = createBlob(stream, { saveBeforeCommit: true });
@@ -114,6 +109,7 @@ await MyTable.put({ id: 'my-record', data: blob });
 
 ## Notes
 
-- `Blob` stores data separately from the record. If you need the binary data to be a true, ACID-committed part of the record, use a `Bytes` field instead.
-- All standard Web API `Blob` methods — `.text()`, `.arrayBuffer()`, `.stream()`, `.slice()`, and `.bytes()` — are available on retrieved blob fields.
-- Without `saveBeforeCommit: true`, blobs are **not** ACID-compliant by default; a record can reference a blob before it is fully written to storage.
+- `Blob` implements the Web API `Blob` interface. All standard methods — `.text()`, `.arrayBuffer()`, `.stream()`, `.slice()`, and `.bytes()` — are available on retrieved blob fields.
+- Blobs are stored **separately from the record**, not within it. If you need the binary data to be a true ACID-committed part of the record, use a `Bytes` field instead.
+- Any string or buffer assigned to a `Blob`-typed field in a `put`, `patch`, or `publish` is automatically coerced to a `Blob` — manual `createBlob()` calls are not required in those cases.
+- Use `saveBeforeCommit: true` whenever downstream consumers must not read a partially written blob.

package/.agents/skills/harper-best-practices/rules/v5-upgrade.md

@@ -7,60 +7,82 @@ metadata:
   mode: generate
   sources:
     - release-notes/v5-lincoln/v5-migration.md
-  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
-  inputHash: 01c0fafb9afa68a0
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: 66ca7a9e265d006e
 ---
 
 # v5 Upgrade: Breaking Changes and Migration Guide
 
-Instructions for the agent to apply when migrating a Harper application to v5, covering all breaking changes and required code updates.
+Instructions for the agent to follow when migrating a Harper application to v5, covering all breaking changes and required code updates.
 
 ## When to Use
 
-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.
+Apply this rule when upgrading an existing Harper application from v4 to v5, when encountering runtime errors after upgrading, or when reviewing application code for v5 compatibility. Every breaking change listed here must be addressed before the application will behave correctly under v5.
 
 ## How It Works
 
-1. **Update the package import from `harperdb` to `harper`**: All application code must import from `harper`, not `harperdb`.
+1. **Update the package import**: Replace all imports from `'harperdb'` with `from 'harper'`.
 
    ```javascript
    import { tables } from 'harper';
    ```
 
-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.
+2. **Enable install scripts if needed**: Harper v5 runs `npm install` with `--ignore-scripts` by default. If your application requires install scripts (e.g., to compile native binaries), set `allowInstallScripts` in your deployment options.
 
-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:
+3. **Update `Table.get` usage**: `Table.get` now returns a plain frozen record object, not a table class instance. The `wasLoadedFromSource()` method no longer exists on the returned object. Replace it with `loadedFromSource` on the `RequestTarget`:
 
-     ```javascript
-     let record = await Table.get(id);
-     record = { ...record, property: 'changed' };
-     ```
+   ```javascript
+   // Before
+   const record = await Table.get(id);
+   if (record.wasLoadedFromSource()) {
+   	// record was loaded from origin (not cache)
+   }
+   ```
 
-   - Replace `wasLoadedFromSource()` with `loadedFromSource` on the `target` object:
+   ```javascript
+   // After
+   import { getContext } from 'harper';
+   const target = new RequestTarget();
+   target.id = id;
+   const record = await Table.get(target);
+   if (target.loadedFromSource) {
+   	// record was loaded from origin (not cache)
+   }
+   ```
 
-     ```javascript
-     const target = new RequestTarget();
-     target.id = id;
-     const record = await Table.get(target);
-     if (target.loadedFromSource) {
-     	// record was loaded from origin (not cache)
-     }
-     ```
+   The record objects do have `getUpdatedTime` and `getExpiresAt` methods available.
 
-   The record objects still expose `getUpdatedTime` and `getExpiresAt` methods.
+4. **Handle frozen records**: The record object returned by `Table.get` is frozen — you cannot mutate it directly. Copy it before modifying:
 
-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
+   // Before
+   const record = await Table.get(id);
+   record.property = 'changed';
+   ```
 
    ```javascript
-   import { getContext, transaction } from 'harper';
+   // After
+   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:
+5. **Register allowed spawn commands via `allowedSpawnCommands`**: `spawn` and `execFile` may only launch executables listed in `applications.allowedSpawnCommands` in `harper-config.yaml`. Only the first token of the command is matched. `exec` is not usable through the substituted module, and `execSync` always throws.
+
+   ```yaml
+   applications:
+     allowedSpawnCommands:
+       - npm
+       - node
+   ```
+
+   Additionally, `spawn`, `execFile`, and `fork` now require a `name` property in the `options` argument to prevent process multiplication across threads.
+
+6. **Update transaction and context usage**: Harper v5 uses asynchronous context tracking. `Table.get` and other calls now automatically inherit the current transaction. Code that previously omitted context to bypass a transaction will no longer work as expected. Explicitly commit the transaction or wrap calls in a new transaction to read updated data:
 
    ```javascript
    import { setTimeout as delay } from 'node:timers/promises';
    import { getContext, transaction } from 'harper';
+
    class MyResource {
    	static async get(target) {
    		await getContext().transaction.commit();
@@ -72,79 +94,70 @@ Apply this rule when upgrading an existing Harper application to v5, when encoun
    }
    ```
 
-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.
+   Use `getContext` (exported from `'harper'`) to access the current transaction anywhere without passing context explicitly.
 
-   ```yaml
-   applications:
-     allowedSpawnCommands:
-       - npm
-       - node
-   ```
+7. **Replace `blob.save()`**: The `blob.save()` method has been removed. Use the `saveBeforeCommit` flag in the options passed to the `Blob` constructor instead.
 
-   Additionally, `spawn`, `execFile`, and `fork` now require a `name` property in the `options` argument to prevent process multiplication across threads.
+8. **Handle response `headers`**: If you return an object from a REST method with a `headers` property, Harper v5 will use it as the response headers. Ensure any object you return that incidentally has a `headers` property is intentional.
 
-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.
+9. **Configure the module loader**: Harper v5 loads application modules through Node.js's VM module API. Control this with the `moduleLoader` setting:
 
-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.
+   | Value                | Behavior                                         |
+   | -------------------- | ------------------------------------------------ |
+   | `vm-current-context` | Default. Shares intrinsics with Harper.          |
+   | `vm`                 | Separate context and intrinsics per application. |
+   | `native`             | Standard `import()`, no application context.     |
+   | `compartment`        | SES Compartments; advanced and heavier.          |
 
-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:
+   The default (`vm-current-context`) avoids `instanceof` failures for values crossing the application/Harper boundary. Choose `vm` only if you need separate per-application intrinsics. Use `native` if the VM loader causes compatibility problems you cannot otherwise resolve.
+
+   To disable the VM loader entirely and restore pre-v5 behavior:
 
    ```yaml
    applications:
-     lockdown: freeze-after-load
-     moduleLoader: vm-current-context
-     dependencyLoader: auto
-     allowedDirectory: app
-     allowedSpawnCommands:
-       - npm
-       - node
+     moduleLoader: native
    ```
 
-   **`moduleLoader` options:**
+   Note: `logger` and per-app `config` are not available in `native` mode.
 
-   | Value                | Behavior                                                                                                                         |
-   | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-   | `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.                                                                  |
+   If the goal is only to fix package compatibility while keeping application context for first-party code, `dependencyLoader: native` is a narrower option — it uses native loading only for npm packages while keeping the VM loader for application source files.
 
-   **`lockdown` options:**
+10. **Handle intrinsic `lockdown`**: The default `lockdown` mode (`freeze-after-load`) freezes JavaScript intrinsics (`Object`, `Array`, `Promise`, `Map`, `Set`, etc.) after all application code loads. Any code or dependency that modifies intrinsic prototypes at runtime will throw a `TypeError`. If a dependency requires a temporary workaround, set:
 
-   | 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:
+      lockdown: none
+    ```
 
-   To disable the VM loader entirely and restore pre-v5 behavior:
+11. **Check `allowedDirectory` in production**: In production, applications can only load modules from within their own directory tree (`allowedDirectory: app`). If your application loads files from outside its directory, set:
 
-   ```yaml
-   applications:
-     moduleLoader: native
-   ```
+    ```yaml
+    applications:
+      allowedDirectory: any
+    ```
 
 ## Examples
 
-**Full transaction polling pattern (v5):**
+### Full `harper-config.yaml` module loading block
+
+```yaml
+applications:
+  lockdown: freeze-after-load
+  moduleLoader: vm-current-context
+  dependencyLoader: auto
+  allowedDirectory: app
+  allowedSpawnCommands:
+    - npm
+    - node
+```
+
+### Updated import and context access
 
 ```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);
-	}
-}
+import { tables, getContext, transaction } from 'harper';
 ```
 
-**Checking `loadedFromSource` after `Table.get`:**
+### Checking `loadedFromSource` after `Table.get`
 
 ```javascript
 const target = new RequestTarget();
@@ -155,37 +168,17 @@ if (target.loadedFromSource) {
 }
 ```
 
-**Full `harperdb-config.yaml` `applications` block:**
-
-```yaml
-applications:
-  lockdown: freeze-after-load
-  moduleLoader: vm-current-context
-  dependencyLoader: auto
-  allowedDirectory: app
-  allowedSpawnCommands:
-    - npm
-    - node
-```
-
-**Restricting allowed built-in modules:**
+### Copying a frozen record before mutation
 
-```yaml
-applications:
-  allowedBuiltinModules:
-    - fs
-    - path
-    - http
+```javascript
+let record = await Table.get(id);
+record = { ...record, property: 'changed' };
 ```
 
 ## Notes
 
-- 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.
+- The `logger` exported from `'harper'` is tagged with the application name when using the VM module loader. It is not available in `native` mode.
+- `instanceof` checks for values crossing the application/Harper boundary will fail when using `moduleLoader: vm` (separate intrinsics). Use `vm-current-context` (the default) to avoid this.
+- `import()` behavior depends on the `moduleLoader` setting. In `native` mode, standard Node.js `import()` is used with no application context.
+- Automatic context tracking simplifies code but requires explicit `commit()` or new `transaction()` calls when you need to observe data written within the same transaction.
+- Use `getContext` from `'harper'` rather than passing context manually through every call — this is the recommended pattern in v5.