@harperfast/template-vue-ts-studio 1.10.0 → 1.10.2

package/.agents/skills/harper-best-practices/rules/custom-resources.md

@@ -7,8 +7,8 @@ metadata:
     - reference/v5/resources/overview.md#Custom External Data Source
     - reference/v5/resources/overview.md#Exporting Resources as Endpoints
     - reference/v5/components/javascript-environment.md#Module Loading
-  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
-  inputHash: 9b911fd8e036b808
+  sourceCommit: f37a8c4021e20d5c74c1d339a6b6c8c196b5603e
+  inputHash: df69870433c0b3e5
 ---
 
 # Custom Resources
@@ -17,17 +17,17 @@ 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 programmatic routes in a Harper application. Use it any time business logic needs to live outside a standard table-backed resource.
+Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when a specific URL shape is required.
 
 ## How It Works
 
-1. **Import `Resource` from the `harper` package**: Always import explicitly rather than relying on globals.
+1. **Import `Resource` from `harper`**: Always import from the `harper` package rather than relying on globals.
 
    ```javascript
    import { tables, Resource } from 'harper';
    ```
 
-2. **Define a class that `extends Resource`**: Use `export class` so Harper can expose it as an endpoint. Implement HTTP methods as `static` methods on the class.
+2. **Define a class that `extends Resource`**: Implement HTTP methods as `static` methods. Each method receives a `target` object.
 
    ```javascript
    export class CustomEndpoint extends Resource {
@@ -39,7 +39,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-3. **Add async `static` methods for each HTTP verb you need**: Methods receive `target` (contains `target.id`, etc.) and, for write operations, `data`.
+3. **Use `async` static methods for external calls**: Await fetch or other async operations inside `static` handlers.
 
    ```javascript
    export class MyExternalData extends Resource {
@@ -57,29 +57,46 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-4. **Control the URL by choosing the export form**: The shape of the export determines the resulting URL path. Path matching is case-sensitive.
+4. **Export the class to create an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
 
-   | Export form                              | URL             | Notes                                                           |
-   | ---------------------------------------- | --------------- | --------------------------------------------------------------- |
-   | `export class Foo extends Resource {}`   | `/Foo/`         | Class name becomes the path segment.                            |
-   | `export const Bar = { Foo };`            | `/Bar/Foo/`     | Nest under an object to add a path prefix.                      |
-   | `export const bar = { 'foo-baz': Foo };` | `/bar/foo-baz/` | Use object keys for lowercase, hyphens, or non-identifier URLs. |
-   | `server.resources.set('my-path', Foo);`  | `/my-path/`     | Programmatic registration; useful when the path is dynamic.     |
+   | Export form                                 | URL             | Notes                                                           |
+   | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
+   | `export class Foo extends Resource {}`      | `/Foo/`         | Class name becomes the path segment. Case-sensitive.            |
+   | `export const Bar = { Foo };`               | `/Bar/Foo/`     | Nest under an object to add a path prefix.                      |
+   | `export const bar = { 'foo-baz': Foo };`    | `/bar/foo-baz/` | Use object keys for lowercase, hyphens, or non-identifier URLs. |
+   | `export { Foo as '/widget/:id' }`           | `/widget/:id`   | Rename the export to set the path directly.                     |
+   | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
+   | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
 
-5. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the class.
+   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+
+5. **Declare path parameters with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+
+   ```javascript
+   export class Widget extends Resource {
+   	static path = '/widget/:id/action/:action';
+   	static get(target) {
+   		return { id: target.id, action: target.action };
+   	}
+   }
+   ```
+
+   A `static path` takes precedence over the export name. A leading `/` makes the path root-relative (top-level). A leading `./` or bare name resolves relative to the component directory.
+
+6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` when the path cannot be known at export time.
 
    ```javascript
    server.resources.set('my-path', Foo);
    ```
 
-6. **Optionally use the resource as a cache source for a local table**: Pass the class to `sourcedFrom`.
+7. **Optionally source a table from a custom resource**: Use the resource as a caching layer for a local table.
    ```javascript
    tables.MyCache.sourcedFrom(MyExternalData);
    ```
 
 ## Examples
 
-Wrap an external API and expose it as an endpoint, then back a local cache table with it:
+### External API wrapper with GET and PUT
 
 ```javascript
 import { tables, Resource } from 'harper';
@@ -102,26 +119,47 @@ export class MyExternalData extends Resource {
 tables.MyCache.sourcedFrom(MyExternalData);
 ```
 
-Programmatic registration with a custom path:
+### Path parameters with `static path`
+
+```javascript
+import { Resource } from 'harper';
+
+export class Widget extends Resource {
+	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
+	static path = '/widget/:id/action/:action';
+	static get(target) {
+		return { id: target.id, action: target.action };
+	}
+}
+
+export class Files extends Resource {
+	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
+	static path = '/files/*rest';
+	static get(target) {
+		return { path: target.rest };
+	}
+}
+```
+
+### Programmatic registration
 
 ```javascript
 import { Resource } from 'harper';
 
-export class CustomEndpoint extends Resource {
+export class Foo extends Resource {
 	static get(target) {
-		return {
-			data: doSomething(),
-		};
+		return { data: doSomething() };
 	}
 }
 
-server.resources.set('my-path', CustomEndpoint);
+server.resources.set('my-path', Foo);
 ```
 
 ## Notes
 
-- `export class` directly produces a URL from the class name (e.g., `export class Foo extends Resource {}` → `/Foo/`). Do not export the same resource from both a schema file and a JavaScript file — this creates conflicting exports.
-- URL path segments are case-sensitive: `/Foo/` and `/foo/` are different endpoints.
-- For CommonJS modules, use `const { tables, Resource } = require('harper');` instead of the ESM import.
-- When developing a component in its own directory, run `npm link harper` to ensure typings match your installed version. All installed components have `harper` automatically linked.
-- The `static` keyword is required on all HTTP verb methods — Harper dispatches requests through static class methods, not instance methods.
+- A bare `*` wildcard (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
+- Resolution order: exact/static paths always win over parameterized ones. Among parameterized routes, more specific paths win — a literal segment beats `:param`, which beats `*`, compared left to right.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
+- If a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
+- Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
+- Harper runs as a single process — `tables`, `databases`, and other APIs are the same live, process-wide objects regardless of which component accesses them.

package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md

@@ -2,177 +2,185 @@
 name: programmatic-table-requests
 description: How to interact with Harper tables programmatically using the `tables` object.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/database/api.md#`tables`
+    - reference/v5/resources/resource-api.md#Query Object
+    - 'reference/v5/database/api.md#`transaction(context?, callback)`'
+    - >-
+      reference/v5/resources/resource-api.md#`update(target: RequestTarget | Id,
+      updates?: object): Promise<Resource>`
+    - >-
+      reference/v5/resources/resource-api.md#`addTo(property: string, value:
+      number)`
+    - reference/v5/components/javascript-environment.md#Module Loading
+  sourceCommit: be709f9978319dcdb669c05d794effc82bcda8b7
+  inputHash: 3d2417fbff687c42
 ---
 
 # Programmatic Table Requests
 
-Instructions for the agent to follow when interacting with Harper tables via code.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object and its query API.
 
 ## When to Use
 
-Use this skill when you need to perform database operations (CRUD, search, subscribe) from within Harper Resources or scripts.
+Apply this rule when writing server-side Harper code that reads from or writes to tables directly — for example, in request handlers, background jobs, or SSR entry points — instead of going through the REST API. Use it whenever you need to construct queries with `conditions`, paginate results, select specific fields, or perform CRDT-safe mutations with `addTo`.
 
 ## How It Works
 
-1. **Access the Table**: Use the global `tables` object followed by your table name (e.g., `tables.MyTable`).
-2. **Perform CRUD Operations**:
-   - **Get**: `await tables.MyTable.get(id)` for a single record or `await tables.MyTable.get({ conditions: [...] })` for multiple.
-   - **Create**: `await tables.MyTable.post(record)` (auto-generates ID) or `await tables.MyTable.put(id, record)`.
-   - **Update**: `await tables.MyTable.patch(id, partialRecord)` for partial updates.
-   - **Delete**: `await tables.MyTable.delete(id)`.
-3. **Use Updatable Records for Atomic Ops**: Call `update(id)` to get a reference, then use `addTo` or `subtractFrom` for atomic increments/decrements:
-   ```typescript
-   const stats = await tables.Stats.update('daily');
-   stats.addTo('viewCount', 1);
-   ```
-4. **Search and Stream**: Use `search(query)` for efficient streaming of large result sets:
-   ```typescript
-   for await (const record of tables.MyTable.search({ conditions: [...] })) {
-     // process record
-   }
-   ```
-   See the [Query Conditions](#query-conditions) section below for the full query object reference.
-5. **Real-time Subscriptions**: Use `subscribe(query)` to listen for changes:
-   ```typescript
-   for await (const event of tables.MyTable.subscribe(query)) {
-   	// handle event
-   }
-   ```
-6. **Publish Events**: Use `publish(id, message)` to trigger subscriptions without necessarily persisting data.
-
-## Query Conditions
-
-When passing a query to `search()`, `get()`, or `subscribe()`, use a query object with a `conditions` array.
-
-### Condition Object Shape
+1. **Import `tables`**: Import from the `harper` package. Each table defined in `schema.graphql` with `@table` is available as a named property.
 
-| Property     | Description                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------ |
-| `attribute`  | Field name, or array of field names to traverse a relationship (e.g., `['brand', 'name']`) |
-| `value`      | The value to compare against                                                               |
-| `comparator` | One of the comparator strings below (default: `equals`)                                    |
-| `operator`   | `and` (default) or `or` — applies to a nested `conditions` block                           |
-| `conditions` | Nested array of condition objects for complex AND/OR logic                                 |
-
-### Comparator Values
+   ```javascript
+   import { tables } from 'harper';
+   const { Product } = tables;
+   // same as: databases.data.Product
+   ```
 
-Use these exact strings — incorrect comparator names will silently fail or error:
+2. **Define your schema**: Declare tables in `schema.graphql` using `@table` and `@primaryKey`.
 
-| Comparator           | Meaning                                                    |
-| -------------------- | ---------------------------------------------------------- |
-| `equals`             | Exact match (default)                                      |
-| `not_equal`          | Not equal                                                  |
-| `greater_than`       | `>`                                                        |
-| `greater_than_equal` | `>=`                                                       |
-| `less_than`          | `<`                                                        |
-| `less_than_equal`    | `<=`                                                       |
-| `starts_with`        | String starts with value                                   |
-| `contains`           | String contains value                                      |
-| `ends_with`          | String ends with value                                     |
-| `between`            | Value is between two bounds (pass `value` as `[min, max]`) |
+   ```graphql
+   # schema.graphql
+   type Product @table {
+   	id: Long @primaryKey
+   	name: String
+   	price: Float
+   }
+   ```
 
-### Query Object Parameters
+3. **Create and mutate records**: Use `create`, `patch`, `get`, and `update` on the table class.
 
-| Property     | Description                                                                                                                                                                                                     |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `conditions` | Array of condition objects                                                                                                                                                                                      |
-| `limit`      | Maximum number of records to return                                                                                                                                                                             |
-| `offset`     | Number of records to skip (for pagination)                                                                                                                                                                      |
-| `select`     | Array of fields to return: attribute names (supports `$id` and `$updatedtime`), or an object `{ name, select }` to include fields from a related record — see [Selecting Related Data](#selecting-related-data) |
-| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort                                                                                                                            |
+   ```javascript
+   // Create a new record (id auto-generated)
+   const created = await Product.create({ name: 'Shirt', price: 9.5 });
 
-### Examples
+   // Modify the record
+   await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
 
-**Simple filter:**
+   // Retrieve by primary key
+   const record = await Product.get(created.id);
+   ```
 
-```javascript
-for await (const record of tables.Product.search({
-  conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
-  limit: 20,
-})) { ... }
-```
+4. **Query with `search(` and `conditions`**: Pass a query object to `search()` to filter records. Iterate the async result.
 
-**AND + nested OR:**
+   ```javascript
+   const query = {
+   	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
+   };
+   for await (const record of Product.search(query)) {
+   	// ...
+   }
+   ```
 
-```javascript
-for await (const record of tables.Product.search({
-  conditions: [
-    { attribute: 'price', comparator: 'less_than', value: 100 },
-    {
-      operator: 'or',
-      conditions: [
-        { attribute: 'rating', comparator: 'greater_than', value: 4 },
-        { attribute: 'featured', value: true },
-      ],
-    },
-  ],
-})) { ... }
-```
+5. **Use `select` to shape results**: Pass a `select` array to return only specific properties, including nested relationship fields.
 
-**Relationship traversal:**
+   ```javascript
+   const book = await Book.get({ id: 42, select: ['id', 'title', 'author'] });
+   book.author.name; // full related Author record
 
-```javascript
-for await (const record of tables.Book.search({
-  conditions: [{ attribute: ['brand', 'name'], comparator: 'equals', value: 'Harper' }],
-})) { ... }
-```
+   // Partial related record
+   const book = await Book.get({
+   	id: 42,
+   	select: ['id', 'title', { name: 'author', select: ['name'] }],
+   });
+   ```
 
-**Sort and paginate:**
+6. **Use `addTo` for concurrent-safe increments**: Call `addTo` on a mutable resource instance obtained via `update()`. This uses CRDT incrementation, safe across threads and nodes.
 
-```javascript
-for await (const record of tables.Product.search({
-  conditions: [{ attribute: 'inStock', value: true }],
-  sort: { attribute: 'price', descending: false },
-  limit: 10,
-  offset: 20,
-})) { ... }
-```
+   ```javascript
+   static async post(target, data) {
+     const record = await this.update(target.id);
+     record.addTo('quantity', -1); // decrement safely across nodes
+   }
+   ```
 
-## Selecting Related Data
+7. **Scope destructive operations carefully**: `update`, `patch`, and `delete` operate directly on stored data. Always use specific `conditions`, validate the affected set before writing, and gate behind authorization controls.
 
-When a field is defined as a relationship (via `@relationship` — see [Defining Relationships](defining-relationships.md)), `select` can pull the related record(s) into your results as nested properties. This is the programmatic equivalent of the REST `select(name,author{name})` syntax (see [Querying REST APIs](querying-rest-apis.md)).
+## Examples
 
-**Whole related record** — list the relationship field by name. The related record (or an array of records for a to-many relationship) is attached as a nested property:
+### Nested conditions query
 
 ```javascript
-for await (const book of tables.Book.search({
-	conditions: [{ attribute: 'id', value: 42 }],
-	select: ['id', 'title', 'author'], // `author` is a relationship field
-})) {
-	console.log(book.author.name); // the full related Author record
-}
+Product.search({
+	conditions: [
+		{ attribute: 'price', comparator: 'less_than', value: 100 },
+		{
+			operator: 'or',
+			conditions: [
+				{ attribute: 'rating', comparator: 'greater_than', value: 4 },
+				{ attribute: 'featured', value: true },
+			],
+		},
+	],
+});
 ```
 
-**Partial related record** — use an object `{ name, select }` to choose which fields of the related record to return. Unselected fields are omitted:
+### Chained attribute reference (relationship join)
 
 ```javascript
-for await (const book of tables.Book.search({
-	conditions: [{ attribute: ['author', 'name'], comparator: 'equals', value: 'Harper' }],
-	select: ['id', 'title', { name: 'author', select: ['name'] }],
-})) {
-	// book.author.name is present; other Author fields are undefined
-}
+Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-**Nesting** — a `select` inside an object entry may itself contain more `{ name, select }` objects, traversing multiple relationships in one query:
+### Deep nested `select`
 
 ```javascript
 select: [
-  'id',
-  'name',
-  {
-    name: 'segments',
-    select: ['id', 'name', { name: 'client', select: ['id', 'name'] }],
-  },
-],
+	'id',
+	'name',
+	{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
+];
 ```
 
-Notes:
+### SSR usage
 
-- A to-many relationship resolves to an array of records; depending on access pattern you may need to `await` the property before iterating it.
-- Selecting a relationship without filtering on it produces LEFT JOIN behavior (records with no related row are still returned); adding a condition on a related attribute (e.g. `attribute: ['author', 'name']`) produces INNER JOIN behavior.
+```typescript
+import { tables } from 'harper';
 
-## Cautions
+export async function render(url: string): Promise<string> {
+	const product = await tables.Product.get(idFromUrl(url));
+	return renderToString(/* <App product={product} /> */);
+}
+```
 
-Be very careful when performing updates and deletions! You may be dealing with live production data. The wrong request to delete, without approval from a human, could be devastating to a business. Always use the proper approval process.
+## Notes
+
+### `conditions` comparator values
+
+| Comparator           | Description            |
+| -------------------- | ---------------------- |
+| `equals`             | Default equality match |
+| `greater_than`       | Strictly greater       |
+| `greater_than_equal` | Greater than or equal  |
+| `less_than`          | Strictly less          |
+| `less_than_equal`    | Less than or equal     |
+| `starts_with`        | String prefix match    |
+| `contains`           | String contains        |
+| `ends_with`          | String suffix match    |
+| `between`            | Range match            |
+| `not_equal`          | Inequality match       |
+
+### Query object options
+
+| Property                | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `conditions`            | Array of condition objects to filter records                            |
+| `operator`              | Top-level `and` (default) or `or` for the `conditions` array            |
+| `limit`                 | Maximum number of records to return                                     |
+| `offset`                | Number of records to skip (for pagination)                              |
+| `select`                | Properties to include in each returned record                           |
+| `sort`                  | Sort order object with `attribute`, `descending`, and `next` properties |
+| `explain`               | If `true`, returns conditions reordered as Harper will execute them     |
+| `enforceExecutionOrder` | If `true`, forces conditions to execute in the order supplied           |
+
+### `select` special properties
+
+- `$id` — Returns the primary key regardless of its name
+- `$updatedtime` — Returns the last-updated timestamp
+- `$distance` — Returns the computed distance from the target vector when the query uses a vector index
+
+### Relationship join behavior
+
+- Selecting a relationship **without** filtering on it behaves as a **LEFT JOIN** — records with no related row are still returned.
+- Adding a `conditions` entry on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN** — only records with a matching related row are returned.
+
+- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime instead of being bundled.
+- `tables`, `databases`, and other Harper APIs are the same live, process-wide objects regardless of whether accessed as globals or via `import { tables } from 'harper'`.

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

@@ -68,6 +68,34 @@ static:
 - Install dependencies: `npm install --save-dev vite @harperfast/vite @vitejs/plugin-react` (swap in your framework's Vite plugin, e.g. `@vitejs/plugin-vue`).
 - Then `harper dev .` runs the app with HMR and `harper run .` runs the production build. Vite does _not_ need to be executed separately.
 
+## Reading Harper Data During SSR
+
+The render entry (`src/entry-server.tsx`) runs **inside Harper**, so it can read straight from the database and render the data into the HTML — no client-side fetch/XHR. `tables` is the same live, process-wide registry available everywhere (see [Programmatic Table Requests](programmatic-table-requests.md)); import it and query a table in an async `render`:
+
+```tsx
+import { tables } from 'harper';
+
+export async function render(url: string): Promise<string> {
+	const product = await tables.Product.get(idFromUrl(url));
+	return renderToString(
+		<StrictMode>
+			<App product={product} />
+		</StrictMode>,
+	);
+}
+```
+
+Keep `harper` external in `vite.config.ts` so this import resolves to Harper's running runtime instead of being bundled. `node_modules/harper` is symlinked to the running install, and symlinked deps aren't reliably auto-externalized for SSR:
+
+```typescript
+export default defineConfig({
+	ssr: { external: ['harper'] },
+	// ...plugins, resolve, build
+});
+```
+
+To hydrate on the client without re-fetching, embed the rendered data in the HTML (e.g. an inline `<script type="application/json">`) and read it back before hydration — so the page needs no XHR at all.
+
 ## Deploying to Production
 
 Because `@harperfast/vite` builds on the node and `static` serves the output, deploy the component as-is — no manual build-and-move step is needed:

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

@@ -8,21 +8,21 @@ metadata:
     - reference/v5/database/api.md#Streaming
     - reference/v5/database/api.md#`BlobOptions`
     - reference/v5/database/api.md#Blob Coercion
-  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
-  inputHash: 71a3e738ebf87fa4
+  sourceCommit: f37a8c4021e20d5c74c1d339a6b6c8c196b5603e
+  inputHash: 92e03eb0b830f335
 ---
 
 # Using the Blob Data Type
 
-Instructions for the agent to follow when storing and retrieving large binary content using Harper's `Blob` data type.
+Instructions for the agent to follow when storing and retrieving large binary content using the `Blob` data type in Harper.
 
 ## 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 you need streaming support or want to avoid loading the entire value into memory. 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.md](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 a `@table` type.
+1. **Declare a `Blob` field in your schema**: Add a field typed as `Blob` to your `@table` type.
 
    ```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 a blob with `createBlob()`**: Pass a buffer, string, or stream as the first argument. Pass a `BlobOptions` object as the second argument to configure behavior.
+2. **Create and store a blob with `createBlob()`**: Pass a buffer or stream to `createBlob()`, then `put` the record.
 
    ```javascript
    let blob = createBlob(largeBuffer);
    await MyTable.put({ id: 'my-record', data: blob });
    ```
 
-3. **Read blob data using standard Web API methods**: The `Blob` type implements the Web API `Blob` interface. Use `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, or `.slice()` to access content.
+3. **Retrieve blob data using standard Web API methods**: The `Blob` type implements the Web API `Blob` interface. Use `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, or `.slice()` as needed.
 
    ```javascript
    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` for ACID-compliant writes**: By default, blobs are not ACID-compliant — a record can reference a blob before it is fully written. Set `saveBeforeCommit: true` to wait for the full write before the transaction commits.
+4. **Use `saveBeforeCommit` when full write must precede commit**: By default, `Blob` is not ACID-compliant — a record can reference a blob before it is fully written. Set `saveBeforeCommit: true` to block the transaction until the blob is fully saved.
 
    ```javascript
    let blob = createBlob(stream, { saveBeforeCommit: true });
@@ -55,7 +55,7 @@ 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 to avoid stale records.
+5. **Register an error handler when returning a blob via REST**: Interrupted streams must be handled explicitly.
 
    ```javascript
    export class MyEndpoint extends MyTable {
@@ -70,15 +70,17 @@ 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`. Manual `createBlob()` calls are not required for plain JSON HTTP bodies or MQTT messages in most cases.
+6. **Rely on automatic coercion where applicable**: When a field is typed as `Blob` in the schema, any string or buffer assigned via `put`, `patch`, or `publish` is automatically coerced to a `Blob` — no manual `createBlob()` call is needed in those cases.
 
-### `BlobOptions` Reference
+### `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 for the blob to be fully written before committing the transaction.                                                 |
+| `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.                                    |
 
@@ -91,7 +93,7 @@ let blob = createBlob(imageBuffer, { type: 'image/jpeg' });
 await Photo.put({ id, data: blob });
 ```
 
-**Stream large media with low latency:**
+**Stream a blob in as it streams out (low-latency passthrough):**
 
 ```javascript
 let blob = createBlob(incomingStream);
@@ -103,7 +105,7 @@ let record = await MyTable.get('my-record');
 let outgoingStream = record.data.stream();
 ```
 
-**Guaranteed write before commit:**
+**Guarantee full write before commit using `saveBeforeCommit`:**
 
 ```javascript
 let blob = createBlob(stream, { saveBeforeCommit: true });
@@ -112,7 +114,6 @@ await MyTable.put({ id: 'my-record', data: blob });
 
 ## Notes
 
-- `Blob` stores data separately from the record; `Bytes` does not. Prefer `Blob` for content larger than 20KB.
-- All standard Web API `Blob` methods are available: `.bytes()`, `.text()`, `.arrayBuffer()`, `.stream()`, `.slice()`.
-- Blobs are **not** ACID-compliant by default when created from a stream. Use `saveBeforeCommit: true` to enforce transactional consistency.
-- Always attach an `error` handler on blobs returned as HTTP response bodies to handle interrupted streams.
+- `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.