@harperfast/skills 1.6.0 → 1.6.1

package/dist/index.js

@@ -47,7 +47,7 @@ export const rules = {
 	"serving-web-content": "---\nname: serving-web-content\ndescription: How to serve static files and integrated Vite/React applications in Harper.\nmetadata:\n  mode: synthesized\n---\n\n# Serving Web Content\n\nInstructions for the agent to follow when serving web content from Harper.\n\n## When to Use\n\nUse this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) directly from your Harper instance.\n\n## How It Works\n\n1. **Choose a Method**: Decide between the simple Static Plugin or the integrated Vite Plugin.\n2. **Option A: Static Plugin (Simple)**:\n   - Add to `config.yaml`:\n     ```yaml\n     static:\n       files: 'web/*'\n     ```\n   - Place files in a `web/` folder in the project root.\n   - Files are served at the root URL (e.g., `http://localhost:9926/index.html`).\n3. **Option B: Vite Plugin (Advanced/Development)**:\n   - Add to `config.yaml`:\n     ```yaml\n     '@harperfast/vite-plugin':\n       package: '@harperfast/vite-plugin'\n     ```\n   - Ensure `vite.config.ts` and `index.html` are in the project root.\n\n   ```javascript\n   import vue from '@vitejs/plugin-vue';\n   import path from 'node:path';\n   import { defineConfig } from 'vite';\n\n   // https://vite.dev/config/\n   export default defineConfig({\n   \tplugins: [vue()],\n   \tresolve: {\n   \t\talias: {\n   \t\t\t'@': path.resolve(import.meta.dirname, './src'),\n   \t\t},\n   \t},\n   \tbuild: {\n   \t\toutDir: 'web',\n   \t\temptyOutDir: true,\n   \t\trolldownOptions: {\n   \t\t\texternal: ['**/*.test.*', '**/*.spec.*'],\n   \t\t},\n   \t},\n   });\n   ```\n\n   - Install dependencies: `npm install --save-dev vite @harperfast/vite-plugin`.\n   - Then `harper run .` will start up Harper and Vite with HMR. Vite does _not_ need to be executed separately.\n\n4. **Deploy for Production**: For Vite apps, use a build script to generate static files into a `web/` folder and deploy them using the static handler pattern. For example, these scripts in a package.json can perform the necessary steps:\n   ```json\n   \"build\": \"vite build\",\n   \"deploy\": \"rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && (cd deploy && harper deploy_component . project=web restart=rolling replicated=true) && rm -Rf deploy\",\n   ```\n   Then in production, the \"Static Plugin\" option will performantly and securely serve your assets. `npm create harper@latest` scaffolds all of this for you.\n",
 	"typescript-type-stripping": "---\nname: typescript-type-stripping\ndescription: How to run TypeScript files directly in Harper without a build step.\nmetadata:\n  mode: synthesized\n---\n\n# TypeScript Type Stripping\n\nInstructions for the agent to follow when using TypeScript in Harper.\n\n## When to Use\n\nUse this skill when you want to write Harper Resources in TypeScript and have them execute directly in Node.js without an intermediate build or compilation step.\n\n## How It Works\n\n1. **Verify Node.js Version**: Ensure you are using Node.js v22.6.0 or higher.\n2. **Name Files with `.ts`**: Create your resource files in the `resources/` directory with a `.ts` extension.\n3. **Use TypeScript Syntax**: Write your resource classes using standard TypeScript (interfaces, types, etc.).\n   ```typescript\n   import { Resource } from 'harper';\n   export class MyResource extends Resource {\n   \tasync get(): Promise<{ message: string }> {\n   \t\treturn { message: 'Running TS directly!' };\n   \t}\n   }\n   ```\n4. **Use Explicit Extensions in Imports**: When importing other local modules, include the `.ts` extension: `import { helper } from './helper.ts'`.\n5. **Configure `config.yaml`**: Ensure `jsResource` points to your `.ts` files:\n   ```yaml\n   jsResource:\n     files: 'resources/*.ts'\n   ```\n",
 	"using-blob-datatype": "---\nname: using-blob-datatype\ndescription: How to use the Blob data type for efficient binary storage in Harper.\nmetadata:\n  mode: synthesized\n---\n\n# Using Blob Datatype\n\nInstructions for the agent to follow when working with the Blob data type in Harper.\n\n## When to Use\n\nUse 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.\n\n## How It Works\n\n1. **Define Blob Fields**: In your GraphQL schema, use the `Blob` type:\n   ```graphql\n   type MyTable @table {\n   \tid: ID @primaryKey\n   \tdata: Blob\n   }\n   ```\n2. **Create and Store Blobs**: Use `createBlob()` from Harper's globals to wrap Buffers or Streams:\n   ```javascript\n   import { tables } from 'harper';\n   const blob = createBlob(largeBuffer);\n   await tables.MyTable.put('my-id', { data: blob });\n   ```\n3. **Use Streaming (Optional)**: For very large files, pass a stream to `createBlob()` to avoid loading the entire file into memory.\n4. **Read Blob Data**: Retrieve the record and use `.bytes()` or streaming interfaces on the blob field:\n   ```javascript\n   const record = await tables.MyTable.get('my-id');\n   const buffer = await record.data.bytes();\n   ```\n5. **Ensure Write Completion**: Use `saveBeforeCommit: true` in `createBlob` options if you need the blob fully written before the record is committed.\n6. **Handle Errors**: Attach error listeners to the blob object to handle streaming failures.\n",
-	"vector-indexing": "---\nname: vector-indexing\ndescription: How to enable and query vector indexes for similarity search in Harper.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/database/schema.md#Vector Indexing\n  sourceCommit: e8fc9e51c7c04637b8ec02d073eed42d495034f1\n  inputHash: 9c47b18c8795e403\n---\n\n# Vector Indexing\n\nInstructions for the agent to follow when enabling and querying vector indexes for similarity search in Harper using the HNSW algorithm.\n\n## When to Use\n\nApply this rule when adding a vector index to a Harper table schema to support approximate nearest-neighbor (similarity) search on high-dimensional float arrays. Use it whenever a query requires ranking results by vector similarity, optionally combined with filter conditions.\n\n## How It Works\n\n1. **Define the table schema with a vector index**: Add `@indexed(type: \"HNSW\")` to a `[Float]` attribute on a `@table` type. See [adding-tables-with-schemas](adding-tables-with-schemas.md) for general schema setup.\n\n   ```graphql\n   type Document @table {\n   \tid: Long @primaryKey\n   \ttextEmbeddings: [Float] @indexed(type: \"HNSW\")\n   }\n   ```\n\n2. **Query by nearest neighbors**: Call `.search()` with a `sort` parameter specifying the indexed `attribute` and a `target` vector. The `target` is the query vector to compare against.\n\n   ```javascript\n   let results = Document.search({\n   \tsort: { attribute: 'textEmbeddings', target: searchVector },\n   \tlimit: 5,\n   });\n   ```\n\n3. **Combine with filter conditions**: Add a `conditions` array alongside `sort` to filter results before ranking by similarity.\n\n   ```javascript\n   let results = Document.search({\n   \tconditions: [{ attribute: 'price', comparator: 'lt', value: 50 }],\n   \tsort: { attribute: 'textEmbeddings', target: searchVector },\n   \tlimit: 5,\n   });\n   ```\n\n4. **Tune HNSW parameters**: Pass additional parameters directly in the `@indexed` directive to control index quality and performance.\n\n   | Parameter              | Default           | Description                                                                                         |\n   | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |\n   | `distance`             | `\"cosine\"`        | Distance function: `\"euclidean\"` or `\"cosine\"` (negative cosine similarity)                         |\n   | `efConstruction`       | `100`             | Max nodes explored during index construction. Higher = better recall, lower = better performance    |\n   | `M`                    | `16`              | Preferred connections per graph layer. Higher = more space, better recall for high-dimensional data |\n   | `optimizeRouting`      | `0.5`             | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive)          |\n   | `mL`                   | computed from `M` | Normalization factor for level generation                                                           |\n   | `efSearchConstruction` | `50`              | Max nodes explored during search                                                                    |\n\n## Examples\n\nSchema with default settings:\n\n```graphql\ntype Document @table {\n\tid: Long @primaryKey\n\ttextEmbeddings: [Float] @indexed(type: \"HNSW\")\n}\n```\n\nSchema with custom parameters (euclidean distance, routing disabled, higher search recall):\n\n```graphql\ntype Document @table {\n\tid: Long @primaryKey\n\ttextEmbeddings: [Float]\n\t\t@indexed(type: \"HNSW\", distance: \"euclidean\", optimizeRouting: 0, efSearchConstruction: 100)\n}\n```\n\nFiltered nearest-neighbor search:\n\n```javascript\nlet results = Document.search({\n\tconditions: [{ attribute: 'price', comparator: 'lt', value: 50 }],\n\tsort: { attribute: 'textEmbeddings', target: searchVector },\n\tlimit: 5,\n});\n```\n\n## Notes\n\n- The default `distance` function is `cosine`. Use `\"euclidean\"` when your vectors are not normalized or when Euclidean geometry better fits your use case.\n- Increasing `efConstruction` improves index recall at the cost of build performance.\n- `mL` is computed automatically from `M` unless explicitly overridden.\n- Always pair `sort` with a `limit` to bound the number of nearest-neighbor results returned.\n"
+	"vector-indexing": "---\nname: vector-indexing\ndescription: How to enable and query vector indexes for similarity search in Harper.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/database/schema.md#Vector Indexing\n  sourceCommit: 6d4a30ccd5b32528e0e9963565782dca9fff5ada\n  inputHash: 3732961c671aac00\n---\n\n# Vector Indexing\n\nInstructions for the agent to follow when enabling and querying vector indexes for similarity search in Harper using the HNSW algorithm.\n\n## When to Use\n\nApply 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.\n\n## How It Works\n\n1. **Declare a 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.\n\n   ```graphql\n   type Document @table {\n   \tid: Long @primaryKey\n   \ttextEmbeddings: [Float] @indexed(type: \"HNSW\")\n   }\n   ```\n\n2. **Query by nearest neighbors using `sort`**: Call `Document.search()` with a `sort` object specifying `attribute` (the indexed field) and `target` (the query vector). Include `limit` to cap results.\n\n   ```javascript\n   let results = Document.search({\n   \tsort: { attribute: 'textEmbeddings', target: searchVector },\n   \tlimit: 5,\n   });\n   ```\n\n3. **Combine HNSW with filter conditions**: Add a `conditions` array alongside `sort` to pre-filter records before ranking by similarity.\n\n   ```javascript\n   let results = Document.search({\n   \tconditions: [{ attribute: 'price', comparator: 'lt', value: 50 }],\n   \tsort: { attribute: 'textEmbeddings', target: searchVector },\n   \tlimit: 5,\n   });\n   ```\n\n4. **Filter by distance threshold**: Place `target` directly on a condition (alongside `attribute`, `comparator`, and `value`) to return only records whose distance to the target vector is below a threshold. Use this form to bound result quality by a similarity cutoff rather than ranking.\n\n   ```javascript\n   let results = Document.search({\n   \tconditions: {\n   \t\tattribute: 'textEmbeddings',\n   \t\tcomparator: 'lt',\n   \t\tvalue: 0.1,\n   \t\ttarget: searchVector,\n   \t},\n   });\n   ```\n\n5. **Include computed distance in results**: Add `'$distance'` to the `select` array to return the computed distance from the target vector alongside each record. `$distance` works in both `sort`-based and `conditions`-based queries.\n\n   ```javascript\n   let results = Document.search({\n   \tselect: ['name', '$distance'],\n   \tsort: { attribute: 'textEmbeddings', target: searchVector },\n   \tlimit: 5,\n   });\n   ```\n\n6. **Tune HNSW parameters**: Pass additional parameters to `@indexed(type: \"HNSW\", ...)` to control index quality and performance:\n\n   | Parameter              | Default           | Description                                                                                         |\n   | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |\n   | `distance`             | `\"cosine\"`        | Distance function: `\"euclidean\"` or `\"cosine\"` (negative cosine similarity)                         |\n   | `efConstruction`       | `100`             | Max nodes explored during index construction. Higher = better recall, lower = better performance    |\n   | `M`                    | `16`              | Preferred connections per graph layer. Higher = more space, better recall for high-dimensional data |\n   | `optimizeRouting`      | `0.5`             | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive)          |\n   | `mL`                   | computed from `M` | Normalization factor for level generation                                                           |\n   | `efSearchConstruction` | `50`              | Max nodes explored during search                                                                    |\n\n## Examples\n\n**Schema with custom HNSW parameters:**\n\n```graphql\ntype Document @table {\n\tid: Long @primaryKey\n\ttextEmbeddings: [Float]\n\t\t@indexed(type: \"HNSW\", distance: \"euclidean\", optimizeRouting: 0, efSearchConstruction: 100)\n}\n```\n\n**Nearest-neighbor search with distance output:**\n\n```javascript\nlet results = Document.search({\n\tselect: ['name', '$distance'],\n\tsort: { attribute: 'textEmbeddings', target: searchVector },\n\tlimit: 5,\n});\n```\n\n**Distance-threshold filter (no ranking):**\n\n```javascript\nlet results = Document.search({\n\tconditions: {\n\t\tattribute: 'textEmbeddings',\n\t\tcomparator: 'lt',\n\t\tvalue: 0.1,\n\t\ttarget: searchVector,\n\t},\n});\n```\n\n## Notes\n\n- The default `distance` function is `cosine`. To use Euclidean distance, set `distance: \"euclidean\"` in the `@indexed` directive.\n- `efConstruction` controls index build quality; increase it to improve recall at the cost of slower indexing.\n- `$distance` is a special field — prefix it with `$` exactly as shown; it is not a schema attribute.\n- `target` is required in both `sort`-based and threshold-based condition queries to identify the reference vector for distance computation.\n"
 };
 
 /**

package/harper-best-practices/AGENTS.md

@@ -139,11 +139,11 @@ Instructions for the agent to follow when enabling and querying vector indexes f
 
 #### When to Use
 
-Apply this rule when adding a vector index to a Harper table schema to support approximate nearest-neighbor (similarity) search on high-dimensional float arrays. Use it whenever a query requires ranking results by vector similarity, optionally combined with filter conditions.
+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.
 
 #### How It Works
 
-1. **Define the table schema with a vector index**: Add `@indexed(type: "HNSW")` to a `[Float]` attribute on a `@table` type. See [adding-tables-with-schemas](adding-tables-with-schemas.md) for general schema setup.
+1. **Declare a 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.
 
    ```graphql
    type Document @table {
@@ -152,7 +152,7 @@ Apply this rule when adding a vector index to a Harper table schema to support a
    }
    ```
 
-2. **Query by nearest neighbors**: Call `.search()` with a `sort` parameter specifying the indexed `attribute` and a `target` vector. The `target` is the query vector to compare against.
+2. **Query by nearest neighbors using `sort`**: Call `Document.search()` with a `sort` object specifying `attribute` (the indexed field) and `target` (the query vector). Include `limit` to cap results.
 
    ```javascript
    let results = Document.search({
@@ -161,7 +161,7 @@ Apply this rule when adding a vector index to a Harper table schema to support a
    });
    ```
 
-3. **Combine with filter conditions**: Add a `conditions` array alongside `sort` to filter results before ranking by similarity.
+3. **Combine HNSW with filter conditions**: Add a `conditions` array alongside `sort` to pre-filter records before ranking by similarity.
 
    ```javascript
    let results = Document.search({
@@ -171,7 +171,30 @@ Apply this rule when adding a vector index to a Harper table schema to support a
    });
    ```
 
-4. **Tune HNSW parameters**: Pass additional parameters directly in the `@indexed` directive to control index quality and performance.
+4. **Filter by distance threshold**: Place `target` directly on a condition (alongside `attribute`, `comparator`, and `value`) to return only records whose distance to the target vector is below a threshold. Use this form to bound result quality by a similarity cutoff rather than ranking.
+
+   ```javascript
+   let results = Document.search({
+   	conditions: {
+   		attribute: 'textEmbeddings',
+   		comparator: 'lt',
+   		value: 0.1,
+   		target: searchVector,
+   	},
+   });
+   ```
+
+5. **Include computed distance in results**: Add `'$distance'` to the `select` array to return the computed distance from the target vector alongside each record. `$distance` works in both `sort`-based and `conditions`-based queries.
+
+   ```javascript
+   let results = Document.search({
+   	select: ['name', '$distance'],
+   	sort: { attribute: 'textEmbeddings', target: searchVector },
+   	limit: 5,
+   });
+   ```
+
+6. **Tune HNSW parameters**: Pass additional parameters to `@indexed(type: "HNSW", ...)` to control index quality and performance:
 
    | Parameter              | Default           | Description                                                                                         |
    | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
@@ -184,16 +207,7 @@ Apply this rule when adding a vector index to a Harper table schema to support a
 
 #### Examples
 
-Schema with default settings:
-
-```graphql
-type Document @table {
-	id: Long @primaryKey
-	textEmbeddings: [Float] @indexed(type: "HNSW")
-}
-```
-
-Schema with custom parameters (euclidean distance, routing disabled, higher search recall):
+**Schema with custom HNSW parameters:**
 
 ```graphql
 type Document @table {
@@ -203,22 +217,35 @@ type Document @table {
 }
 ```
 
-Filtered nearest-neighbor search:
+**Nearest-neighbor search with distance output:**
 
 ```javascript
 let results = Document.search({
-	conditions: [{ attribute: 'price', comparator: 'lt', value: 50 }],
+	select: ['name', '$distance'],
 	sort: { attribute: 'textEmbeddings', target: searchVector },
 	limit: 5,
 });
 ```
 
+**Distance-threshold filter (no ranking):**
+
+```javascript
+let results = Document.search({
+	conditions: {
+		attribute: 'textEmbeddings',
+		comparator: 'lt',
+		value: 0.1,
+		target: searchVector,
+	},
+});
+```
+
 #### Notes
 
-- The default `distance` function is `cosine`. Use `"euclidean"` when your vectors are not normalized or when Euclidean geometry better fits your use case.
-- Increasing `efConstruction` improves index recall at the cost of build performance.
-- `mL` is computed automatically from `M` unless explicitly overridden.
-- Always pair `sort` with a `limit` to bound the number of nearest-neighbor results returned.
+- The default `distance` function is `cosine`. To use Euclidean distance, set `distance: "euclidean"` in the `@indexed` directive.
+- `efConstruction` controls index build quality; increase it to improve recall at the cost of slower indexing.
+- `$distance` is a special field — prefix it with `$` exactly as shown; it is not a schema attribute.
+- `target` is required in both `sort`-based and threshold-based condition queries to identify the reference vector for distance computation.
 
 ### 1.5 Using Blob Datatype
 

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

@@ -5,8 +5,8 @@ metadata:
   mode: generate
   sources:
     - reference/v5/database/schema.md#Vector Indexing
-  sourceCommit: e8fc9e51c7c04637b8ec02d073eed42d495034f1
-  inputHash: 9c47b18c8795e403
+  sourceCommit: 6d4a30ccd5b32528e0e9963565782dca9fff5ada
+  inputHash: 3732961c671aac00
 ---
 
 # Vector Indexing
@@ -15,11 +15,11 @@ Instructions for the agent to follow when enabling and querying vector indexes f
 
 ## When to Use
 
-Apply this rule when adding a vector index to a Harper table schema to support approximate nearest-neighbor (similarity) search on high-dimensional float arrays. Use it whenever a query requires ranking results by vector similarity, optionally combined with filter conditions.
+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.
 
 ## How It Works
 
-1. **Define the table schema with a vector index**: Add `@indexed(type: "HNSW")` to a `[Float]` attribute on a `@table` type. See [adding-tables-with-schemas](adding-tables-with-schemas.md) for general schema setup.
+1. **Declare a 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.
 
    ```graphql
    type Document @table {
@@ -28,7 +28,7 @@ Apply this rule when adding a vector index to a Harper table schema to support a
    }
    ```
 
-2. **Query by nearest neighbors**: Call `.search()` with a `sort` parameter specifying the indexed `attribute` and a `target` vector. The `target` is the query vector to compare against.
+2. **Query by nearest neighbors using `sort`**: Call `Document.search()` with a `sort` object specifying `attribute` (the indexed field) and `target` (the query vector). Include `limit` to cap results.
 
    ```javascript
    let results = Document.search({
@@ -37,7 +37,7 @@ Apply this rule when adding a vector index to a Harper table schema to support a
    });
    ```
 
-3. **Combine with filter conditions**: Add a `conditions` array alongside `sort` to filter results before ranking by similarity.
+3. **Combine HNSW with filter conditions**: Add a `conditions` array alongside `sort` to pre-filter records before ranking by similarity.
 
    ```javascript
    let results = Document.search({
@@ -47,7 +47,30 @@ Apply this rule when adding a vector index to a Harper table schema to support a
    });
    ```
 
-4. **Tune HNSW parameters**: Pass additional parameters directly in the `@indexed` directive to control index quality and performance.
+4. **Filter by distance threshold**: Place `target` directly on a condition (alongside `attribute`, `comparator`, and `value`) to return only records whose distance to the target vector is below a threshold. Use this form to bound result quality by a similarity cutoff rather than ranking.
+
+   ```javascript
+   let results = Document.search({
+   	conditions: {
+   		attribute: 'textEmbeddings',
+   		comparator: 'lt',
+   		value: 0.1,
+   		target: searchVector,
+   	},
+   });
+   ```
+
+5. **Include computed distance in results**: Add `'$distance'` to the `select` array to return the computed distance from the target vector alongside each record. `$distance` works in both `sort`-based and `conditions`-based queries.
+
+   ```javascript
+   let results = Document.search({
+   	select: ['name', '$distance'],
+   	sort: { attribute: 'textEmbeddings', target: searchVector },
+   	limit: 5,
+   });
+   ```
+
+6. **Tune HNSW parameters**: Pass additional parameters to `@indexed(type: "HNSW", ...)` to control index quality and performance:
 
    | Parameter              | Default           | Description                                                                                         |
    | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
@@ -60,16 +83,7 @@ Apply this rule when adding a vector index to a Harper table schema to support a
 
 ## Examples
 
-Schema with default settings:
-
-```graphql
-type Document @table {
-	id: Long @primaryKey
-	textEmbeddings: [Float] @indexed(type: "HNSW")
-}
-```
-
-Schema with custom parameters (euclidean distance, routing disabled, higher search recall):
+**Schema with custom HNSW parameters:**
 
 ```graphql
 type Document @table {
@@ -79,19 +93,32 @@ type Document @table {
 }
 ```
 
-Filtered nearest-neighbor search:
+**Nearest-neighbor search with distance output:**
 
 ```javascript
 let results = Document.search({
-	conditions: [{ attribute: 'price', comparator: 'lt', value: 50 }],
+	select: ['name', '$distance'],
 	sort: { attribute: 'textEmbeddings', target: searchVector },
 	limit: 5,
 });
 ```
 
+**Distance-threshold filter (no ranking):**
+
+```javascript
+let results = Document.search({
+	conditions: {
+		attribute: 'textEmbeddings',
+		comparator: 'lt',
+		value: 0.1,
+		target: searchVector,
+	},
+});
+```
+
 ## Notes
 
-- The default `distance` function is `cosine`. Use `"euclidean"` when your vectors are not normalized or when Euclidean geometry better fits your use case.
-- Increasing `efConstruction` improves index recall at the cost of build performance.
-- `mL` is computed automatically from `M` unless explicitly overridden.
-- Always pair `sort` with a `limit` to bound the number of nearest-neighbor results returned.
+- The default `distance` function is `cosine`. To use Euclidean distance, set `distance: "euclidean"` in the `@indexed` directive.
+- `efConstruction` controls index build quality; increase it to improve recall at the cost of slower indexing.
+- `$distance` is a special field — prefix it with `$` exactly as shown; it is not a schema attribute.
+- `target` is required in both `sort`-based and threshold-based condition queries to identify the reference vector for distance computation.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/skills",
-	"version": "1.6.0",
+	"version": "1.6.1",
 	"description": "Best practices for making awesome Harper apps with your favorite Agent",
 	"keywords": [],
 	"homepage": "https://github.com/harperfast",