@harperfast/skills 1.6.0 → 1.7.0

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: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  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 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.
 
    ```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 containing `attribute` (the indexed field name) 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 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**: To return only records within a similarity cutoff (without ranking), place `target` directly on the condition alongside `comparator` and `value`. Omit `sort`.
+
+   ```javascript
+   let results = Document.search({
+   	conditions: {
+   		attribute: 'textEmbeddings',
+   		comparator: 'lt',
+   		value: 0.1,
+   		target: searchVector,
+   	},
+   });
+   ```
+
+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.
+
+   ```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 score:**
 
 ```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`. Pass `distance: "euclidean"` to switch.
+- `efConstruction` controls index build quality; raising it improves recall at the cost of build time.
+- `$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.

package/harper-best-practices/rules.manifest.yaml

@@ -5,10 +5,10 @@
 # (rule bodies, AGENTS.md). See docs/plans/docs-driven-skills.md for the
 # full schema definition and Manifest ↔ frontmatter reconciliation semantics.
 #
-# All 20 rules currently use mode: synthesized (hand-authored bodies),
-# matching the state of the repo at the time this manifest was introduced.
-# Subsequent phases progressively flip individual rules to mode: generate
-# or mode: direct as docs sources are wired up.
+# Phase 2 flipped vector-indexing to mode: generate.
+# Phase 3 flips 7 obvious 1:1 rules to mode: generate (automatic-apis,
+# querying-rest-apis, real-time-apps, checking-authentication, logging,
+# deploying-to-harper-fabric, caching). All others remain synthesized.
 
 rules:
   # ===========================================================================
@@ -78,28 +78,75 @@ rules:
     category: api
     priority: 2
     order: 1
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/rest/overview.md
+        role: primary
+      - path: reference/v5/rest/websockets.md
+        role: supplemental
+    must_cover:
+      - 'rest: true'
+      - '@export'
+      - 'WebSocket'
+    cross_links:
+      - querying-rest-apis
+      - real-time-apps
 
   - rule: querying-rest-apis
     description: How to use query parameters to filter, sort, and paginate Harper REST APIs.
     category: api
     priority: 2
     order: 2
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/rest/querying.md
+        role: primary
+    must_cover:
+      - '=gt='
+      - '=lt='
+      - 'select('
+      - 'sort('
+      - 'limit('
+    cross_links:
+      - automatic-apis
 
   - rule: real-time-apps
     description: How to build real-time features in Harper using WebSockets and Pub/Sub.
     category: api
     priority: 2
     order: 3
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/rest/websockets.md
+        role: primary
+    must_cover:
+      - 'WebSocket'
+      - 'connect('
+    cross_links:
+      - automatic-apis
 
   - rule: checking-authentication
     description: How to handle user authentication and sessions in Harper Resources.
     category: api
     priority: 2
     order: 4
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/resources/resource-api.md
+        section: '`getCurrentUser(): User | undefined`'
+        role: primary
+      - path: reference/v5/resources/resource-api.md
+        section: 'Session and Login from a Resource'
+        role: primary
+      - path: reference/v5/security/jwt-authentication.md
+        role: supplemental
+    must_cover:
+      - 'getCurrentUser()'
+      - 'getContext()'
+      - 'context.login'
+      - 'enableSessions'
+    cross_links:
+      - custom-resources
 
   # ===========================================================================
   # Logic & Extension (priority 3 — MEDIUM)
@@ -138,7 +185,17 @@ rules:
     category: logic
     priority: 3
     order: 5
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: learn/developers/caching-with-harper.md
+        role: primary
+    must_cover:
+      - 'expiration'
+      - 'sourcedFrom'
+      - '@table'
+    cross_links:
+      - custom-resources
+      - automatic-apis
 
   # ===========================================================================
   # Infrastructure & Ops (priority 4 — MEDIUM)
@@ -149,7 +206,19 @@ rules:
     category: ops
     priority: 4
     order: 1
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/components/applications.md
+        section: 'Remote Management'
+        role: primary
+      - path: fabric/cluster-creation-management.md
+        section: 'Connecting the Harper CLI to a Cluster'
+        role: supplemental
+    must_cover:
+      - 'harper deploy'
+      - 'harper login'
+    cross_links:
+      - creating-a-fabric-account-and-cluster
 
   - rule: creating-a-fabric-account-and-cluster
     description: How to create a Harper Fabric account, organization, and cluster.
@@ -177,4 +246,13 @@ rules:
     category: ops
     priority: 4
     order: 5
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/logging/overview.md
+        role: primary
+      - path: reference/v5/logging/api.md
+        role: primary
+    must_cover:
+      - 'console.log'
+      - 'logger'
+      - 'withTag('

package/package.json

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