@harperfast/skills 1.4.5 → 1.4.7

package/dist/index.js

@@ -40,11 +40,11 @@ export const rules = {
 	"extending-tables": "---\nname: extending-tables\ndescription: How to add custom logic to automatically generated table resources in Harper.\n---\n\n# Extending Tables\n\nInstructions for the agent to follow when extending table resources in Harper.\n\n## When to Use\n\nUse this skill when you need to add custom validation, side effects (like webhooks), data transformation, or custom access control to the standard CRUD operations of a Harper table.\n\n## How It Works\n\n1. **Define the Table in GraphQL**: In your `.graphql` schema, define the table using the `@table` directive. **Do not** use `@export` if you plan to extend it.\n   ```graphql\n   type MyTable @table {\n   \tid: ID @primaryKey\n   \tname: String\n   }\n   ```\n2. **Create the Extension File**: Create a `.ts` file in your `resources/` directory.\n3. **Extend the Table Resource**: Export a class that extends `tables.YourTableName`:\n\n   ```typescript\n   import { type RequestTargetOrId, tables } from 'harper';\n\n   export class MyTable extends tables.MyTable {\n   \tasync post(target: RequestTargetOrId, record: any) {\n   \t\t// Custom logic here\n   \t\tif (!record.name) {\n   \t\t\tthrow new Error('Name required');\n   \t\t}\n   \t\treturn super.post(target, record);\n   \t}\n   }\n   ```\n\n4. **Override Methods**: Override `get`, `post`, `put`, `patch`, or `delete` as needed. Always call `super[method]` to maintain default Harper functionality unless you intend to replace it entirely.\n5. **Implement Logic**: Use overrides for validation, side effects, or transforming data before/after database operations.\n",
 	"handling-binary-data": "---\nname: handling-binary-data\ndescription: How to store and serve binary data like images or audio in Harper.\n---\n\n# Handling Binary Data\n\nInstructions for the agent to follow when handling binary data in Harper.\n\n## When to Use\n\nUse this skill when you need to store binary files (images, audio, etc.) in the database or serve them back to clients via REST endpoints.\n\n## How It Works\n\n1. **Store Binary Data**: In your resource's `post` or `put` method, convert incoming data to Buffers and then to Blobs using `createBlob` from Harper's globals. Include the MIME type if available:\n\n   ```typescript\n   async post(target, record) {\n     if (record.data) {\n       record.data = createBlob(Buffer.from(record.data, record.encoding || 'base64'), {\n         type: record.contentType || 'application/octet-stream',\n       });\n     }\n     return super.post(target, record);\n   }\n   ```\n\n2. **Serve Binary Data**: In your resource's `get` method, return a response object with the appropriate `Content-Type` and the binary data in the `body`:\n   ```typescript\n   async get(target) {\n    const record = await super.get(target);\n    if (record?.data) {\n      return {\n        status: 200,\n        headers: { 'Content-Type': record.data.type || 'application/octet-stream' },\n        body: record.data,\n      };\n    }\n    return record;\n   }\n   ```\n3. **Use the Blob Type**: Ensure your GraphQL schema uses the `Blob` scalar for binary fields.\n",
 	"logging": "---\nname: logging\ndescription: Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.\n---\n\n# Logging Best Practices\n\nHarper provides a robust logging system that captures standard output and offers a granular, tagged logging interface for both local and deployed environments.\n\n## Standard Console Logging\n\nThe simplest way to log in Harper is using standard JavaScript console methods. `console.log()`, `console.warn()`, `console.error()`, and `console.trace()` are automatically captured by Harper and can be viewed in the logs.\n\n- `console.log(...)`: Captured as `stdout` level in Harper logs.\n- `console.warn(...)`: Captured as `stderr` level in Harper logs.\n- `console.error(...)`: Captured as `stderr` level in Harper logs.\n- `console.trace(...)`: Captured as `stdout` level in Harper logs (includes stack trace).\n\n## Harper Logger\n\nFor more granularity and better organization, use Harper's built-in `logger`. You can use the global `logger` object or import it from the `harper` package.\n\n### Log Levels\n\nThe Harper `logger` supports the following levels (ordered by increasing severity):\n\n- `trace`\n- `debug`\n- `info`\n- `warn`\n- `error`\n- `fatal`\n- `notify`\n\n### Usage\n\n```typescript\nimport { logger, loggerWithTag } from 'harper';\n\n// Basic logging\nlogger.info('Application started');\nlogger.error('An error occurred', error);\n\n// Tagged logging for better filtering (Namespacing)\nconst authLogger = loggerWithTag('auth');\nauthLogger.debug('User login attempt', { userId: '123' });\n```\n\nUsing `loggerWithTag` is highly recommended for grouping related logs, making them much easier to filter and analyze in the Harper Studio or via the API.\n\n## Programmatic Log Retrieval\n\nYou can programmatically read logs from a deployed Harper instance using the `read_log` operation. This is useful for building custom monitoring tools or debugging dashboards.\n\n### `read_log` Operation\n\nThe `read_log` operation is a POST request to the Harper instance.\n\n**Example Request:**\n\n```json\n{\n\t\"operation\": \"read_log\",\n\t\"limit\": 100,\n\t\"start\": 0,\n\t\"level\": \"error\",\n\t\"order\": \"desc\",\n\t\"from\": \"2024-01-01T00:00:00.000Z\",\n\t\"until\": \"2024-01-02T00:00:00.000Z\"\n}\n```\n\n### Parameters\n\n- `limit`: Number of log entries to return.\n- `start`: Offset for pagination.\n- `level`: Filter by log level (`info`, `error`, `warn`, `debug`, `trace`, `notify`, `fatal`, `stdout`, `stderr`).\n- `from`: ISO 8601 timestamp to start reading from.\n- `until`: ISO 8601 timestamp to stop reading at.\n- `order`: Sort order, either `asc` or `desc`.\n- `replicated`: (Boolean) Include logs from replicated nodes in a cluster.\n\n### Log Entry Structure\n\nEach log entry returned by `read_log` typically includes:\n\n- `level`: The severity level of the log.\n- `timestamp`: When the log was recorded.\n- `thread`: The execution thread.\n- `tags`: An array of tags (e.g., from `loggerWithTag`).\n- `node`: The node name in a Harper cluster.\n- `message`: The logged content.\n",
-	"programmatic-table-requests": "---\nname: programmatic-table-requests\ndescription: How to interact with Harper tables programmatically using the `tables` object.\n---\n\n# Programmatic Table Requests\n\nInstructions for the agent to follow when interacting with Harper tables via code.\n\n## When to Use\n\nUse this skill when you need to perform database operations (CRUD, search, subscribe) from within Harper Resources or scripts.\n\n## How It Works\n\n1. **Access the Table**: Use the global `tables` object followed by your table name (e.g., `tables.MyTable`).\n2. **Perform CRUD Operations**:\n   - **Get**: `await tables.MyTable.get(id)` for a single record or `await tables.MyTable.get({ conditions: [...] })` for multiple.\n   - **Create**: `await tables.MyTable.post(record)` (auto-generates ID) or `await tables.MyTable.put(id, record)`.\n   - **Update**: `await tables.MyTable.patch(id, partialRecord)` for partial updates.\n   - **Delete**: `await tables.MyTable.delete(id)`.\n3. **Use Updatable Records for Atomic Ops**: Call `update(id)` to get a reference, then use `addTo` or `subtractFrom` for atomic increments/decrements:\n   ```typescript\n   const stats = await tables.Stats.update('daily');\n   stats.addTo('viewCount', 1);\n   ```\n4. **Search and Stream**: Use `search(query)` for efficient streaming of large result sets:\n   ```typescript\n   for await (const record of tables.MyTable.search({ conditions: [...] })) {\n     // process record\n   }\n   ```\n5. **Real-time Subscriptions**: Use `subscribe(query)` to listen for changes:\n   ```typescript\n   for await (const event of tables.MyTable.subscribe(query)) {\n   \t// handle event\n   }\n   ```\n6. **Publish Events**: Use `publish(id, message)` to trigger subscriptions without necessarily persisting data.\n\n## Cautions\n\nBe 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.\n",
+	"programmatic-table-requests": "---\nname: programmatic-table-requests\ndescription: How to interact with Harper tables programmatically using the `tables` object.\n---\n\n# Programmatic Table Requests\n\nInstructions for the agent to follow when interacting with Harper tables via code.\n\n## When to Use\n\nUse this skill when you need to perform database operations (CRUD, search, subscribe) from within Harper Resources or scripts.\n\n## How It Works\n\n1. **Access the Table**: Use the global `tables` object followed by your table name (e.g., `tables.MyTable`).\n2. **Perform CRUD Operations**:\n   - **Get**: `await tables.MyTable.get(id)` for a single record or `await tables.MyTable.get({ conditions: [...] })` for multiple.\n   - **Create**: `await tables.MyTable.post(record)` (auto-generates ID) or `await tables.MyTable.put(id, record)`.\n   - **Update**: `await tables.MyTable.patch(id, partialRecord)` for partial updates.\n   - **Delete**: `await tables.MyTable.delete(id)`.\n3. **Use Updatable Records for Atomic Ops**: Call `update(id)` to get a reference, then use `addTo` or `subtractFrom` for atomic increments/decrements:\n   ```typescript\n   const stats = await tables.Stats.update('daily');\n   stats.addTo('viewCount', 1);\n   ```\n4. **Search and Stream**: Use `search(query)` for efficient streaming of large result sets:\n   ```typescript\n   for await (const record of tables.MyTable.search({ conditions: [...] })) {\n     // process record\n   }\n   ```\n   See the [Query Conditions](#query-conditions) section below for the full query object reference.\n5. **Real-time Subscriptions**: Use `subscribe(query)` to listen for changes:\n   ```typescript\n   for await (const event of tables.MyTable.subscribe(query)) {\n   \t// handle event\n   }\n   ```\n6. **Publish Events**: Use `publish(id, message)` to trigger subscriptions without necessarily persisting data.\n\n## Query Conditions\n\nWhen passing a query to `search()`, `get()`, or `subscribe()`, use a query object with a `conditions` array.\n\n### Condition Object Shape\n\n| Property     | Description                                                                                |\n| ------------ | ------------------------------------------------------------------------------------------ |\n| `attribute`  | Field name, or array of field names to traverse a relationship (e.g., `['brand', 'name']`) |\n| `value`      | The value to compare against                                                               |\n| `comparator` | One of the comparator strings below (default: `equals`)                                    |\n| `operator`   | `and` (default) or `or` — applies to a nested `conditions` block                           |\n| `conditions` | Nested array of condition objects for complex AND/OR logic                                 |\n\n### Comparator Values\n\nUse these exact strings — incorrect comparator names will silently fail or error:\n\n| Comparator           | Meaning                                                    |\n| -------------------- | ---------------------------------------------------------- |\n| `equals`             | Exact match (default)                                      |\n| `not_equal`          | Not equal                                                  |\n| `greater_than`       | `>`                                                        |\n| `greater_than_equal` | `>=`                                                       |\n| `less_than`          | `<`                                                        |\n| `less_than_equal`    | `<=`                                                       |\n| `starts_with`        | String starts with value                                   |\n| `contains`           | String contains value                                      |\n| `ends_with`          | String ends with value                                     |\n| `between`            | Value is between two bounds (pass `value` as `[min, max]`) |\n\n### Query Object Parameters\n\n| Property     | Description                                                                          |\n| ------------ | ------------------------------------------------------------------------------------ |\n| `conditions` | Array of condition objects                                                           |\n| `limit`      | Maximum number of records to return                                                  |\n| `offset`     | Number of records to skip (for pagination)                                           |\n| `select`     | Array of attribute names to return; supports `$id` and `$updatedtime`                |\n| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort |\n\n### Examples\n\n**Simple filter:**\n\n```javascript\nfor await (const record of tables.Product.search({\n  conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],\n  limit: 20,\n})) { ... }\n```\n\n**AND + nested OR:**\n\n```javascript\nfor await (const record of tables.Product.search({\n  conditions: [\n    { attribute: 'price', comparator: 'less_than', value: 100 },\n    {\n      operator: 'or',\n      conditions: [\n        { attribute: 'rating', comparator: 'greater_than', value: 4 },\n        { attribute: 'featured', value: true },\n      ],\n    },\n  ],\n})) { ... }\n```\n\n**Relationship traversal:**\n\n```javascript\nfor await (const record of tables.Book.search({\n  conditions: [{ attribute: ['brand', 'name'], comparator: 'equals', value: 'Harper' }],\n})) { ... }\n```\n\n**Sort and paginate:**\n\n```javascript\nfor await (const record of tables.Product.search({\n  conditions: [{ attribute: 'inStock', value: true }],\n  sort: { attribute: 'price', descending: false },\n  limit: 10,\n  offset: 20,\n})) { ... }\n```\n\n## Cautions\n\nBe 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.\n",
 	"querying-rest-apis": "---\nname: querying-rest-apis\ndescription: How to use query parameters to filter, sort, and paginate Harper REST APIs.\n---\n\n# Querying REST APIs\n\nInstructions for the agent to follow when querying Harper's REST APIs.\n\n## When to Use\n\nUse this skill when you need to perform advanced data retrieval (filtering, sorting, pagination, joins) using Harper's automatic REST endpoints.\n\n## How It Works\n\n1. **Basic Filtering**: Use attribute names as query parameters: `GET /Table/?key=value`.\n2. **Use Comparison Operators**: Append operators like `gt`, `ge`, `lt`, `le`, `ne` using FIQL-style syntax: `GET /Table/?price=gt=100`.\n3. **Apply Logic and Grouping**: Use `&` for AND, `|` for OR, and `()` for grouping: `GET /Table/?(rating=5|featured=true)&price=lt=50`.\n4. **Select Specific Fields**: Use `select()` to limit returned attributes: `GET /Table/?select(name,price)`.\n5. **Paginate Results**: Use `limit(count)` or `limit(offset, count)` to set the number of records to return and skip.\n   - Example (first 10): `GET /Table/?limit(10)`\n   - Example (skip 20, return 10): `GET /Table/?limit(20, 10)`\n6. **Sort Results**: Use `sort()` with `+` (asc) or `-` (desc) before the field name. Avoid `sort=field` format.\n   - Example (asc): `GET /Table/?sort(+name)`\n   - Example (desc): `GET /Table/?sort(-price)`\n   - Example (combined): `GET /Table/?sort(-price,+name)`\n7. **Query Relationships**: Use dot syntax for tables linked with `@relationship`: `GET /Book/?author.name=Harper`.\n",
 	"real-time-apps": "---\nname: real-time-apps\ndescription: How to build real-time features in Harper using WebSockets and Pub/Sub.\n---\n\n# Real-time Applications\n\nInstructions for the agent to follow when building real-time applications in Harper.\n\n## When to Use\n\nUse this skill when you need to stream live updates to clients, implement chat features, or provide real-time data synchronization between the database and a frontend.\n\n## How It Works\n\n1. **Check Automatic WebSockets**: If you only need to stream table changes, use [Automatic APIs](automatic-apis.md) which provide a WebSocket endpoint for every `@export`ed table.\n2. **Implement `connect` in a Resource**: For custom bi-directional logic, implement the `connect` method.\n3. **Use Pub/Sub**: Use `tables.TableName.subscribe(query)` to listen for specific data changes and stream them to the client.\n4. **Handle SSE**: Ensure your `connect` method gracefully handles cases where `incomingMessages` is null (Server-Sent Events).\n5. **Connect from Client**: Use standard WebSockets (`new WebSocket('wss://...')`) to connect to your resource endpoint. Ensure you use the appropriate scheme (`ws://` for HTTP, `wss://` for HTTPS).\n\n## Examples\n\n### Bi-directional WebSocket Resource\n\n```typescript\nimport { Resource, tables } from 'harper';\n\nexport class MySocket extends Resource {\n\tasync *connect(target, incomingMessages) {\n\t\t// Subscribe to table changes\n\t\tconst subscription = await tables.MyTable.subscribe(target);\n\t\tif (!incomingMessages) {\n\t\t\treturn subscription; // SSE mode\n\t\t}\n\n\t\t// Handle incoming client messages\n\t\tfor await (let message of incomingMessages) {\n\t\t\tyield { received: message };\n\t\t}\n\t}\n}\n```\n",
 	"schema-design-tooling": "---\nname: schema-design-tooling\ndescription: Best practices for Harper schema design, including core directives and GraphQL tooling configuration.\n---\n\n# Schema Design & Tooling\n\nHarper uses GraphQL schemas to define database tables, relationships, and APIs. To ensure the best development experience for both humans and AI agents, it's important to understand the core directives and configure your project tooling correctly.\n\n## Core Harper Directives\n\nHarper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harper/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:\n\n### Table Definition\n\n- `@table`: Marks a GraphQL type as a Harper database table.\n- `@export`: Automatically generates REST and WebSocket APIs for the table.\n- `@table(expiration: Int)`: Configures a time-to-expire for records in the table (useful for caching).\n\n### Attribute Constraints & Indexing\n\n- `@primaryKey`: Specifies the unique identifier for the table.\n- `@indexed`: Creates a standard index on the field for faster lookups.\n- `@indexed(type: \"HNSW\", distance: \"cosine\" | \"euclidean\" | \"dot\")`: Creates a vector index for similarity search.\n\n### Relationships\n\n- `@relationship(from: String)`: Defines a relationship to another table. `from` specifies the local field holding the foreign key.\n\n### Authentication & Authorization\n\n- `@auth(role: String)`: Restricts access to a table or field based on user roles.\n\n## Configuring GraphQL Tooling\n\nTo get the best IDE support (autocompletion, validation) and to help AI agents understand your schema context, you should create a `graphql.config.yml` file in your project root.\n\nThis file tells GraphQL tools where to find Harper's built-in types and directives alongside your own schema files.\n\n### Creating `graphql.config.yml`\n\nCreate a file named `graphql.config.yml` in your project root with the following content:\n\n```yaml\nschema:\n  - 'node_modules/harper/schema.graphql'\n  - 'schema.graphql'\n  - 'schemas/*.graphql'\n```\n\n### Why this is important:\n\n1. **Shared Directives**: It includes `@table`, `@primaryKey`, etc., so they aren't marked as \"unknown directives\".\n2. **Context for Agents**: When an agent reads your project, seeing this config helps it locate the core Harper definitions, leading to more accurate code generation.\n3. **Consistency**: The `npm create harper@latest` command includes this by default. Manually adding it to existing projects ensures they follow the same standards.\n\n## Example Project Structure\n\nA typical Harper project with proper schema tooling:\n\n```text\nmy-harper-app/\n├── config.yaml\n├── graphql.config.yml\n├── package.json\n├── schema.graphql\n└── resources.js\n```\n",
-	"serving-web-content": "---\nname: serving-web-content\ndescription: How to serve static files and integrated Vite/React applications in Harper.\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/ && dotenv -- npm run deploy:component && rm -Rf deploy\",\n   \"deploy:component\": \"(cd deploy && harper deploy_component . project=web restart=rolling replicated=true)\"\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",
+	"serving-web-content": "---\nname: serving-web-content\ndescription: How to serve static files and integrated Vite/React applications in Harper.\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.\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.\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.\n---\n\n# Vector Indexing\n\nInstructions for the agent to follow when implementing vector search in Harper.\n\n## When to Use\n\nUse this skill when you need to perform similarity searches on high-dimensional data, such as AI embeddings for semantic search, recommendations, or image retrieval.\n\n## How It Works\n\n1. **Enable Vector Indexing**: In your GraphQL schema, add `@indexed(type: \"HNSW\")` to a numeric array field:\n   ```graphql\n   type Product @table {\n   \tid: ID @primaryKey\n   \ttextEmbeddings: [Float] @indexed(type: \"HNSW\")\n   }\n   ```\n2. **Configure Index Options (Optional)**: Fine-tune the index with parameters like `distance` (`cosine` or `euclidean`), `M`, and `efConstruction`.\n3. **Query with Vector Search**: Use `tables.Table.search()` with a `sort` object containing the `target` vector:\n   ```javascript\n   const results = await tables.Product.search({\n     select: ['name', '$distance'],\n     sort: {\n       attribute: 'textEmbeddings',\n       target: [0.1, 0.2, ...], // query vector\n     },\n     limit: 5,\n   });\n   ```\n4. **Filter by Distance**: Use `conditions` with a `target` vector and a `comparator` (e.g., `lt`) to return results within a similarity threshold:\n   ```javascript\n   const results = await tables.Product.search({\n   \tconditions: {\n   \t\tattribute: 'textEmbeddings',\n   \t\tcomparator: 'lt',\n   \t\tvalue: 0.1,\n   \t\ttarget: searchVector,\n   \t},\n   });\n   ```\n5. **Generate Embeddings**: Use external services (OpenAI, Ollama) to generate the numeric vectors before storing or searching them in Harper.\n\n```typescript\nimport OpenAI from 'openai';\nimport ollama from 'ollama';\n\nconst { Product } = tables;\nconst openai = new OpenAI();\n// the name of the OpenAI embedding model\nconst OPENAI_EMBEDDING_MODEL = 'text-embedding-3-small';\n\n// the name of the Ollama embedding model\nconst OLLAMA_EMBEDDING_MODEL = 'llama3';\n\nconst SIMILARITY_THRESHOLD = 0.5;\n\nexport class ProductSearch extends Resource {\n\t// based on env variable we choose the appropriate embedding generator\n\tgenerateEmbedding =\n\t\tprocess.env.EMBEDDING_GENERATOR === 'ollama'\n\t\t\t? this._generateOllamaEmbedding\n\t\t\t: this._generateOpenAIEmbedding;\n\n\t/**\n\t * Executes a search query using a generated text embedding and returns the matching products.\n\t *\n\t * @param {Object} data - The input data for the request.\n\t * @param {string} data.prompt - The prompt to generate the text embedding from.\n\t * @return {Promise<Array>} Returns a promise that resolves to an array of products matching the conditions,\n\t * including fields: name, description, price, and $distance.\n\t */\n\tasync post(data) {\n\t\tconst embedding = await this.generateEmbedding(data.prompt);\n\n\t\treturn await Product.search({\n\t\t\tselect: ['name', 'description', 'price', '$distance'],\n\t\t\tconditions: {\n\t\t\t\tattribute: 'textEmbeddings',\n\t\t\t\tcomparator: 'lt',\n\t\t\t\tvalue: SIMILARITY_THRESHOLD,\n\t\t\t\ttarget: embedding[0],\n\t\t\t},\n\t\t\tlimit: 5,\n\t\t});\n\t}\n\n\t/**\n\t * Generates an embedding using the Ollama API.\n\t *\n\t * @param {string} promptData - The input data for which the embedding is to be generated.\n\t * @return {Promise<number[][]>} A promise that resolves to the generated embedding as an array of numbers.\n\t */\n\tasync _generateOllamaEmbedding(promptData) {\n\t\tconst embedding = await ollama.embed({\n\t\t\tmodel: OLLAMA_EMBEDDING_MODEL,\n\t\t\tinput: promptData,\n\t\t});\n\t\treturn embedding?.embeddings;\n\t}\n\n\t/**\n\t * Generates OpenAI embeddings based on the given prompt data.\n\t *\n\t * @param {string} promptData - The input data used for generating the embedding.\n\t * @return {Promise<number[][]>} A promise that resolves to an array of embeddings, where each embedding is an array of floats.\n\t */\n\tasync _generateOpenAIEmbedding(promptData) {\n\t\tconst embedding = await openai.embeddings.create({\n\t\t\tmodel: OPENAI_EMBEDDING_MODEL,\n\t\t\tinput: promptData,\n\t\t\tencoding_format: 'float',\n\t\t});\n\n\t\tlet embeddings = [];\n\t\tembedding.data.forEach((embeddingData) => {\n\t\t\tembeddings.push(embeddingData.embedding);\n\t\t});\n\n\t\treturn embeddings;\n\t}\n}\n```\n\n## Examples\n\nSample request to the `ProductSearch` resource which prompts to find \"shorts for the gym\":\n\n```bash\ncurl -X POST \"http://localhost:9926/ProductSearch/\" \\\n-H \"Accept: application/json\" \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Basic <YOUR_AUTH>\" \\\n-d '{\"prompt\": \"shorts for the gym\"}'\n```\n\n---\n\n## When to Use Vector Indexing\n\nVector indexing is ideal when:\n\n- Storing embedding vectors from ML models\n- Performing semantic or similarity-based search\n- Working with high-dimensional numeric data\n- Exact-match indexes are insufficient\n\n---\n\n## Summary\n\n- Vector indexing enables fast similarity search on numeric arrays\n- Defined using `@indexed(type: \"HNSW\")`\n- Queried using a target vector in search sorting\n- Tunable for performance and accuracy\n"

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

@@ -30,6 +30,7 @@ Use this skill when you need to perform database operations (CRUD, search, subsc
      // 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)) {
@@ -38,6 +39,94 @@ Use this skill when you need to perform database operations (CRUD, search, subsc
    ```
 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
+
+| 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
+
+Use these exact strings — incorrect comparator names will silently fail or error:
+
+| 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]`) |
+
+### Query Object Parameters
+
+| 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 attribute names to return; supports `$id` and `$updatedtime`                |
+| `sort`       | Object with `attribute`, `descending` (bool), and optional `next` for secondary sort |
+
+### Examples
+
+**Simple filter:**
+
+```javascript
+for await (const record of tables.Product.search({
+  conditions: [{ attribute: 'price', comparator: 'less_than', value: 100 }],
+  limit: 20,
+})) { ... }
+```
+
+**AND + nested OR:**
+
+```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 },
+      ],
+    },
+  ],
+})) { ... }
+```
+
+**Relationship traversal:**
+
+```javascript
+for await (const record of tables.Book.search({
+  conditions: [{ attribute: ['brand', 'name'], comparator: 'equals', value: 'Harper' }],
+})) { ... }
+```
+
+**Sort and paginate:**
+
+```javascript
+for await (const record of tables.Product.search({
+  conditions: [{ attribute: 'inStock', value: true }],
+  sort: { attribute: 'price', descending: false },
+  limit: 10,
+  offset: 20,
+})) { ... }
+```
+
 ## Cautions
 
 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.

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

@@ -59,7 +59,6 @@ Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app)
 4. **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:
    ```json
    "build": "vite build",
-   "deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && dotenv -- npm run deploy:component && rm -Rf deploy",
-   "deploy:component": "(cd deploy && harper deploy_component . project=web restart=rolling replicated=true)"
+   "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",
    ```
    Then in production, the "Static Plugin" option will performantly and securely serve your assets. `npm create harper@latest` scaffolds all of this for you.

package/package.json

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