@harperfast/skills 1.6.1 → 1.7.0

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

@@ -5,7 +5,7 @@ metadata:
   mode: generate
   sources:
     - reference/v5/database/schema.md#Vector Indexing
-  sourceCommit: 6d4a30ccd5b32528e0e9963565782dca9fff5ada
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
   inputHash: 3732961c671aac00
 ---
 
@@ -19,7 +19,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
 
 ## How It Works
 
-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.
+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 or writing s
    }
    ```
 
-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.
+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 or writing s
    });
    ```
 
-3. **Combine HNSW with filter conditions**: Add a `conditions` array alongside `sort` to pre-filter records 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,7 @@ Apply this rule when adding a vector index to a Harper table schema or writing s
    });
    ```
 
-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.
+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({
@@ -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**: 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.
+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({
@@ -70,7 +70,7 @@ 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 HNSW parameters**: Pass additional parameters to `@indexed(type: "HNSW", ...)` to control index quality and performance.
 
    | Parameter              | Default           | Description                                                                                         |
    | ---------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
@@ -93,7 +93,7 @@ type Document @table {
 }
 ```
 
-**Nearest-neighbor search with distance output:**
+**Nearest-neighbor search with distance score:**
 
 ```javascript
 let results = Document.search({
@@ -118,7 +118,7 @@ let results = Document.search({
 
 ## Notes
 
-- 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.
+- 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.1",
+	"version": "1.7.0",
 	"description": "Best practices for making awesome Harper apps with your favorite Agent",
 	"keywords": [],
 	"homepage": "https://github.com/harperfast",