@harperfast/template-vue-ts-studio 1.9.2 → 1.10.1

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

@@ -9,11 +9,11 @@ metadata:
     - reference/v5/database/schema.md#Overview
     - reference/v5/database/schema.md#Type Directives
     - reference/v5/database/schema.md#Field Directives
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 4faa3baed7cfa854
+  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
+  inputHash: 15b9c72decc1f05d
 ---
 
-# Schema Design and Tooling
+# Schema Design and GraphQL Tooling
 
 Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
@@ -23,7 +23,18 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
 
 ## How It Works
 
-1. **Create a GraphQL schema file** with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
+1. **Create a schema file** using standard GraphQL type definitions with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
+
+2. **Register the schema** in the component's `config.yaml` using the `graphqlSchema` plugin:
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   ```
+
+   Both plugins and applications can specify schemas.
+
+3. **Mark types as tables** with `@table`. The type name becomes the table name by default:
 
    ```graphql
    type Dog @table {
@@ -32,23 +43,36 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    	breed: String
    	age: Int
    }
+   ```
 
+4. **Designate a primary key** with `@primaryKey` on exactly one field per type. Primary keys must be unique; duplicate-key inserts are rejected. If no primary key is provided on insert, Harper auto-generates one:
+   - `String` or `ID` → UUID string
+   - `Int`, `Long`, or `Any` → auto-incrementing integer
+
+   Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
+
+5. **Add secondary indexes** with `@indexed` on any field that will be used for filtering in REST queries, SQL, or NoSQL operations:
+
+   ```graphql
    type Breed @table {
    	id: Long @primaryKey
    	name: String @indexed
    }
    ```
 
-2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin key:
+   If the field value is an array, each element is individually indexed. Null values are indexed by default.
 
-   ```yaml
-   graphqlSchema:
-     files: 'schema.graphql'
+6. **Expose a table as an external endpoint** with `@export`. The optional `name` parameter sets the URL path segment:
+
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
    ```
 
-   Both plugins and applications can specify schemas this way.
+   Without `name`, the type name is used as the path segment.
 
-3. **Mark every table type with `@table`**. The type name becomes the table name by default. Use optional arguments to override behavior:
+7. **Configure `@table` arguments** as needed for database placement, expiration, eviction, and replication:
 
    | Argument       | Type      | Default                       | Description                                                   |
    | -------------- | --------- | ----------------------------- | ------------------------------------------------------------- |
@@ -59,32 +83,13 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    | `scanInterval` | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                |
    | `replicate`    | `Boolean` | `true`                        | Enable replication of this table                              |
 
-4. **Designate a primary key on every table** using `@primaryKey`. Primary keys must be unique; duplicate-key inserts are rejected. If no key is provided on insert, Harper auto-generates one:
-   - `String` or `ID` → UUID string
-   - `Int`, `Long`, or `Any` → auto-incrementing integer
-
-   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
-
-5. **Index fields that need fast querying** with `@indexed`. This is required for filtering by that attribute in REST queries, SQL, or NoSQL operations. If the field value is an array, each element is individually indexed.
-
-   ```graphql
-   type Product @table {
-   	id: Long @primaryKey
-   	category: String @indexed
-   	price: Float @indexed
-   }
-   ```
-
-6. **Expose a table as an external resource endpoint** with `@export`. This makes the table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment; without it, the type name is used.
-
-   ```graphql
-   type MyTable @table @export(name: "my-table") {
-   	id: Long @primaryKey
-   }
-   ```
-
-7. **Restrict extra properties** with `@sealed` when records must not include attributes beyond those declared. By default, Harper allows additional properties.
+8. **Apply additional field directives** where needed:
+   - `@createdTime` — auto-assigns Unix epoch milliseconds on record creation
+   - `@updatedTime` — auto-assigns Unix epoch milliseconds on each update
+   - `@embed(source: "fieldName", model: "modelName")` — computes an embedding vector on write; attribute type must be `[Float]`
+   - `@hidden` — suppresses the field from MCP tool descriptors and OpenAPI documents (not an access-control mechanism)
 
+9. **Restrict extra properties** with `@sealed` if records must not include properties beyond those declared:
    ```graphql
    type StrictRecord @table @sealed {
    	id: Long @primaryKey
@@ -92,70 +97,88 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
    }
    ```
 
-8. **Configure expiration, eviction, and scan behavior** together when building caching tables. These three arguments control the full record lifecycle:
-   - `expiration` — record becomes stale; next request triggers a source fetch
-   - `eviction` — additional time after `expiration` before physical removal
-   - `scanInterval` — how often Harper scans for records to evict; clock-aligned, not startup-aligned
-
 ## Examples
 
-**Caching table with tuned expiration:**
+**Minimal two-table schema:**
 
 ```graphql
-# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
-type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
-	id: ID @primaryKey
-	temperature: Float
+type Dog @table {
+	id: Long @primaryKey
+	name: String
+	breed: String
+	age: Int
 }
-```
-
-**Table in a named database with expiration and an indexed field:**
 
-```graphql
-type Event @table(database: "analytics", expiration: 86400) {
+type Breed @table {
 	id: Long @primaryKey
 	name: String @indexed
 }
 ```
 
-**Session cache with auto-expiry:**
+**Table with expiration, eviction, and custom scan interval:**
 
 ```graphql
-type Session @table(expiration: 3600) {
-	id: Long @primaryKey
-	userId: String
+# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
+type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
+	id: ID @primaryKey
+	temperature: Float
 }
 ```
 
-**Table with audit timestamps:**
+**Exported table with timestamps and a hidden field:**
 
 ```graphql
-type Order @table @export(name: "orders") {
+type Customer @table @export(name: "customers") {
 	id: Long @primaryKey
+	name: String @indexed
 	createdAt: Long @createdTime
 	updatedAt: Long @updatedTime
-	status: String @indexed
+
+	"""
+	Internal — do not surface to external consumers.
+	"""
+	creditScore: Int @hidden
 }
 ```
 
-**Overriding the table name and disabling replication:**
+**Multiple `@table` argument combinations:**
 
 ```graphql
+# Override table name
 type Product @table(table: "products") {
 	id: Long @primaryKey
-	name: String
 }
 
+# Place in a specific database
+type Order @table(database: "commerce") {
+	id: Long @primaryKey
+}
+
+# Auto-expire records after 1 hour
+type Session @table(expiration: 3600) {
+	id: Long @primaryKey
+	userId: String
+}
+
+# Disable replication
 type LocalRecord @table(replicate: false) {
 	id: Long @primaryKey
 	value: String
 }
+
+# Combine multiple arguments
+type Event @table(database: "analytics", expiration: 86400) {
+	id: Long @primaryKey
+	name: String @indexed
+}
 ```
 
 ## Notes
 
-- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
-- 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 from the source on demand when a query matches an evicted record.
-- `scanInterval` is clock-aligned to the server's local timezone. The server's startup time does not affect when eviction runs.
-- If replication is disabled on a table and later re-enabled, it will not catch up on writes made while replication was disabled.
-- Null values are indexed by `@indexed` fields, enabling queries such as `GET /Product/?category=null`.
+- All tables default to the `"data"` database. When designing plugins or applications, use unique database names to avoid table naming collisions.
+- Schemas are flexible by default — records may include properties beyond those declared. Use `@sealed` to prevent this.
+- `expiration` marks a record stale; `eviction` controls how long after expiration the record is physically removed. Eviction does not remove records from secondary indexes — Harper fetches the full record on demand if an evicted record matches a query.
+- `scanInterval` is clock-aligned to the server's local timezone, not startup-aligned. The eviction schedule is deterministic across restarts.
+- If replication is disabled on a table and later re-enabled, writes made during the disabled period are not replicated retroactively.
+- `@hidden` (on types or fields) is a metadata-visibility directive only. Use `attribute_permissions` on roles to enforce data access control.
+- Disabling replication (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.

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

@@ -2,37 +2,118 @@
 name: using-blob-datatype
 description: How to use the Blob data type for efficient binary storage in Harper.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/database/schema.md#Blob Type
+    - reference/v5/database/api.md#Streaming
+    - reference/v5/database/api.md#`BlobOptions`
+    - reference/v5/database/api.md#Blob Coercion
+  sourceCommit: f37a8c4021e20d5c74c1d339a6b6c8c196b5603e
+  inputHash: 92e03eb0b830f335
 ---
 
-# Using Blob Datatype
+# Using the Blob Data Type
 
-Instructions for the agent to follow when working with the Blob data type in Harper.
+Instructions for the agent to follow when storing and retrieving large binary content using the `Blob` data type in Harper.
 
 ## When to Use
 
-Use this skill when you need to store unstructured or large binary data (media, documents) that is too large for standard JSON fields. Blobs provide efficient storage and integrated streaming support.
+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. **Define Blob Fields**: In your GraphQL schema, use the `Blob` type:
+1. **Declare a `Blob` field in your schema**: Add a field typed as `Blob` to your `@table` type.
+
    ```graphql
    type MyTable @table {
-   	id: ID @primaryKey
+   	id: Any! @primaryKey
    	data: Blob
    }
    ```
-2. **Create and Store Blobs**: Use `createBlob()` from Harper's globals to wrap Buffers or Streams:
+
+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. **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');
+   let buffer = await record.data.bytes(); // ArrayBuffer
+   let text = await record.data.text(); // string
+   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.
+
    ```javascript
-   import { tables } from 'harper';
-   const blob = createBlob(largeBuffer);
-   await tables.MyTable.put('my-id', { data: blob });
+   let blob = createBlob(stream, { saveBeforeCommit: true });
+   await MyTable.put({ id: 'my-record', data: blob });
+   // put() resolves only after blob is fully written and record is committed
    ```
-3. **Use Streaming (Optional)**: For very large files, pass a stream to `createBlob()` to avoid loading the entire file into memory.
-4. **Read Blob Data**: Retrieve the record and use `.bytes()` or streaming interfaces on the blob field:
+
+5. **Register an error handler when returning a blob via REST**: Interrupted streams must be handled explicitly.
+
    ```javascript
-   const record = await tables.MyTable.get('my-id');
-   const buffer = await record.data.bytes();
+   export class MyEndpoint extends MyTable {
+   	static async get(target) {
+   		const record = super.get(target);
+   		let blob = record.data;
+   		blob.on('error', () => {
+   			MyTable.invalidate(target);
+   		});
+   		return { status: 200, headers: {}, body: blob };
+   	}
+   }
    ```
-5. **Ensure Write Completion**: Use `saveBeforeCommit: true` in `createBlob` options if you need the blob fully written before the record is committed.
-6. **Handle Errors**: Attach error listeners to the blob object to handle streaming failures.
+
+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
+
+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.                                    |
+
+## Examples
+
+**Store an image with a MIME type:**
+
+```javascript
+let blob = createBlob(imageBuffer, { type: 'image/jpeg' });
+await Photo.put({ id, data: blob });
+```
+
+**Stream a blob in as it streams out (low-latency passthrough):**
+
+```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`:**
+
+```javascript
+let blob = createBlob(stream, { saveBeforeCommit: true });
+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.

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

@@ -5,21 +5,21 @@ metadata:
   mode: generate
   sources:
     - reference/v5/database/schema.md#Vector Indexing
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 3732961c671aac00
+  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
+  inputHash: d90b1b74597d08a6
 ---
 
 # Vector Indexing
 
-Instructions for the agent to follow when enabling and querying vector indexes for similarity search in Harper using the HNSW algorithm.
+Instructions for the agent to enable HNSW vector indexes on table fields and query them for similarity search in Harper.
 
 ## When to Use
 
-Apply this rule when adding a vector index to a Harper table schema or writing similarity search queries against high-dimensional vector fields. Use it whenever you need approximate nearest-neighbor search, distance-threshold filtering, or distance-scored results.
+Apply this rule when adding a vector similarity search capability to a Harper table — for example, storing text embeddings and querying for nearest neighbors, filtering by distance threshold, or tuning index construction and search parameters. Use it alongside [adding-tables-with-schemas.md](adding-tables-with-schemas.md) when defining the schema that hosts the vector field.
 
 ## How It Works
 
-1. **Declare the vector index on a `[Float]` field**: Add `@indexed(type: "HNSW")` to any `[Float]` attribute in a `@table` type. See [adding-tables-with-schemas.md](adding-tables-with-schemas.md) for general schema setup.
+1. **Declare the vector index on a field**: Add `@indexed(type: "HNSW")` to a `[Float]` field inside a `@table` type. This creates an HNSW (Hierarchical Navigable Small World) index for approximate nearest-neighbor search.
 
    ```graphql
    type Document @table {
@@ -28,7 +28,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    }
    ```
 
-2. **Query by nearest neighbors using `sort`**: Call `Document.search()` with a `sort` object containing `attribute` (the indexed field name) and `target` (the query vector). Include `limit` to cap results.
+2. **Query by nearest neighbors using `sort`**: Call `.search()` with a `sort` descriptor that specifies the indexed `attribute` and a `target` vector. Use `limit` to cap results.
 
    ```javascript
    let results = Document.search({
@@ -47,7 +47,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-4. **Filter by distance threshold**: To return only records within a similarity cutoff (without ranking), place `target` directly on the condition alongside `comparator` and `value`. Omit `sort`.
+4. **Filter by distance threshold**: To return only records within a similarity cutoff (without ranking), place `target` directly on the condition alongside `comparator` and `value`. This bounds result quality rather than ranking by similarity.
 
    ```javascript
    let results = Document.search({
@@ -60,7 +60,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-5. **Include computed distance in results**: Use the special `$distance` field in `select` to return the distance from the target vector. Works with both `sort`-based and `conditions`-based queries.
+5. **Include computed distance in results**: Use the special `$distance` field in `select` to return the distance from the target vector. Available in both `sort`-based and threshold-based queries.
 
    ```javascript
    let results = Document.search({
@@ -70,43 +70,59 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-6. **Tune HNSW parameters**: Pass additional parameters to `@indexed(type: "HNSW", ...)` to control index quality and performance.
+6. **Tune per-query search options**: Pass `distance` and `ef` directly on the `sort` descriptor to override index defaults for a single query.
 
-   | Parameter              | Default           | Description                                                                                         |
-   | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
-   | `distance`             | `"cosine"`        | Distance function: `"euclidean"` or `"cosine"` (negative cosine similarity)                         |
-   | `efConstruction`       | `100`             | Max nodes explored during index construction. Higher = better recall, lower = better performance    |
-   | `M`                    | `16`              | Preferred connections per graph layer. Higher = more space, better recall for high-dimensional data |
-   | `optimizeRouting`      | `0.5`             | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive)          |
-   | `mL`                   | computed from `M` | Normalization factor for level generation                                                           |
-   | `efSearchConstruction` | `50`              | Max nodes explored during search                                                                    |
+   ```javascript
+   let results = Document.search({
+   	sort: { attribute: 'textEmbeddings', target: searchVector, distance: 'dotProduct', ef: 200 },
+   	limit: 5,
+   });
+   ```
+
+   - `distance` — overrides the distance function for this query: `"cosine"`, `"euclidean"`, or `"dotProduct"`.
+   - `ef` — overrides the search exploration budget. Higher values improve recall at the cost of latency.
+
+7. **Configure HNSW index parameters**: Pass parameters directly in the `@indexed` directive. Structural parameters (`distance`, `M`, `efConstruction`, `quantization`) trigger an index rebuild when changed; `efConstructionSearch` does not.
+
+   ```graphql
+   type Document @table {
+   	id: Long @primaryKey
+   	textEmbeddings: [Float]
+   		@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
+   }
+   ```
+
+8. **Enable vector quantization**: Use `quantization: "int8"` to store vectors as 8-bit integers, reducing index size and memory usage. Harper re-ranks nearest-neighbor `sort` results against full-precision vectors automatically.
+
+   ```graphql
+   type Document @table {
+   	id: Long @primaryKey
+   	textEmbeddings: [Float] @indexed(type: "HNSW", quantization: "int8")
+   }
+   ```
 
 ## Examples
 
-**Schema with custom HNSW parameters:**
+Full schema with custom HNSW parameters and a nearest-neighbor query with distance output:
 
 ```graphql
 type Document @table {
 	id: Long @primaryKey
 	textEmbeddings: [Float]
-		@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efSearchConstruction: 100)
+		@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
 }
 ```
 
-**Nearest-neighbor search with distance score:**
-
 ```javascript
+// Nearest-neighbor search with distance scores
 let results = Document.search({
 	select: ['name', '$distance'],
 	sort: { attribute: 'textEmbeddings', target: searchVector },
 	limit: 5,
 });
-```
 
-**Distance-threshold filter (no ranking):**
-
-```javascript
-let results = Document.search({
+// Distance-threshold query (no ranking)
+let closeMatches = Document.search({
 	conditions: {
 		attribute: 'textEmbeddings',
 		comparator: 'lt',
@@ -118,7 +134,21 @@ let results = Document.search({
 
 ## Notes
 
-- The default `distance` function is `cosine`. Pass `distance: "euclidean"` to switch.
-- `efConstruction` controls index build quality; raising it improves recall at the cost of build time.
+### HNSW Parameters
+
+| Parameter              | Default           | Description                                                                                            |
+| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `distance`             | `"cosine"`        | Distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"`                                        |
+| `efConstruction`       | `100`             | Max nodes explored during index construction. Higher = better recall, lower = better performance       |
+| `M`                    | `16`              | Preferred connections per graph layer. Higher = more space, better recall for high-dimensional data    |
+| `optimizeRouting`      | `0.5`             | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive)             |
+| `mL`                   | computed from `M` | Normalization factor for level generation                                                              |
+| `efConstructionSearch` | auto-scaled       | Max nodes explored during search. When unset, auto-scales with index size; setting it fixes the budget |
+| `quantization`         | —                 | `"int8"` stores vectors quantized to int8                                                              |
+
+- The `distance` option on a per-query `sort` descriptor accepts `"cosine"`, `"euclidean"`, or `"dotProduct"`.
+- When no `ef` is passed and `efConstructionSearch` (or `efConstruction`) is not explicitly set on the index, the search budget auto-scales with index size.
+- `efConstruction` seeds the initial value of `efConstructionSearch`; setting either one fixes the search budget.
+- The correct parameter name is `efConstructionSearch` (not `efSearchConstruction`).
 - `$distance` is available in both `sort`-based ranking and `conditions`-based threshold queries.
-- Use the threshold (`conditions` + `target`) form when you want to bound result quality by a similarity cutoff rather than ranking by similarity.
+- For `quantization: "int8"`, distance-threshold (`lt`/`le`) queries filter on approximate distance; `sort` queries re-rank against full-precision vectors.