@harperfast/skills 1.8.0 → 1.9.1

package/dist/index.js

@@ -40,7 +40,7 @@ export const rules = {
 	"deploying-to-harper-fabric": "---\nname: deploying-to-harper-fabric\ndescription: How to deploy a Harper application to the Harper Fabric cloud.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/components/applications.md#Remote Management\n    - >-\n      fabric/cluster-creation-management.md#Connecting the Harper CLI to a\n      Cluster\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: ccdefbbf8f3b8657\n---\n\n# Deploying to Harper Fabric\n\nInstructions for the agent to follow when deploying a Harper application to the Harper Fabric cloud using the Harper CLI.\n\n## When to Use\n\nApply this rule when deploying a Harper application to a remote Harper instance or Harper Fabric cluster. This covers interactive deployments, CI/CD pipelines, and any scenario where the agent must push a local or remote package to a target environment.\n\n## How It Works\n\n1. **Authenticate with the remote target**: Run `harper login` once to store an authentication token. The CLI writes `HARPER_CLI_TARGET` to a local `.env` so subsequent commands do not need credentials repeated. Find the **Application URL** on the cluster's **Config → Overview** page (see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md)).\n\n   ```bash\n   harper login <Application URL>\n   # Provide cluster username and password when prompted\n   ```\n\n2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials are needed inline.\n\n   ```bash\n   harper deploy \\\n     project=<name> \\\n     package=<package> \\\n     target=<remote> \\\n     restart=true \\\n     replicated=true\n   ```\n\n3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and deploy the current local directory.\n\n   | Value                                                | Effect                                           |\n   | ---------------------------------------------------- | ------------------------------------------------ |\n   | _(omitted)_                                          | Packages and deploys the current local directory |\n   | `\"@harperdb/status-check\"`                           | npm package                                      |\n   | `\"HarperDB/status-check\"`                            | GitHub repo (short form)                         |\n   | `\"https://github.com/HarperDB/status-check\"`         | GitHub repo (full URL)                           |\n   | `\"git+ssh://git@github.com:HarperDB/secret-app.git\"` | Private repo via SSH                             |\n   | `\"https://example.com/application.tar.gz\"`           | Remote tarball                                   |\n\n   For git tags, use the `semver` directive for reliable versioning:\n\n   ```\n   HarperDB/application-template#semver:v1.0.0\n   ```\n\n4. **Authenticate for CI/CD pipelines**: Use environment variables instead of interactive login. Set credentials before running `harper deploy`.\n\n   ```bash\n   export HARPER_CLI_USERNAME=<username>\n   export HARPER_CLI_PASSWORD=<password>\n   harper deploy \\\n     project=<name> \\\n     package=<package> \\\n     target=<remote> \\\n     restart=true \\\n     replicated=true\n   ```\n\n5. **Register SSH keys for private repos**: Before deploying from an SSH-based private repository, use the Add SSH Key operation to register the key with the remote instance.\n\n## Examples\n\n**Interactive login then deploy (recommended):**\n\n```bash\n# Log in once\nharper login <remote>\n# Provide your username and password when prompted\n\n# Subsequently deploy without credentials\nharper deploy \\\n  project=<name> \\\n  package=<package> \\\n  target=<remote> \\\n  restart=true \\\n  replicated=true\n```\n\n**Deploy with inline credentials (not recommended for production):**\n\n```bash\nharper deploy \\\n  project=<name> \\\n  package=<package> \\\n  username=<username> \\\n  password=<password> \\\n  target=<remote> \\\n  restart=true \\\n  replicated=true\n```\n\n**Deploy a specific GitHub release by semver tag:**\n\n```bash\nharper deploy \\\n  project=my-app \\\n  package=\"HarperDB/application-template#semver:v1.0.0\" \\\n  target=<remote> \\\n  restart=true \\\n  replicated=true\n```\n\n## Notes\n\n- Always prefer `harper login` for interactive use and environment variables (`HARPER_CLI_USERNAME`, `HARPER_CLI_PASSWORD`) for CI/CD. Avoid inline `username`/`password` parameters in production.\n- Omitting `package` causes the CLI to package the current local directory. Specifying a local file path creates a symlink, so changes are picked up between restarts without redeploying.\n- Harper generates a `package.json` from component configurations and resolves dependencies using a form of `npm install`.\n- For SSH-based private repos, register keys with the Add SSH Key operation before deploying.\n",
 	"extending-tables": "---\nname: extending-tables\ndescription: How to add custom logic to automatically generated table resources in Harper.\nmetadata:\n  mode: synthesized\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.\nmetadata:\n  mode: synthesized\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",
-	"load-env": "---\nname: load-env\ndescription: >-\n  How to load environment variables from .env files into a Harper application\n  using the loadEnv plugin.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/environment-variables/overview.md\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: c73a0caf28a2b833\n---\n\n# Load Environment Variables with loadEnv\n\nInstructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.\n\n## When to Use\n\nApply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever you need to configure `loadEnv` in `config.yaml`, control load order, handle multiple files, or manage override behavior.\n\n## How It Works\n\n1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` to your `config.yaml` with a `files` key pointing to the `.env` file. `loadEnv` is built into Harper and does not need to be installed separately.\n\n   ```yaml\n   loadEnv:\n     files: '.env'\n   ```\n\n   This loads the specified file from the root of your component directory into `process.env`.\n\n2. **Place `loadEnv` first**: Always declare `loadEnv` before any other components in `config.yaml` so environment variables are available before dependent components start. Because Harper is single-process, variables loaded onto `process.env` are shared across all components.\n\n   ```yaml\n   # config.yaml — loadEnv must come first\n   loadEnv:\n     files: '.env'\n\n   rest: true\n\n   myApp:\n     files: './src/*.js'\n   ```\n\n3. **Control override behavior**: By default, existing shell or container environment variables take precedence over values in `.env` files. To force `.env` values to overwrite existing variables, set `override: true`.\n\n   ```yaml\n   loadEnv:\n     files: '.env'\n     override: true\n   ```\n\n4. **Load multiple files**: Provide a list of files or a glob pattern under `files`. Files are loaded in the order specified.\n   ```yaml\n   loadEnv:\n     files:\n       - '.env'\n       - '.env.local'\n   ```\n   Or using a glob pattern:\n   ```yaml\n   loadEnv:\n     files: 'env-vars/*'\n   ```\n\n## Examples\n\nA complete `config.yaml` using `loadEnv` with multiple files and override enabled:\n\n```yaml\n# config.yaml — loadEnv must come first\nloadEnv:\n  files:\n    - '.env'\n    - '.env.local'\n  override: true\n\nrest: true\n\nmyApp:\n  files: './src/*.js'\n```\n\nA minimal setup loading a single `.env` file:\n\n```yaml\nloadEnv:\n  files: '.env'\n\nmyApp:\n  files: './src/*.js'\n```\n\n## Notes\n\n- `loadEnv` is built into Harper — declare it in `config.yaml` only; do not install it as a separate package.\n- The `files` value accepts either a single string, a list of strings, or a glob pattern.\n- Without `override: true`, variables already present in the environment are never overwritten by values in `.env` files.\n- `process.env` is shared across all Harper components in the same process, so load order in `config.yaml` determines availability.\n",
+	"load-env": "---\nname: load-env\ndescription: >-\n  How to load environment variables from .env files into a Harper application\n  using the loadEnv plugin.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/environment-variables/overview.md\n  sourceCommit: 42231db17c025a4a455e3d91875fad4084a01cb5\n  inputHash: fe610fc245226357\n---\n\n# Load Environment Variables with loadEnv\n\nInstructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.\n\n## When to Use\n\nApply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever hardcoding values must be avoided and environment-specific configuration must be supplied to Harper components.\n\n## How It Works\n\n1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as a top-level key. It is built into Harper and requires no installation.\n\n   ```yaml\n   loadEnv:\n     files: '.env'\n   ```\n\n2. **Place `loadEnv` first**: Always list `loadEnv` before any other components in `config.yaml` so that environment variables are available on `process.env` before dependent components start.\n\n   ```yaml\n   # config.yaml — loadEnv must come first\n   loadEnv:\n     files: '.env'\n\n   rest: true\n\n   myApp:\n     files: './src/*.js'\n   ```\n\n3. **Configure the `files` option**: Provide one or more paths or glob patterns pointing to the env files to load. This option is required.\n\n4. **Set `override` if needed**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this and have loaded values win.\n\n   ```yaml\n   loadEnv:\n     files: '.env'\n     override: true\n   ```\n\n5. **Load multiple files when required**: Supply a list of files or a glob pattern. Files are loaded in the order specified.\n   ```yaml\n   loadEnv:\n     files:\n       - '.env'\n       - '.env.local'\n   ```\n   or\n   ```yaml\n   loadEnv:\n     files: 'env-vars/*'\n   ```\n\n### Configuration Options\n\n| Option     | Type                 | Required | Description                                                                            |\n| ---------- | -------------------- | -------- | -------------------------------------------------------------------------------------- |\n| `files`    | `string \\| string[]` | **Yes**  | Path(s) or glob pattern(s) to the env file(s) to load.                                 |\n| `override` | `boolean`            | No       | If `true`, loaded values override existing environment variables. Defaults to `false`. |\n\n## Examples\n\n**Minimal setup — single `.env` file:**\n\n```yaml\nloadEnv:\n  files: '.env'\n```\n\n**Full `config.yaml` with load order, multiple files, and override:**\n\n```yaml\n# config.yaml — loadEnv must come first\nloadEnv:\n  files:\n    - '.env'\n    - '.env.local'\n  override: true\n\nrest: true\n\nmyApp:\n  files: './src/*.js'\n```\n\n**Glob pattern:**\n\n```yaml\nloadEnv:\n  files: 'env-vars/*'\n```\n\n## Notes\n\n- `loadEnv` is built into Harper — do not install it separately; only declare it in `config.yaml`.\n- Because Harper is a single-process application, variables loaded onto `process.env` are shared across all components.\n- Without `override: true`, variables already set in the shell or container environment will not be overwritten by values in `.env` files.\n- `files` is the only required option; omitting it will produce an invalid configuration.\n",
 	"logging": "---\nname: logging\ndescription: >-\n  Best practices for logging in Harper, including console capture, the granular\n  logger interface, and programmatic log retrieval.\nmetadata:\n  mode: generate\n  sources:\n    - reference/v5/logging/overview.md\n    - reference/v5/logging/api.md\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: 46cd384598304e3b\n---\n\n# Harper Logging\n\nInstructions for the agent to follow when implementing logging in Harper applications, including direct logger usage, tagged loggers, and console capture behavior.\n\n## When to Use\n\nApply this rule when writing any JavaScript component, plugin, or resource that needs to emit structured log entries, filter logs by component, or capture existing `console.log` output into Harper's log system. Use it whenever you need to understand log levels, log entry format, or the `logger` global API.\n\n## How It Works\n\n1. **Use the `logger` global directly** — `logger` is available in all JavaScript components without any imports. Call the method matching the desired severity level:\n\n   ```javascript\n   logger.trace('detailed trace message');\n   logger.debug('debug info', { someContext: 'value' });\n   logger.info('informational message');\n   logger.warn('potential issue');\n   logger.error('error occurred', error);\n   logger.fatal('fatal error');\n   logger.notify('server is ready');\n   ```\n\n   Only entries at or above the configured `logging.level` (or `logging.external.level`) are written to `hdb.log`.\n\n2. **Create a tagged logger with `withTag(`** — Call `logger.withTag(tag)` once per module or class to get a `TaggedLogger` scoped to that tag. This prefixes every log entry with the tag, making log output filterable by component.\n\n   ```javascript\n   const log = logger.withTag('my-resource');\n   ```\n\n   Because `TaggedLogger` methods for disabled levels are `null`, always use optional chaining (`?.`) when calling them:\n\n   ```javascript\n   log.debug?.('Fetching record', { id });\n   log.warn?.('Record not found', { id });\n   log.error?.('Failed to update record', err);\n   ```\n\n   `TaggedLogger` does not have a `withTag()` method.\n\n3. **Understand the interface contracts** — `MainLogger` always has all methods defined:\n\n   ```typescript\n   interface MainLogger {\n   \ttrace(...messages: any[]): void;\n   \tdebug(...messages: any[]): void;\n   \tinfo(...messages: any[]): void;\n   \twarn(...messages: any[]): void;\n   \terror(...messages: any[]): void;\n   \tfatal(...messages: any[]): void;\n   \tnotify(...messages: any[]): void;\n   \twithTag(tag: string): TaggedLogger;\n   }\n   ```\n\n   `TaggedLogger` methods may be `null`:\n\n   ```typescript\n   interface TaggedLogger {\n   \ttrace: ((...messages: any[]) => void) | null;\n   \tdebug: ((...messages: any[]) => void) | null;\n   \tinfo: ((...messages: any[]) => void) | null;\n   \twarn: ((...messages: any[]) => void) | null;\n   \terror: ((...messages: any[]) => void) | null;\n   \tfatal: ((...messages: any[]) => void) | null;\n   \tnotify: ((...messages: any[]) => void) | null;\n   }\n   ```\n\n4. **Know the log levels** — From least to most severe:\n\n   | Level    | Description                                                          |\n   | -------- | -------------------------------------------------------------------- |\n   | `trace`  | Highly detailed internal execution tracing.                          |\n   | `debug`  | Diagnostic information useful during development.                    |\n   | `info`   | General operational events.                                          |\n   | `warn`   | Potential issues that don't prevent normal operation.                |\n   | `error`  | Errors that affect specific operations.                              |\n   | `fatal`  | Critical errors causing process termination.                         |\n   | `notify` | Important operational milestones. Always logged regardless of level. |\n\n   The default log level is `warn`. Setting a level includes that level and all more-severe levels.\n\n5. **Enable console capture when porting existing code** — When `logging.console: true` is set, writes via `console.log`, `console.warn`, `console.error`, etc. are appended verbatim to `hdb.log`. Captured lines do **not** pass through `logger`'s level filter. Prefer `logger` directly in production code so that level filtering and tagging apply. Console capture is intended as a convenience for porting existing code and for debugging.\n\n6. **Know where logs are written** — All standard log output goes to `<ROOTPATH>/log/hdb.log` (default: `~/hdb/log/hdb.log`). To also log to `stdout`/`stderr`, set `logging.stdStreams: true`.\n\n## Examples\n\n### Basic logging in a resource\n\n```javascript\nexport class MyResource extends Resource {\n\tasync get(id) {\n\t\tlogger.debug('Fetching record', { id });\n\t\tconst record = await super.get(id);\n\t\tif (!record) {\n\t\t\tlogger.warn('Record not found', { id });\n\t\t}\n\t\treturn record;\n\t}\n\n\tasync put(record) {\n\t\tlogger.info('Updating record', { id: record.id });\n\t\ttry {\n\t\t\treturn await super.put(record);\n\t\t} catch (err) {\n\t\t\tlogger.error('Failed to update record', err);\n\t\t\tthrow err;\n\t\t}\n\t}\n}\n```\n\n### Tagged logging with `withTag()`\n\n```javascript\nconst log = logger.withTag('my-resource');\n\nexport class MyResource extends Resource {\n\tasync get(id) {\n\t\tlog.debug?.('Fetching record', { id });\n\t\tconst record = await super.get(id);\n\t\tif (!record) {\n\t\t\tlog.warn?.('Record not found', { id });\n\t\t}\n\t\treturn record;\n\t}\n\n\tasync put(record) {\n\t\tlog.info?.('Updating record', { id: record.id });\n\t\ttry {\n\t\t\treturn await super.put(record);\n\t\t} catch (err) {\n\t\t\tlog.error?.('Failed to update record', err);\n\t\t\tthrow err;\n\t\t}\n\t}\n}\n```\n\nTagged entries appear in `hdb.log` with the tag in the header:\n\n```\n2023-03-09T14:25:05.269Z [info] [my-resource]: Updating record\n```\n\n## Notes\n\n- All log output is written to `<ROOTPATH>/log/hdb.log`. The `logger` global writes to this file at the configured `logging.external` level.\n- Log entry format for `logger`: `<timestamp> [<level>] [<thread>/<id>]: <message>`\n- Log entry format for `TaggedLogger`: `<timestamp> [<level>] [<tag>]: <message>`\n- `console.log` output is only forwarded to `hdb.log` when `logging.console: true` is explicitly set; it is not forwarded by default.\n- When logging to standard streams, run Harper in the foreground (`harper`, not `harper start`).\n- `TaggedLogger` is bound to the configured log level at creation time — always use `?.` on its methods.\n",
 	"programmatic-table-requests": "---\nname: programmatic-table-requests\ndescription: How to interact with Harper tables programmatically using the `tables` object.\nmetadata:\n  mode: synthesized\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.'\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",

package/harper-best-practices/AGENTS.md

@@ -1833,20 +1833,18 @@ Instructions for the agent to follow when loading environment variables from `.e
 
 #### When to Use
 
-Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever you need to configure `loadEnv` in `config.yaml`, control load order, handle multiple files, or manage override behavior.
+Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever hardcoding values must be avoided and environment-specific configuration must be supplied to Harper components.
 
 #### How It Works
 
-1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` to your `config.yaml` with a `files` key pointing to the `.env` file. `loadEnv` is built into Harper and does not need to be installed separately.
+1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as a top-level key. It is built into Harper and requires no installation.
 
    ```yaml
    loadEnv:
      files: '.env'
    ```
 
-   This loads the specified file from the root of your component directory into `process.env`.
-
-2. **Place `loadEnv` first**: Always declare `loadEnv` before any other components in `config.yaml` so environment variables are available before dependent components start. Because Harper is single-process, variables loaded onto `process.env` are shared across all components.
+2. **Place `loadEnv` first**: Always list `loadEnv` before any other components in `config.yaml` so that environment variables are available on `process.env` before dependent components start.
 
    ```yaml
    # config.yaml — loadEnv must come first
@@ -1859,7 +1857,9 @@ Apply this rule when a Harper application needs to load secrets or configuration
      files: './src/*.js'
    ```
 
-3. **Control override behavior**: By default, existing shell or container environment variables take precedence over values in `.env` files. To force `.env` values to overwrite existing variables, set `override: true`.
+3. **Configure the `files` option**: Provide one or more paths or glob patterns pointing to the env files to load. This option is required.
+
+4. **Set `override` if needed**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this and have loaded values win.
 
    ```yaml
    loadEnv:
@@ -1867,22 +1867,36 @@ Apply this rule when a Harper application needs to load secrets or configuration
      override: true
    ```
 
-4. **Load multiple files**: Provide a list of files or a glob pattern under `files`. Files are loaded in the order specified.
+5. **Load multiple files when required**: Supply a list of files or a glob pattern. Files are loaded in the order specified.
    ```yaml
    loadEnv:
      files:
        - '.env'
        - '.env.local'
    ```
-   Or using a glob pattern:
+   or
    ```yaml
    loadEnv:
      files: 'env-vars/*'
    ```
 
+##### Configuration Options
+
+| Option     | Type                 | Required | Description                                                                            |
+| ---------- | -------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `files`    | `string \| string[]` | **Yes**  | Path(s) or glob pattern(s) to the env file(s) to load.                                 |
+| `override` | `boolean`            | No       | If `true`, loaded values override existing environment variables. Defaults to `false`. |
+
 #### Examples
 
-A complete `config.yaml` using `loadEnv` with multiple files and override enabled:
+**Minimal setup — single `.env` file:**
+
+```yaml
+loadEnv:
+  files: '.env'
+```
+
+**Full `config.yaml` with load order, multiple files, and override:**
 
 ```yaml
 # config.yaml — loadEnv must come first
@@ -1898,19 +1912,16 @@ myApp:
   files: './src/*.js'
 ```
 
-A minimal setup loading a single `.env` file:
+**Glob pattern:**
 
 ```yaml
 loadEnv:
-  files: '.env'
-
-myApp:
-  files: './src/*.js'
+  files: 'env-vars/*'
 ```
 
 #### Notes
 
-- `loadEnv` is built into Harper — declare it in `config.yaml` only; do not install it as a separate package.
-- The `files` value accepts either a single string, a list of strings, or a glob pattern.
-- Without `override: true`, variables already present in the environment are never overwritten by values in `.env` files.
-- `process.env` is shared across all Harper components in the same process, so load order in `config.yaml` determines availability.
+- `loadEnv` is built into Harper — do not install it separately; only declare it in `config.yaml`.
+- Because Harper is a single-process application, variables loaded onto `process.env` are shared across all components.
+- Without `override: true`, variables already set in the shell or container environment will not be overwritten by values in `.env` files.
+- `files` is the only required option; omitting it will produce an invalid configuration.

package/harper-best-practices/rules/load-env.md

@@ -7,8 +7,8 @@ metadata:
   mode: generate
   sources:
     - reference/v5/environment-variables/overview.md
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: c73a0caf28a2b833
+  sourceCommit: 42231db17c025a4a455e3d91875fad4084a01cb5
+  inputHash: fe610fc245226357
 ---
 
 # Load Environment Variables with loadEnv
@@ -17,20 +17,18 @@ Instructions for the agent to follow when loading environment variables from `.e
 
 ## When to Use
 
-Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever you need to configure `loadEnv` in `config.yaml`, control load order, handle multiple files, or manage override behavior.
+Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever hardcoding values must be avoided and environment-specific configuration must be supplied to Harper components.
 
 ## How It Works
 
-1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` to your `config.yaml` with a `files` key pointing to the `.env` file. `loadEnv` is built into Harper and does not need to be installed separately.
+1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as a top-level key. It is built into Harper and requires no installation.
 
    ```yaml
    loadEnv:
      files: '.env'
    ```
 
-   This loads the specified file from the root of your component directory into `process.env`.
-
-2. **Place `loadEnv` first**: Always declare `loadEnv` before any other components in `config.yaml` so environment variables are available before dependent components start. Because Harper is single-process, variables loaded onto `process.env` are shared across all components.
+2. **Place `loadEnv` first**: Always list `loadEnv` before any other components in `config.yaml` so that environment variables are available on `process.env` before dependent components start.
 
    ```yaml
    # config.yaml — loadEnv must come first
@@ -43,7 +41,9 @@ Apply this rule when a Harper application needs to load secrets or configuration
      files: './src/*.js'
    ```
 
-3. **Control override behavior**: By default, existing shell or container environment variables take precedence over values in `.env` files. To force `.env` values to overwrite existing variables, set `override: true`.
+3. **Configure the `files` option**: Provide one or more paths or glob patterns pointing to the env files to load. This option is required.
+
+4. **Set `override` if needed**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this and have loaded values win.
 
    ```yaml
    loadEnv:
@@ -51,22 +51,36 @@ Apply this rule when a Harper application needs to load secrets or configuration
      override: true
    ```
 
-4. **Load multiple files**: Provide a list of files or a glob pattern under `files`. Files are loaded in the order specified.
+5. **Load multiple files when required**: Supply a list of files or a glob pattern. Files are loaded in the order specified.
    ```yaml
    loadEnv:
      files:
        - '.env'
        - '.env.local'
    ```
-   Or using a glob pattern:
+   or
    ```yaml
    loadEnv:
      files: 'env-vars/*'
    ```
 
+### Configuration Options
+
+| Option     | Type                 | Required | Description                                                                            |
+| ---------- | -------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `files`    | `string \| string[]` | **Yes**  | Path(s) or glob pattern(s) to the env file(s) to load.                                 |
+| `override` | `boolean`            | No       | If `true`, loaded values override existing environment variables. Defaults to `false`. |
+
 ## Examples
 
-A complete `config.yaml` using `loadEnv` with multiple files and override enabled:
+**Minimal setup — single `.env` file:**
+
+```yaml
+loadEnv:
+  files: '.env'
+```
+
+**Full `config.yaml` with load order, multiple files, and override:**
 
 ```yaml
 # config.yaml — loadEnv must come first
@@ -82,19 +96,16 @@ myApp:
   files: './src/*.js'
 ```
 
-A minimal setup loading a single `.env` file:
+**Glob pattern:**
 
 ```yaml
 loadEnv:
-  files: '.env'
-
-myApp:
-  files: './src/*.js'
+  files: 'env-vars/*'
 ```
 
 ## Notes
 
-- `loadEnv` is built into Harper — declare it in `config.yaml` only; do not install it as a separate package.
-- The `files` value accepts either a single string, a list of strings, or a glob pattern.
-- Without `override: true`, variables already present in the environment are never overwritten by values in `.env` files.
-- `process.env` is shared across all Harper components in the same process, so load order in `config.yaml` determines availability.
+- `loadEnv` is built into Harper — do not install it separately; only declare it in `config.yaml`.
+- Because Harper is a single-process application, variables loaded onto `process.env` are shared across all components.
+- Without `override: true`, variables already set in the shell or container environment will not be overwritten by values in `.env` files.
+- `files` is the only required option; omitting it will produce an invalid configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/skills",
-	"version": "1.8.0",
+	"version": "1.9.1",
 	"description": "Best practices for making awesome Harper apps with your favorite Agent",
 	"keywords": [],
 	"homepage": "https://github.com/harperfast",
@@ -29,6 +29,7 @@
 		"format": "oxfmt",
 		"format:check": "oxfmt --check",
 		"generate": "node scripts/generation/generate-rules.mjs",
+		"sync:report": "node scripts/generation/sync-report.mjs",
 		"validate": "npm run format:check && npm run build && node scripts/validate-skills.mjs && node scripts/generation/validate-generated.mjs"
 	},
 	"devDependencies": {