@harperfast/skills 1.9.1 → 1.10.0

package/dist/index.js

@@ -46,7 +46,7 @@ export const rules = {
 	"querying-rest-apis": "---\nname: querying-rest-apis\ndescription: 'How to use query parameters to filter, sort, and paginate Harper REST APIs.'\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/rest/querying.md\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: 9f8c981a629ef606\n---\n\n# Querying REST APIs\n\nInstructions for the agent to filter, sort, select, and paginate Harper REST API collections using URL query parameters.\n\n## When to Use\n\nApply this rule when building or modifying code that queries Harper REST endpoints with filtering, sorting, field selection, or pagination. Use it whenever constructing URLs against collection paths exposed by Harper's automatic REST interface (see [automatic-apis.md](automatic-apis.md)).\n\n## How It Works\n\n1. **Filter by attribute**: Add query parameters matching attribute names and values. The queried attribute must be indexed.\n\n   ```\n   GET /Product/?category=software\n   GET /Product/?category=software&inStock=true\n   ```\n\n2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators directly in query parameter values.\n\n   | Operator     | Meaning                                |\n   | ------------ | -------------------------------------- |\n   | `==`         | Equal                                  |\n   | `=lt=`       | Less than                              |\n   | `=le=`       | Less than or equal                     |\n   | `=gt=`       | Greater than                           |\n   | `=ge=`       | Greater than or equal                  |\n   | `=ne=`, `!=` | Not equal                              |\n   | `=ct=`       | Contains (strings)                     |\n   | `=sw=`       | Starts with (strings)                  |\n   | `=ew=`       | Ends with (strings)                    |\n   | `=`, `===`   | Strict equality (no type conversion)   |\n   | `!==`        | Strict inequality (no type conversion) |\n\n   ```\n   GET /Product/?price=gt=100\n   GET /Product/?price=le=20\n   GET /Product/?name==Keyboard*\n   GET /Product/?category=software&price=gt=100&price=lt=200\n   ```\n\n   For date fields, URL-encode colons as `%3A`:\n\n   ```\n   GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z\n   ```\n\n3. **Chain conditions for range queries**: Omit the attribute name on the second condition to apply it to the same attribute. Only `gt`/`ge` combined with `lt`/`le` is supported.\n\n   ```\n   GET /Product/?price=gt=100&lt=200\n   ```\n\n4. **Combine conditions with OR logic**: Use `|` instead of `&`.\n\n   ```\n   GET /Product/?rating=5|featured=true\n   ```\n\n5. **Group conditions**: Use parentheses or square brackets to control order of operations. Prefer square brackets when constructing queries from user input, since standard URI encoding safely encodes `[` and `]`.\n\n   ```\n   GET /Product/?rating=5|(price=gt=100&price=lt=200)\n   GET /Product/?rating=5&[tag=fast|tag=scalable|tag=efficient]\n   ```\n\n   Construct grouped queries from JavaScript:\n\n   ```javascript\n   let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;\n   ```\n\n6. **Select specific properties with `select(`**: Use `select()` to control which fields are returned.\n\n   | Syntax                                 | Returns                                     |\n   | -------------------------------------- | ------------------------------------------- |\n   | `?select(property)`                    | Values of a single property directly        |\n   | `?select(property1,property2)`         | Objects with only the specified properties  |\n   | `?select([property1,property2])`       | Arrays of property values                   |\n   | `?select(property1,)`                  | Objects with a single specified property    |\n   | `?select(property{subProp1,subProp2})` | Nested objects with specific sub-properties |\n\n   ```\n   GET /Product/?category=software&select(name)\n   GET /Product/?brand.name=Microsoft&select(name,brand{name})\n   ```\n\n7. **Limit results with `limit(`**: Use `limit(end)` or `limit(start,end)` to paginate.\n\n   ```\n   GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)\n   GET /Product/?rating=gt=3&limit(10,30)\n   ```\n\n8. **Sort results with `sort(`**: Use `sort(property)` or `sort(+property,-property,...)`. Prefix `+` or no prefix = ascending; `-` = descending.\n\n   ```\n   GET /Product/?rating=gt=3&sort(+name)\n   GET /Product/?sort(+rating,-price)\n   ```\n\n9. **Query across relationships**: Use dot-syntax to filter by related table attributes. Relationships must be defined in the schema using `@relation`.\n\n   ```\n   GET /Product/?brand.name=Microsoft\n   GET /Brand/?products.name=Keyboard\n   ```\n\n   Use `select()` to include relationship attributes in the response (they are not included by default):\n\n   ```\n   GET /Product/?brand.name=Microsoft&select(name,brand{name})\n   ```\n\n10. **Access a specific property by URL**: Append the property name with dot syntax to the record ID. Only works for properties declared in the schema.\n    ```\n    GET /MyTable/123.propertyName\n    ```\n\n## Examples\n\n**Range filter with select and limit:**\n\n```\nGET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)&limit(20)\n```\n\n**Sort descending with multiple fields:**\n\n```\nGET /Product/?sort(+rating,-price)\n```\n\n**OR logic with grouping:**\n\n```\nGET /Product/?price=lt=100|[rating=5&[tag=fast|tag=scalable|tag=efficient]&inStock=true]\n```\n\n**Relationship join with nested select:**\n\n```\nGET /Product/?brand.name=Microsoft&select(name,brand{name,id})\n```\n\n**Schema defining a relationship for join queries:**\n\n```graphql\ntype Product @table @export {\n\tid: Long @primaryKey\n\tname: String\n\tbrandId: Long @indexed\n\tbrand: Brand @relation(from: \"brandId\")\n}\ntype Brand @table @export {\n\tid: Long @primaryKey\n\tname: String\n\tproducts: [Product] @relation(to: \"brandId\")\n}\n```\n\n**Many-to-many relationship query:**\n\n```graphql\ntype Product @table @export {\n\tid: Long @primaryKey\n\tname: String\n\tresellerIds: [Long] @indexed\n\tresellers: [Reseller] @relation(from: \"resellerId\")\n}\n```\n\n```\nGET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})\n```\n\n**Type conversion with explicit prefix:**\n\n```\nGET /Product/?price==number:123\nGET /Product/?active==boolean:true\nGET /Product/?listDate==date:2024-01-05T20%3A07%3A27.955Z\n```\n\n## Notes\n\n- Only indexed attributes can be used as the primary filter; additional unindexed attributes can be combined with `&` once at least one indexed attribute is present.\n- For null value queries, use `?attribute=null`. Indexes must have been created with null indexing support; existing indexes must be removed and re-added to support null queries.\n- FIQL comparators (`==`, `!=`, `=gt=`, etc.) apply automatic type conversion based on value syntax or schema-declared type. Strict operators (`=`, `===`, `!==`) skip automatic type conversion.\n- Filtering by a related attribute produces INNER JOIN behavior (only records with a matching related record are returned). Using `select()` on a relationship without a filter produces LEFT JOIN behavior.\n- The array order of foreign key values in many-to-many relationships is preserved when resolving the relationship.\n- See [automatic-apis.md](automatic-apis.md) for how Harper tables are automatically exposed as REST endpoints.\n",
 	"real-time-apps": "---\nname: real-time-apps\ndescription: How to build real-time features in Harper using WebSockets and Pub/Sub.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/rest/websockets.md\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: a8afd4d3a52f77ba\n---\n\n# Real-Time Apps with WebSockets and Pub/Sub\n\nInstructions for the agent to follow when building real-time features in Harper using WebSockets and Pub/Sub.\n\n## When to Use\n\nApply this rule when implementing any feature that requires real-time bidirectional communication, live data streaming, or push-based updates in a Harper application. This includes chat, live dashboards, sensor feeds, and any scenario where clients must receive resource changes as they happen.\n\n## How It Works\n\n1. **Enable WebSocket support**: WebSocket support is enabled automatically when the `rest` plugin is enabled. To explicitly disable it, set the following in your config:\n\n   ```yaml\n   rest:\n     webSocket: false\n   ```\n\n2. **Connect a client to a resource**: A WebSocket connection to a resource URL automatically subscribes to that resource. When the record changes or a message is published to it, the connection receives the update.\n\n   ```javascript\n   let ws = new WebSocket('wss://server/my-resource/341');\n   ws.onmessage = (event) => {\n   \tlet data = JSON.parse(event.data);\n   };\n   ```\n\n   `new WebSocket('wss://server/my-resource/341')` accesses the resource defined for `my-resource` with record id `341` and subscribes to it.\n\n3. **Implement a custom `connect()` handler**: Override the `connect(incomingMessages)` method on a resource class to control WebSocket behavior. The method must return an async iterable (or generator) that produces messages to send to the client. See [automatic-apis.md](automatic-apis.md) for more on defining resource classes.\n\n4. **Use the default `connect()` for event-style access**: Call `super.connect()` to get a streaming iterable that provides:\n   - A `send(message)` method for pushing outgoing messages\n   - A `close` event for cleanup on disconnect\n\n5. **Handle message ordering in distributed environments**: Harper delivers messages to local subscribers immediately without inter-node coordination delay.\n\n   | Message Type                                             | Behavior                                                                |\n   | -------------------------------------------------------- | ----------------------------------------------------------------------- |\n   | Non-retained (no `retain` flag)                          | Every message delivered in order received; suitable for chat            |\n   | Retained (published with `retain`, or PUT/updated in DB) | Only the latest-timestamp message is kept; suitable for sensor readings |\n\n6. **Use MQTT over WebSockets** when needed by setting the sub-protocol header:\n   ```\n   Sec-WebSocket-Protocol: mqtt\n   ```\n\n## Examples\n\n**Simple echo server** — override `connect(incomingMessages)` to yield each incoming message back to the client:\n\n```javascript\nexport class Echo extends Resource {\n\tasync *connect(incomingMessages) {\n\t\tfor await (let message of incomingMessages) {\n\t\t\tyield message; // echo each message back\n\t\t}\n\t}\n}\n```\n\n**Custom connect with timer and event-style access** — use `super.connect()` to get the outgoing stream, push periodic messages, echo incoming messages, and clean up on disconnect:\n\n```javascript\nexport class Example extends Resource {\n\tconnect(incomingMessages) {\n\t\tlet outgoingMessages = super.connect();\n\n\t\tlet timer = setInterval(() => {\n\t\t\toutgoingMessages.send({ greeting: 'hi again!' });\n\t\t}, 1000);\n\n\t\tincomingMessages.on('data', (message) => {\n\t\t\toutgoingMessages.send(message); // echo incoming messages\n\t\t});\n\n\t\toutgoingMessages.on('close', () => {\n\t\t\tclearInterval(timer);\n\t\t});\n\n\t\treturn outgoingMessages;\n\t}\n}\n```\n\n## Notes\n\n- WebSocket connections target a resource URL path. By default, connecting to a resource subscribes to changes for that resource.\n- The `connect(incomingMessages)` method **must** return an async iterable or generator; returning a plain value will not work.\n- `super.connect()` returns a streaming iterable with `send(message)` and a `close` event — use this when you need to push messages outside of the incoming message loop.\n- For one-way real-time streaming without bidirectional communication, consider Server-Sent Events instead.\n- For full pub/sub capabilities, Harper also supports MQTT; set `Sec-WebSocket-Protocol: mqtt` to use MQTT over WebSockets.\n",
 	"schema-design-tooling": "---\nname: schema-design-tooling\ndescription: >-\n  Best practices for Harper schema design, including core directives and GraphQL\n  tooling configuration.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/database/schema.md#Overview\n    - reference/v5/database/schema.md#Type Directives\n    - reference/v5/database/schema.md#Field Directives\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: 4faa3baed7cfa854\n---\n\n# Schema Design and Tooling\n\nInstructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.\n\n## When to Use\n\nApply this rule when creating or modifying Harper schema files, configuring `graphqlSchema` in `config.yaml`, or deciding which directives to apply to tables and fields. Use it any time a component needs tables, indexes, primary keys, or exported endpoints defined.\n\n## How It Works\n\n1. **Create a GraphQL schema file** with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.\n\n   ```graphql\n   type Dog @table {\n   \tid: Long @primaryKey\n   \tname: String\n   \tbreed: String\n   \tage: Int\n   }\n\n   type Breed @table {\n   \tid: Long @primaryKey\n   \tname: String @indexed\n   }\n   ```\n\n2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin key:\n\n   ```yaml\n   graphqlSchema:\n     files: 'schema.graphql'\n   ```\n\n   Both plugins and applications can specify schemas this way.\n\n3. **Mark every table type with `@table`**. The type name becomes the table name by default. Use optional arguments to override behavior:\n\n   | Argument       | Type      | Default                       | Description                                                   |\n   | -------------- | --------- | ----------------------------- | ------------------------------------------------------------- |\n   | `table`        | `String`  | type name                     | Override the table name                                       |\n   | `database`     | `String`  | `\"data\"`                      | Database to place the table in                                |\n   | `expiration`   | `Int`     | —                             | Seconds until a record goes stale                             |\n   | `eviction`     | `Int`     | `0`                           | Additional seconds after `expiration` before physical removal |\n   | `scanInterval` | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                |\n   | `replicate`    | `Boolean` | `true`                        | Enable replication of this table                              |\n\n4. **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:\n   - `String` or `ID` → UUID string\n   - `Int`, `Long`, or `Any` → auto-incrementing integer\n\n   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.\n\n5. **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.\n\n   ```graphql\n   type Product @table {\n   \tid: Long @primaryKey\n   \tcategory: String @indexed\n   \tprice: Float @indexed\n   }\n   ```\n\n6. **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.\n\n   ```graphql\n   type MyTable @table @export(name: \"my-table\") {\n   \tid: Long @primaryKey\n   }\n   ```\n\n7. **Restrict extra properties** with `@sealed` when records must not include attributes beyond those declared. By default, Harper allows additional properties.\n\n   ```graphql\n   type StrictRecord @table @sealed {\n   \tid: Long @primaryKey\n   \tname: String\n   }\n   ```\n\n8. **Configure expiration, eviction, and scan behavior** together when building caching tables. These three arguments control the full record lifecycle:\n   - `expiration` — record becomes stale; next request triggers a source fetch\n   - `eviction` — additional time after `expiration` before physical removal\n   - `scanInterval` — how often Harper scans for records to evict; clock-aligned, not startup-aligned\n\n## Examples\n\n**Caching table with tuned expiration:**\n\n```graphql\n# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes\ntype WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {\n\tid: ID @primaryKey\n\ttemperature: Float\n}\n```\n\n**Table in a named database with expiration and an indexed field:**\n\n```graphql\ntype Event @table(database: \"analytics\", expiration: 86400) {\n\tid: Long @primaryKey\n\tname: String @indexed\n}\n```\n\n**Session cache with auto-expiry:**\n\n```graphql\ntype Session @table(expiration: 3600) {\n\tid: Long @primaryKey\n\tuserId: String\n}\n```\n\n**Table with audit timestamps:**\n\n```graphql\ntype Order @table @export(name: \"orders\") {\n\tid: Long @primaryKey\n\tcreatedAt: Long @createdTime\n\tupdatedAt: Long @updatedTime\n\tstatus: String @indexed\n}\n```\n\n**Overriding the table name and disabling replication:**\n\n```graphql\ntype Product @table(table: \"products\") {\n\tid: Long @primaryKey\n\tname: String\n}\n\ntype LocalRecord @table(replicate: false) {\n\tid: Long @primaryKey\n\tvalue: String\n}\n```\n\n## Notes\n\n- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `\"data\"` database.\n- 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.\n- `scanInterval` is clock-aligned to the server's local timezone. The server's startup time does not affect when eviction runs.\n- If replication is disabled on a table and later re-enabled, it will not catch up on writes made while replication was disabled.\n- Null values are indexed by `@indexed` fields, enabling queries such as `GET /Product/?category=null`.\n",
-	"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",
+	"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/Vue app) directly from your Harper instance — either plain static files or an integrated Vite app with hot module replacement (HMR) in development and a real production build when deployed.\n\n## How It Works\n\nThere are two building blocks. Harper's built-in `static` plugin **serves** files; the `@harperfast/vite` plugin **builds** (and, for SSR, **renders**) a Vite app. For a Vite app they work **together** — the plugin builds into a directory and `static` serves that same directory.\n\n### Option A: Static plugin only (simple, pre-built assets)\n\nFor a plain static site or already-built assets, use `static` on its own:\n\n```yaml\nstatic:\n  files: 'web/*'\n```\n\n- Place files in a `web/` folder in the project root; they are served from the root URL (e.g. `http://localhost:9926/index.html`).\n- Static files are matched first; if none matches, Harper falls through to your resource and table APIs.\n\n### Option B: Vite plugin + static plugin (integrated Vite app)\n\n> **Renamed in v1:** the plugin was previously `@harperfast/vite-plugin`. From `1.0.0` on it is **`@harperfast/vite`** (same key and `package`). It now pairs with the `static` plugin instead of building into `web/` itself.\n\n`@harperfast/vite` **builds** your app — in `harper dev` it runs Vite in middleware mode with HMR; in `harper run` it runs `vite build` and rebuilds when watched files change (and renders HTML for SSR). The `static` plugin **serves** the built output. Point both at the same directory (`output`, default `dist`) — that shared directory is the only contract between them.\n\n**SPA `config.yaml`** — list the plugin first so its dev server wins in `harper dev`; `notFound` + `fallthrough: false` makes client-side routing work:\n\n```yaml\n'@harperfast/vite':\n  package: '@harperfast/vite'\n  files: 'src/**/*'\n  output: 'dist'\n\nstatic:\n  files: 'dist/**'\n  notFound:\n    file: 'index.html'\n    statusCode: 200\n  fallthrough: false\n```\n\n**SSR `config.yaml`** — add an `ssr` entry so the plugin renders `index.html`, and set `index: false` on `static` so it serves assets only:\n\n```yaml\n'@harperfast/vite':\n  package: '@harperfast/vite'\n  files: 'src/**/*'\n  output: 'dist'\n  ssr: 'src/entry-server.tsx'\n\nstatic:\n  files: 'dist/**'\n  index: false\n```\n\n- Install dependencies: `npm install --save-dev vite @harperfast/vite @vitejs/plugin-react` (swap in your framework's Vite plugin, e.g. `@vitejs/plugin-vue`).\n- Then `harper dev .` runs the app with HMR and `harper run .` runs the production build. Vite does _not_ need to be executed separately.\n\n## Deploying to Production\n\nBecause `@harperfast/vite` builds on the node and `static` serves the output, deploy the component as-is — no manual build-and-move step is needed:\n\n```json\n{\n\t\"scripts\": {\n\t\t\"dev\": \"harper dev .\",\n\t\t\"start\": \"harper run .\",\n\t\t\"deploy\": \"harper deploy_component . restart=true replicated=true\"\n\t}\n}\n```\n\nOn deploy the plugin runs `vite build` at startup (and rebuilds when `files` change) while `static` serves the result. If you prefer to build in CI, commit the build output, point `static` at it, and omit `files` so the plugin stays idle while `static` serves the prebuilt assets. Either way, `npm create harper@latest` scaffolds a working setup 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: generate\n  sources:\n    - reference/v5/components/javascript-environment.md#TypeScript Support\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: 4e6bd8b610edd595\n---\n\n# TypeScript Type Stripping in Harper\n\nInstructions for the agent to run `.ts` files directly in Harper without a build step using Node.js's built-in type stripping.\n\n## When to Use\n\nApply this rule when writing Harper resource files in TypeScript. Use it any time you need to reference `.ts` source files from `config.yaml` or import between local TypeScript modules in a Harper project.\n\n## How It Works\n\n1. **Ensure Node.js version**: Require Node.js 22.6 or later. Type stripping is unavailable on earlier versions.\n\n2. **Point `jsResource` at `.ts` files**: The `jsResource` plugin loads both `.js` and `.ts` files. Set its `files` glob in `config.yaml` to target your `.ts` source files:\n\n   ```yaml\n   jsResource:\n     files: 'resources/*.ts'\n   ```\n\n3. **Use explicit `.ts` extensions in local imports**: Node's loader does not resolve `'./helper'` to `'./helper.ts'`, so always include the full extension:\n\n   ```typescript\n   import { helper } from './helper.ts';\n   ```\n\n4. **Stay within type-stripping limits**: Only type annotations and declarations are removed. Do not use enums with runtime values, namespaces with runtime semantics, or any other features that require code transformation beyond type stripping.\n\n## Examples\n\nA complete Harper resource written in TypeScript, using imports from the `harper` package:\n\n```typescript\nimport { type RequestTargetOrId, Resource, tables } from 'harper';\n\nexport class MyResource extends Resource {\n\tasync get(target?: RequestTargetOrId): Promise<{ message: string }> {\n\t\treturn { message: 'Hello from TS' };\n\t}\n}\n```\n\nPaired `config.yaml` entry loading the file via `jsResource`:\n\n```yaml\njsResource:\n  files: 'resources/*.ts'\n```\n\n## Notes\n\n- No build step or transpiler is required — Harper runs `.ts` files directly.\n- Type imports (e.g., `import { type RequestTargetOrId }`) from the `harper` package work as usual.\n- Unsupported TypeScript features include: enums with runtime values, namespaces with runtime semantics, and anything requiring code transformation beyond simple type stripping.\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: b7fbddadd42eb4487190b650a9abc4bcfeef5819\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 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.\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 containing `attribute` (the indexed field name) 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 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**: To return only records within a similarity cutoff (without ranking), place `target` directly on the condition alongside `comparator` and `value`. Omit `sort`.\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**: Use the special `$distance` field in `select` to return the distance from the target vector. Works with 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 score:**\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`. Pass `distance: \"euclidean\"` to switch.\n- `efConstruction` controls index build quality; raising it improves recall at the cost of build time.\n- `$distance` is available in both `sort`-based ranking and `conditions`-based threshold queries.\n- Use the threshold (`conditions` + `target`) form when you want to bound result quality by a similarity cutoff rather than ranking by similarity.\n"

package/harper-best-practices/AGENTS.md

@@ -1617,59 +1617,78 @@ Instructions for the agent to follow when serving web content from Harper.
 
 #### When to Use
 
-Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) directly from your Harper instance.
+Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React/Vue app) directly from your Harper instance — either plain static files or an integrated Vite app with hot module replacement (HMR) in development and a real production build when deployed.
 
 #### How It Works
 
-1. **Choose a Method**: Decide between the simple Static Plugin or the integrated Vite Plugin.
-2. **Option A: Static Plugin (Simple)**:
-   - Add to `config.yaml`:
-     ```yaml
-     static:
-       files: 'web/*'
-     ```
-   - Place files in a `web/` folder in the project root.
-   - Files are served at the root URL (e.g., `http://localhost:9926/index.html`).
-3. **Option B: Vite Plugin (Advanced/Development)**:
-   - Add to `config.yaml`:
-     ```yaml
-     '@harperfast/vite-plugin':
-       package: '@harperfast/vite-plugin'
-     ```
-   - Ensure `vite.config.ts` and `index.html` are in the project root.
+There are two building blocks. Harper's built-in `static` plugin **serves** files; the `@harperfast/vite` plugin **builds** (and, for SSR, **renders**) a Vite app. For a Vite app they work **together** — the plugin builds into a directory and `static` serves that same directory.
 
-   ```javascript
-   import vue from '@vitejs/plugin-vue';
-   import path from 'node:path';
-   import { defineConfig } from 'vite';
-
-   // https://vite.dev/config/
-   export default defineConfig({
-   	plugins: [vue()],
-   	resolve: {
-   		alias: {
-   			'@': path.resolve(import.meta.dirname, './src'),
-   		},
-   	},
-   	build: {
-   		outDir: 'web',
-   		emptyOutDir: true,
-   		rolldownOptions: {
-   			external: ['**/*.test.*', '**/*.spec.*'],
-   		},
-   	},
-   });
-   ```
+##### Option A: Static plugin only (simple, pre-built assets)
 
-   - Install dependencies: `npm install --save-dev vite @harperfast/vite-plugin`.
-   - Then `harper run .` will start up Harper and Vite with HMR. Vite does _not_ need to be executed separately.
+For a plain static site or already-built assets, use `static` on its own:
 
-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/ && (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.
+```yaml
+static:
+  files: 'web/*'
+```
+
+- Place files in a `web/` folder in the project root; they are served from the root URL (e.g. `http://localhost:9926/index.html`).
+- Static files are matched first; if none matches, Harper falls through to your resource and table APIs.
+
+##### Option B: Vite plugin + static plugin (integrated Vite app)
+
+> **Renamed in v1:** the plugin was previously `@harperfast/vite-plugin`. From `1.0.0` on it is **`@harperfast/vite`** (same key and `package`). It now pairs with the `static` plugin instead of building into `web/` itself.
+
+`@harperfast/vite` **builds** your app — in `harper dev` it runs Vite in middleware mode with HMR; in `harper run` it runs `vite build` and rebuilds when watched files change (and renders HTML for SSR). The `static` plugin **serves** the built output. Point both at the same directory (`output`, default `dist`) — that shared directory is the only contract between them.
+
+**SPA `config.yaml`** — list the plugin first so its dev server wins in `harper dev`; `notFound` + `fallthrough: false` makes client-side routing work:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+
+static:
+  files: 'dist/**'
+  notFound:
+    file: 'index.html'
+    statusCode: 200
+  fallthrough: false
+```
+
+**SSR `config.yaml`** — add an `ssr` entry so the plugin renders `index.html`, and set `index: false` on `static` so it serves assets only:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+  ssr: 'src/entry-server.tsx'
+
+static:
+  files: 'dist/**'
+  index: false
+```
+
+- 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.
+
+#### 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:
+
+```json
+{
+	"scripts": {
+		"dev": "harper dev .",
+		"start": "harper run .",
+		"deploy": "harper deploy_component . restart=true replicated=true"
+	}
+}
+```
+
+On deploy the plugin runs `vite build` at startup (and rebuilds when `files` change) while `static` serves the result. If you prefer to build in CI, commit the build output, point `static` at it, and omit `files` so the plugin stays idle while `static` serves the prebuilt assets. Either way, `npm create harper@latest` scaffolds a working setup for you.
 
 ### 4.5 Harper Logging
 

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

@@ -11,56 +11,75 @@ Instructions for the agent to follow when serving web content from Harper.
 
 ## When to Use
 
-Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) directly from your Harper instance.
+Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React/Vue app) directly from your Harper instance — either plain static files or an integrated Vite app with hot module replacement (HMR) in development and a real production build when deployed.
 
 ## How It Works
 
-1. **Choose a Method**: Decide between the simple Static Plugin or the integrated Vite Plugin.
-2. **Option A: Static Plugin (Simple)**:
-   - Add to `config.yaml`:
-     ```yaml
-     static:
-       files: 'web/*'
-     ```
-   - Place files in a `web/` folder in the project root.
-   - Files are served at the root URL (e.g., `http://localhost:9926/index.html`).
-3. **Option B: Vite Plugin (Advanced/Development)**:
-   - Add to `config.yaml`:
-     ```yaml
-     '@harperfast/vite-plugin':
-       package: '@harperfast/vite-plugin'
-     ```
-   - Ensure `vite.config.ts` and `index.html` are in the project root.
-
-   ```javascript
-   import vue from '@vitejs/plugin-vue';
-   import path from 'node:path';
-   import { defineConfig } from 'vite';
-
-   // https://vite.dev/config/
-   export default defineConfig({
-   	plugins: [vue()],
-   	resolve: {
-   		alias: {
-   			'@': path.resolve(import.meta.dirname, './src'),
-   		},
-   	},
-   	build: {
-   		outDir: 'web',
-   		emptyOutDir: true,
-   		rolldownOptions: {
-   			external: ['**/*.test.*', '**/*.spec.*'],
-   		},
-   	},
-   });
-   ```
-
-   - Install dependencies: `npm install --save-dev vite @harperfast/vite-plugin`.
-   - Then `harper run .` will start up Harper and Vite with HMR. Vite does _not_ need to be executed separately.
-
-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/ && (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.
+There are two building blocks. Harper's built-in `static` plugin **serves** files; the `@harperfast/vite` plugin **builds** (and, for SSR, **renders**) a Vite app. For a Vite app they work **together** — the plugin builds into a directory and `static` serves that same directory.
+
+### Option A: Static plugin only (simple, pre-built assets)
+
+For a plain static site or already-built assets, use `static` on its own:
+
+```yaml
+static:
+  files: 'web/*'
+```
+
+- Place files in a `web/` folder in the project root; they are served from the root URL (e.g. `http://localhost:9926/index.html`).
+- Static files are matched first; if none matches, Harper falls through to your resource and table APIs.
+
+### Option B: Vite plugin + static plugin (integrated Vite app)
+
+> **Renamed in v1:** the plugin was previously `@harperfast/vite-plugin`. From `1.0.0` on it is **`@harperfast/vite`** (same key and `package`). It now pairs with the `static` plugin instead of building into `web/` itself.
+
+`@harperfast/vite` **builds** your app — in `harper dev` it runs Vite in middleware mode with HMR; in `harper run` it runs `vite build` and rebuilds when watched files change (and renders HTML for SSR). The `static` plugin **serves** the built output. Point both at the same directory (`output`, default `dist`) — that shared directory is the only contract between them.
+
+**SPA `config.yaml`** — list the plugin first so its dev server wins in `harper dev`; `notFound` + `fallthrough: false` makes client-side routing work:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+
+static:
+  files: 'dist/**'
+  notFound:
+    file: 'index.html'
+    statusCode: 200
+  fallthrough: false
+```
+
+**SSR `config.yaml`** — add an `ssr` entry so the plugin renders `index.html`, and set `index: false` on `static` so it serves assets only:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+  ssr: 'src/entry-server.tsx'
+
+static:
+  files: 'dist/**'
+  index: false
+```
+
+- 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.
+
+## 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:
+
+```json
+{
+	"scripts": {
+		"dev": "harper dev .",
+		"start": "harper run .",
+		"deploy": "harper deploy_component . restart=true replicated=true"
+	}
+}
+```
+
+On deploy the plugin runs `vite build` at startup (and rebuilds when `files` change) while `static` serves the result. If you prefer to build in CI, commit the build output, point `static` at it, and omit `files` so the plugin stays idle while `static` serves the prebuilt assets. Either way, `npm create harper@latest` scaffolds a working setup for you.

package/package.json

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