@harperfast/skills 1.7.0 → 1.8.0

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export declare const ruleNames: readonly [
 	"deploying-to-harper-fabric",
 	"extending-tables",
 	"handling-binary-data",
+	"load-env",
 	"logging",
 	"programmatic-table-requests",
 	"querying-rest-apis",

package/dist/index.js

@@ -13,6 +13,7 @@ export const ruleNames = [
 	"deploying-to-harper-fabric",
 	"extending-tables",
 	"handling-binary-data",
+	"load-env",
 	"logging",
 	"programmatic-table-requests",
 	"querying-rest-apis",
@@ -33,19 +34,20 @@ export const rules = {
 	"caching": "---\nname: caching\ndescription: How to implement integrated data caching in Harper from external sources.\nmetadata:\n  mode: generate\n  sources:\n    - learn/developers/caching-with-harper.md\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: 8212a7d7dbbd2b18\n---\n\n# Caching External Data Sources in Harper\n\nInstructions for the agent to implement integrated data caching in Harper by wrapping external sources with a cache table and `sourcedFrom`.\n\n## When to Use\n\nApply this rule when a Harper application needs to cache responses from an external API, microservice, or database to avoid repeated slow or expensive upstream calls. Use it whenever you need to define TTL-based cache expiration, observe ETag-based conditional responses, or manually invalidate cached entries.\n\n## How It Works\n\n1. **Define a cache table with `expiration`**: In `schema.graphql`, add the `expiration` argument to `@table`. The value is in seconds. Any record older than this threshold is considered stale and will be re-fetched on next access.\n\n   ```graphql\n   type JokeCache @table(expiration: 60) @export {\n   \tid: ID @primaryKey\n   \tsetup: String\n   \tpunchline: String\n   }\n   ```\n\n2. **Wrap the external source in `resources.js`**: Create an object with a `get(id)` method that fetches from the upstream source. Then call `sourcedFrom` on the table to register it.\n\n   ```javascript\n   const jokeAPI = {\n   \tasync get(id) {\n   \t\tconst response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);\n   \t\treturn response.json();\n   \t},\n   };\n\n   tables.JokeCache.sourcedFrom(jokeAPI);\n   ```\n\n   Harper's caching behavior after `sourcedFrom` is registered:\n   - A request arrives for `/JokeCache/1`.\n   - Harper checks if the record with id `1` exists in `JokeCache` and is not stale.\n   - If fresh, Harper returns it immediately.\n   - If missing or stale, Harper calls `jokeAPI.get()`, stores the result in `JokeCache`, and returns it.\n   - Multiple simultaneous requests for the same missing or stale record wait on a single upstream call — Harper prevents cache stampedes automatically.\n\n3. **Configure plugins in `config.yaml`**: Enable the schema, REST API, and JS resource plugins.\n\n   ```yaml\n   graphqlSchema:\n     files: 'schema.graphql'\n   rest: true\n   jsResource:\n     files: 'resources.js'\n   ```\n\n4. **Observe caching via ETags**: Harper automatically computes an ETag from the record's last-modified timestamp. On the first request you receive a `200` with an `etag` header. Pass that value back in `If-None-Match` on subsequent requests; Harper returns `304 Not Modified` with an empty body if the record is unchanged.\n\n   ```bash\n   curl -i 'http://localhost:9926/JokeCache/1' \\\n     -H 'If-None-Match: \"abCDefGHij\"'\n   ```\n\n5. **Force a cache bypass**: Send `Cache-Control: no-cache` to make Harper skip the local cache and always call the upstream source, regardless of TTL.\n\n   ```bash\n   curl -i 'http://localhost:9926/JokeCache/1' \\\n     -H 'Cache-Control: no-cache'\n   ```\n\n6. **Invalidate a cache entry on demand**: Remove `@export` from the schema type, then export a class of the same name in `resources.js` that extends the table and implements a `post` handler calling `this.invalidate(target)`.\n\n   ```graphql\n   type JokeCache @table(expiration: 60) {\n   \tid: ID @primaryKey\n   \tsetup: String\n   \tpunchline: String\n   }\n   ```\n\n   ```javascript\n   export class JokeCache extends tables.JokeCache {\n   \tstatic async post(target, data) {\n   \t\tconst body = await data;\n   \t\tif (body?.action === 'invalidate') {\n   \t\t\tthis.invalidate(target);\n   \t\t\treturn { status: 200, data: { message: 'invalidated' } };\n   \t\t}\n   \t}\n   }\n   ```\n\n   Trigger invalidation with a `POST`:\n\n   ```bash\n   curl -X POST 'http://localhost:9926/JokeCache/1' \\\n     -H 'Content-Type: application/json' \\\n     -d '{\"action\": \"invalidate\"}'\n   ```\n\n   The next `GET /JokeCache/1` will fetch fresh data from the upstream source regardless of TTL.\n\n## Examples\n\nComplete `schema.graphql` and `resources.js` for a cached external API with on-demand invalidation:\n\n```graphql\ntype JokeCache @table(expiration: 60) {\n\tid: ID @primaryKey\n\tsetup: String\n\tpunchline: String\n}\n```\n\n```javascript\n// resources.js\n\nconst jokeAPI = {\n\tasync get() {\n\t\tconst id = this.getId();\n\t\tconst response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);\n\t\treturn response.json();\n\t},\n};\n\ntables.JokeCache.sourcedFrom(jokeAPI);\n\nexport class JokeCache extends tables.JokeCache {\n\tstatic async post(target, data) {\n\t\tconst body = await data;\n\t\tif (body?.action === 'invalidate') {\n\t\t\tthis.invalidate(target);\n\t\t\treturn { status: 200, data: { message: 'invalidated' } };\n\t\t}\n\t}\n}\n```\n\nFirst request — cache miss, upstream is called, `200` returned:\n\n```bash\ncurl -i 'http://localhost:9926/JokeCache/1'\n```\n\nSecond request with ETag — cache hit, `304 Not Modified`:\n\n```bash\ncurl -i 'http://localhost:9926/JokeCache/1' \\\n  -H 'If-None-Match: \"abCDefGHij\"'\n```\n\n## Notes\n\n- `expiration` is measured in seconds. Harper also supports separate `eviction` and `scanInterval` arguments on `@table` for fine-grained control over physical record removal.\n- The `@export` directive on the schema type is not required when you export a Resource class of the same name from `resources.js` — the class export serves as the endpoint registration. See [custom-resources.md](custom-resources.md) for details on building Resource classes.\n- Harper's REST layer automatically exposes `@export`-ed tables and Resource classes as HTTP endpoints. See [automatic-apis.md](automatic-apis.md) for how endpoints are structured and named.\n- ETag values include their double quotes as part of the value — include them verbatim when passing the value in `If-None-Match`.\n- `sourcedFrom` must be called after the table reference (`tables.JokeCache`) is available, which is guaranteed when the call is at the top level of `resources.js`.\n",
 	"checking-authentication": "---\nname: checking-authentication\ndescription: How to handle user authentication and sessions in Harper Resources.\nmetadata:\n  mode: generate\n  sources:\n    - >-\n      reference/v5/resources/resource-api.md#`getCurrentUser(): User |\n      undefined`\n    - reference/v5/resources/resource-api.md#Session and Login from a Resource\n    - reference/v5/security/jwt-authentication.md\n  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819\n  inputHash: fdd9ec3b11011490\n---\n\n# Checking Authentication\n\nInstructions for the agent to follow when handling user authentication and session management inside Harper Resources.\n\n## When to Use\n\nApply this rule when implementing authentication checks, login/logout flows, or token issuance inside a custom Resource. Use it any time a Resource needs to identify the current user, establish a session, or issue JWTs to clients. See [custom-resources.md](custom-resources.md) for the general Resource authoring pattern.\n\n## How It Works\n\n1. **Check the current user** with `getCurrentUser()`. Call it inside any Resource method to retrieve the authenticated user or `undefined` if no user is authenticated. Guard protected endpoints by returning a `401` when the result is `undefined`.\n\n   ```javascript\n   async get(target) {\n     const user = this.getCurrentUser();\n     if (!user) return new Response(null, { status: 401 });\n     return { username: user.username, role: user.role };\n   }\n   ```\n\n   The returned object exposes `username`, `role`, and `role.permission` flags.\n\n2. **Enable sessions** before using session-based login. Set `authentication.enableSessions: true` in `harperdb-config.yaml`:\n\n   ```yaml\n   authentication:\n     enableSessions: true\n   ```\n\n3. **Access login and session helpers** via `getContext()`. The context object exposes `context.login` and `context.session` for sign-in/out flows.\n   - Call `context.login(username, password)` to verify credentials and establish a session cookie on success.\n   - To end a session, delete it via `context.session.delete(context.session.id)`.\n\n4. **Implement sign-in and sign-out Resources** using the context helpers:\n\n   ```javascript\n   export class SignIn extends Resource {\n   \tasync post(_target, data) {\n   \t\tconst context = this.getContext();\n   \t\ttry {\n   \t\t\tawait context.login(data.username, data.password);\n   \t\t} catch {\n   \t\t\treturn new Response('Invalid credentials', { status: 403 });\n   \t\t}\n   \t\treturn new Response('Logged in', { status: 200 });\n   \t}\n   }\n\n   export class SignOut extends Resource {\n   \tasync post() {\n   \t\tconst context = this.getContext();\n   \t\tif (!context.session) return new Response(null, { status: 401 });\n   \t\tawait context.session.delete(context.session.id);\n   \t\treturn new Response('Logged out', { status: 200 });\n   \t}\n   }\n   ```\n\n5. **Issue JWTs for non-browser clients** (CLI tools, mobile apps, service-to-service). Cookie-based sessions are intended for browser clients. For other clients, mint tokens programmatically using `server.operation()`:\n\n   ```javascript\n   import { Resource, server } from 'harper';\n\n   export class IssueTokens extends Resource {\n   \tstatic async get(_target, context) {\n   \t\tconst { operation_token, refresh_token } = await server.operation(\n   \t\t\t{ operation: 'create_authentication_tokens' },\n   \t\t\tcontext,\n   \t\t\ttrue,\n   \t\t);\n   \t\treturn { operation_token, refresh_token };\n   \t}\n\n   \tstatic async post(_target, data) {\n   \t\tconst { username, password } = await data;\n   \t\tif (!username || !password) {\n   \t\t\treturn new Response('username and password required', { status: 400 });\n   \t\t}\n   \t\tconst { operation_token, refresh_token } = await server.operation({\n   \t\t\toperation: 'create_authentication_tokens',\n   \t\t\tusername,\n   \t\t\tpassword,\n   \t\t});\n   \t\treturn { operation_token, refresh_token };\n   \t}\n   }\n\n   export class RefreshJWT extends Resource {\n   \tstatic async post(_target, data) {\n   \t\tconst { refresh_token } = await data;\n   \t\tif (!refresh_token) {\n   \t\t\treturn new Response('refresh_token required', { status: 400 });\n   \t\t}\n   \t\tconst { operation_token } = await server.operation({\n   \t\t\toperation: 'refresh_operation_token',\n   \t\t\trefresh_token,\n   \t\t});\n   \t\treturn { operation_token };\n   \t}\n   }\n   ```\n\n   Pass `true` as the third argument to `server.operation()` when the operation should run as the current authenticated user. Omit it or pass `false` when the operation supplies its own credentials.\n\n6. **Configure JWT token expiry** in `harperdb-config.yaml` under the `authentication` section:\n\n   ```yaml\n   authentication:\n     operationTokenTimeout: 1d\n     refreshTokenTimeout: 30d\n   ```\n\n   Duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`).\n\n## Examples\n\n**Protecting a resource endpoint and returning user info:**\n\n```javascript\nasync get(target) {\n  const user = this.getCurrentUser();\n  if (!user) return new Response(null, { status: 401 });\n  return { username: user.username, role: user.role };\n}\n```\n\n**Full session-based sign-in/sign-out flow:**\n\n```javascript\nexport class SignIn extends Resource {\n\tasync post(_target, data) {\n\t\tconst context = this.getContext();\n\t\ttry {\n\t\t\tawait context.login(data.username, data.password);\n\t\t} catch {\n\t\t\treturn new Response('Invalid credentials', { status: 403 });\n\t\t}\n\t\treturn new Response('Logged in', { status: 200 });\n\t}\n}\n\nexport class SignOut extends Resource {\n\tasync post() {\n\t\tconst context = this.getContext();\n\t\tif (!context.session) return new Response(null, { status: 401 });\n\t\tawait context.session.delete(context.session.id);\n\t\treturn new Response('Logged out', { status: 200 });\n\t}\n}\n```\n\n**JWT token refresh endpoint:**\n\n```javascript\nexport class RefreshJWT extends Resource {\n\tstatic async post(_target, data) {\n\t\tconst { refresh_token } = await data;\n\t\tif (!refresh_token) {\n\t\t\treturn new Response('refresh_token required', { status: 400 });\n\t\t}\n\t\tconst { operation_token } = await server.operation({\n\t\t\toperation: 'refresh_operation_token',\n\t\t\trefresh_token,\n\t\t});\n\t\treturn { operation_token };\n\t}\n}\n```\n\n## Notes\n\n- `getCurrentUser()` and `getContext()` are instance methods; call them with `this` inside non-static Resource methods.\n- `enableSessions` must be `true` in config before `context.login` or `context.session` will function.\n- Cookie-based sessions target browser clients. Use JWT issuance via `server.operation()` for all other client types.\n- When both `operation_token` and `refresh_token` have expired, the client must call `create_authentication_tokens` again with credentials.\n",
 	"creating-a-fabric-account-and-cluster": "---\nname: creating-a-fabric-account-and-cluster\ndescription: How to create a Harper Fabric account, organization, and cluster.\nmetadata:\n  mode: synthesized\n---\n\n# Creating a Harper Fabric Account and Cluster\n\nFollow these steps to set up your Harper Fabric environment for deployment.\n\n## How It Works\n\n1. **Sign Up/In**: Go to [https://fabric.harper.fast/](https://fabric.harper.fast/) and sign up or sign in.\n2. **Create an Organization**: Create an organization (org) to manage your projects.\n3. **Create a Cluster**: Create a new cluster. This can be on the free tier, no credit card required.\n4. **Set Credentials**: During setup, set the cluster username and password to finish configuring it.\n5. **Get Application URL**: Navigate to the **Config** tab and copy the **Application URL**.\n6. **Configure Environment**: Update your `.env` file or GitHub Actions secrets with cluster-specific credentials.\n7. **Next Steps**: See the [deploying-to-harper-fabric](deploying-to-harper-fabric.md) rule for detailed instructions on deploying your application successfully.\n\n## Examples\n\n### Environment Configuration\n\n```bash\nCLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'\nCLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'\nCLI_TARGET='YOUR_CLUSTER_URL'\n```\n",
-	"creating-harper-apps": "---\nname: creating-harper-apps\ndescription: How to initialize a new Harper application using the CLI.\nmetadata:\n  mode: synthesized\n---\n\n# Creating Harper Applications\n\nThe fastest way to start a new Harper project is using the `create-harper` CLI tool. This command initializes a project with a standard folder structure, essential configuration files, and basic schema definitions.\n\n## When to Use\n\nUse this command when starting a new Harper application or adding a new Harper microservice to an existing architecture.\n\n## Commands\n\nInitialize a project using your preferred package manager:\n\n### NPM\n\n```bash\nnpm create harper@latest\n```\n\n### PNPM\n\n```bash\npnpm create harper@latest\n```\n\n### Bun\n\n```bash\nbun create harper@latest\n```\n\n## Options\n\nYou can specify the project name and template directly:\n\n```bash\nnpm create harper@latest my-app --template default\n```\n\n## Next Steps\n\n1. **Configure Environment**: Set up your `.env` file with local or cloud credentials.\n2. **Define Schema**: Modify `schema.graphql` to fit your application's data model.\n3. **Start Development**: Run `npm run dev` to start the local Harper instance.\n4. **Deploy**: Use `npm run deploy` to push your application to Harper Fabric.\n",
+	"creating-harper-apps": "---\nname: creating-harper-apps\ndescription: How to initialize a new Harper application using the CLI.\nmetadata:\n  mode: synthesized\n---\n\n# Creating Harper Applications\n\nThe fastest way to start a new Harper project is using the `create-harper` CLI tool. This command\ninitializes a project with a standard folder structure, essential configuration files, and basic\nschema definitions.\n\n## When to Use\n\nUse this command when starting a new Harper application or adding a new Harper microservice to an\nexisting architecture.\n\n## Commands\n\nInitialize a project using your preferred package manager:\n\n### NPM\n\n```bash\nnpm create harper@latest\n```\n\n### PNPM\n\n```bash\npnpm create harper@latest\n```\n\n### Bun\n\n```bash\nbun create harper@latest\n```\n\n## Options\n\nYou can specify the project name and template directly:\n\n```bash\nnpm create harper@latest my-app --template default\n```\n\n## Next Steps\n\n1. **Configure Environment**: Set up your `.env` file with local or cloud credentials.\n2. **Define Schema**: Modify `schema.graphql` to fit your application's data model.\n3. **Start Development**: Run `npm run dev` to start the local Harper instance.\n4. **Deploy**: Use `npm run deploy` to push your application to Harper Fabric.\n",
 	"custom-resources": "---\nname: custom-resources\ndescription: How to define custom REST endpoints with JavaScript or TypeScript in Harper.\nmetadata:\n  mode: synthesized\n---\n\n# Custom Resources\n\nInstructions for the agent to follow when creating custom resources in Harper.\n\n## When to Use\n\nUse this skill when the automatic CRUD operations provided by `@table @export` are insufficient, and you need custom logic, third-party API integration, or specialized data handling for your REST endpoints.\n\n## How It Works\n\n1. **Check if a Custom Resource is Necessary**: Verify if [Automatic APIs](./automatic-apis.md) or [Extending Tables](./extending-tables.md) can satisfy the requirement first.\n2. **Create the Resource File**: Create a `.ts` or `.js` file in the directory specified by `jsResource` in `config.yaml` (typically `resources/`).\n3. **Define the Resource Class**: Export a class extending `Resource` from `harper`:\n\n   ```typescript\n   import { type RequestTargetOrId, Resource } from 'harper';\n\n   export class MyResource extends Resource {\n   \tasync get(target?: RequestTargetOrId) {\n   \t\treturn { message: 'Hello from custom GET!' };\n   \t}\n   }\n   ```\n\n4. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests.\n5. **Route Nesting and Naming**: You can control the URL structure by how you export your resources:\n   - **Direct Class Export**: `export class Foo extends Resource` creates endpoints at `/Foo/`. Class names are case-sensitive in the URL.\n   - **Nested Objects**: `export const Bar = { Foo };` creates endpoints at `/Bar/Foo/`.\n   - **Lowercase and Hyphens**: Use object keys to define custom paths: `export const bar = { 'foo-baz': Foo };` exposes endpoints at `/bar/foo-baz/`.\n6. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:\n   ```typescript\n   import { tables } from 'harper';\n   // ... inside a method\n   const results = await tables.MyTable.list();\n   ```\n7. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).\n",
 	"defining-relationships": "---\nname: defining-relationships\ndescription: How to define and use relationships between tables in Harper using GraphQL.\nmetadata:\n  mode: synthesized\n---\n\n# Defining Relationships\n\nInstructions for the agent to follow when defining relationships between Harper tables.\n\n## When to Use\n\nUse this skill when you need to link data across different tables, enabling automatic joins and efficient related-data fetching via REST APIs.\n\n## How It Works\n\n1. **Identify the Relationship Type**: Determine if it's one-to-one, many-to-one, or one-to-many.\n2. **Use the `@relationship` Directive**: Apply it to a field in your GraphQL schema.\n   - **Many-to-One (Current table holds FK)**: Use `from`.\n     ```graphql\n     type Book @table @export {\n     \tauthorId: ID\n     \tauthor: Author @relationship(from: \"authorId\")\n     }\n     ```\n   - **One-to-Many (Related table holds FK)**: Use `to` and an array type.\n     ```graphql\n     type Author @table @export {\n     \tbooks: [Book] @relationship(to: \"authorId\")\n     }\n     ```\n3. **Query with Relationships**: Use dot syntax in REST API calls for filtering or the `select()` operator for including related data.\n   - Example Filter: `GET /Book/?author.name=Harper`\n   - Example Select: `GET /Author/?select(name,books(title))`\n",
 	"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",
 	"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",
 	"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: Best practices for Harper schema design, including core directives and GraphQL tooling configuration.\nmetadata:\n  mode: synthesized\n---\n\n# Schema Design & Tooling\n\nHarper uses GraphQL schemas to define database tables, relationships, and APIs. To ensure the best development experience for both humans and AI agents, it's important to understand the core directives and configure your project tooling correctly.\n\n## Core Harper Directives\n\nHarper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harper/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:\n\n### Table Definition\n\n- `@table`: Marks a GraphQL type as a Harper database table.\n- `@export`: Automatically generates REST and WebSocket APIs for the table.\n- `@table(expiration: Int)`: Configures a time-to-expire for records in the table (useful for caching).\n\n### Attribute Constraints & Indexing\n\n- `@primaryKey`: Specifies the unique identifier for the table.\n- `@indexed`: Creates a standard index on the field for faster lookups.\n- `@indexed(type: \"HNSW\", distance: \"cosine\" | \"euclidean\" | \"dot\")`: Creates a vector index for similarity search.\n\n### Relationships\n\n- `@relationship(from: String)`: Defines a relationship to another table. `from` specifies the local field holding the foreign key.\n\n### Authentication & Authorization\n\n- `@auth(role: String)`: Restricts access to a table or field based on user roles.\n\n## Configuring GraphQL Tooling\n\nTo get the best IDE support (autocompletion, validation) and to help AI agents understand your schema context, you should create a `graphql.config.yml` file in your project root.\n\nThis file tells GraphQL tools where to find Harper's built-in types and directives alongside your own schema files.\n\n### Creating `graphql.config.yml`\n\nCreate a file named `graphql.config.yml` in your project root with the following content:\n\n```yaml\nschema:\n  - 'node_modules/harper/schema.graphql'\n  - 'schema.graphql'\n  - 'schemas/*.graphql'\n```\n\n### Why this is important:\n\n1. **Shared Directives**: It includes `@table`, `@primaryKey`, etc., so they aren't marked as \"unknown directives\".\n2. **Context for Agents**: When an agent reads your project, seeing this config helps it locate the core Harper definitions, leading to more accurate code generation.\n3. **Consistency**: The `npm create harper@latest` command includes this by default. Manually adding it to existing projects ensures they follow the same standards.\n\n## Example Project Structure\n\nA typical Harper project with proper schema tooling:\n\n```text\nmy-harper-app/\n├── config.yaml\n├── graphql.config.yml\n├── package.json\n├── schema.graphql\n└── resources.js\n```\n",
+	"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",
-	"typescript-type-stripping": "---\nname: typescript-type-stripping\ndescription: How to run TypeScript files directly in Harper without a build step.\nmetadata:\n  mode: synthesized\n---\n\n# TypeScript Type Stripping\n\nInstructions for the agent to follow when using TypeScript in Harper.\n\n## When to Use\n\nUse this skill when you want to write Harper Resources in TypeScript and have them execute directly in Node.js without an intermediate build or compilation step.\n\n## How It Works\n\n1. **Verify Node.js Version**: Ensure you are using Node.js v22.6.0 or higher.\n2. **Name Files with `.ts`**: Create your resource files in the `resources/` directory with a `.ts` extension.\n3. **Use TypeScript Syntax**: Write your resource classes using standard TypeScript (interfaces, types, etc.).\n   ```typescript\n   import { Resource } from 'harper';\n   export class MyResource extends Resource {\n   \tasync get(): Promise<{ message: string }> {\n   \t\treturn { message: 'Running TS directly!' };\n   \t}\n   }\n   ```\n4. **Use Explicit Extensions in Imports**: When importing other local modules, include the `.ts` extension: `import { helper } from './helper.ts'`.\n5. **Configure `config.yaml`**: Ensure `jsResource` points to your `.ts` files:\n   ```yaml\n   jsResource:\n     files: 'resources/*.ts'\n   ```\n",
+	"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"
 };
@@ -53,4 +55,4 @@ export const rules = {
 /**
  * The content of the Harper Best Practices SKILL.md.
  */
-export const skillSummary = "---\nname: harper-best-practices\ndescription: Best practices for building Harper applications, covering schema definition,\n  automatic APIs, authentication, custom resources, and data handling.\n  Triggers on tasks involving Harper database design, API implementation,\n  and deployment.\nlicense: Apache-2.0\nmetadata:\n  author: harper\n  version: '1.0.0'\n---\n\n# Harper Best Practices\n\nGuidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.\n\n## When to Use\n\nReference these guidelines when:\n\n- Defining or modifying database schemas\n- Implementing or extending REST/WebSocket APIs\n- Handling authentication and session management\n- Working with custom resources and extensions\n- Optimizing data storage and retrieval (Blobs, Vector Indexing)\n- Deploying applications to Harper Fabric\n\n## How It Works\n\n1. Review the requirements for the task (schema design, API needs, or infrastructure setup).\n2. Consult the relevant category under \"Rule Categories by Priority\" to understand the impact of your decisions.\n3. Apply specific rules from the \"Quick Reference\" section below by reading their detailed rule files.\n4. If you're building a new table, prioritize the `schema-` rules.\n5. If you're extending functionality, consult the `logic-` and `api-` rules.\n6. Validate your implementation against the `ops-` rules before deployment.\n\n## Examples\n\nSee the concrete examples embedded in each rule subsection below (GraphQL schemas, REST query patterns, and deployment workflow snippets).\n\n<!-- BEGIN GENERATED INDEX -->\n\n## Rule Categories by Priority\n\n| Priority | Category             | Impact | Prefix    |\n| -------- | -------------------- | ------ | --------- |\n| 1        | Schema & Data Design | HIGH   | `schema-` |\n| 2        | API & Communication  | HIGH   | `api-`    |\n| 3        | Logic & Extension    | MEDIUM | `logic-`  |\n| 4        | Infrastructure & Ops | MEDIUM | `ops-`    |\n\n## Quick Reference\n\n### 1. Schema & Data Design (HIGH)\n\n- `adding-tables-with-schemas` — Guidelines for adding tables to a Harper database using GraphQL schemas.\n- `schema-design-tooling` — Best practices for Harper schema design, including core directives and GraphQL tooling configuration.\n- `defining-relationships` — How to define and use relationships between tables in Harper using GraphQL.\n- `vector-indexing` — How to enable and query vector indexes for similarity search in Harper.\n- `using-blob-datatype` — How to use the Blob data type for efficient binary storage in Harper.\n- `handling-binary-data` — How to store and serve binary data like images or audio in Harper.\n\n### 2. API & Communication (HIGH)\n\n- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs.\n- `querying-rest-apis` — How to use query parameters to filter, sort, and paginate Harper REST APIs.\n- `real-time-apps` — How to build real-time features in Harper using WebSockets and Pub/Sub.\n- `checking-authentication` — How to handle user authentication and sessions in Harper Resources.\n\n### 3. Logic & Extension (MEDIUM)\n\n- `custom-resources` — How to define custom REST endpoints with JavaScript or TypeScript in Harper.\n- `extending-tables` — How to add custom logic to automatically generated table resources in Harper.\n- `programmatic-table-requests` — How to interact with Harper tables programmatically using the `tables` object.\n- `typescript-type-stripping` — How to run TypeScript files directly in Harper without a build step.\n- `caching` — How to implement integrated data caching in Harper from external sources.\n\n### 4. Infrastructure & Ops (MEDIUM)\n\n- `deploying-to-harper-fabric` — How to deploy a Harper application to the Harper Fabric cloud.\n- `creating-a-fabric-account-and-cluster` — How to create a Harper Fabric account, organization, and cluster.\n- `creating-harper-apps` — How to initialize a new Harper application using the CLI.\n- `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper.\n- `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.\n\n<!-- END GENERATED INDEX -->\n\n## How to Use\n\nRead individual rule files for detailed explanations and code examples:\n\n```\nrules/adding-tables-with-schemas.md\nrules/schema-design-tooling.md\nrules/automatic-apis.md\nrules/creating-harper-apps.md\nrules/logging.md\n```\n\n## Full Compiled Document\n\nFor the complete guide with all rules expanded: `AGENTS.md`\n";
+export const skillSummary = "---\nname: harper-best-practices\ndescription: Best practices for building Harper applications, covering schema definition,\n  automatic APIs, authentication, custom resources, and data handling.\n  Triggers on tasks involving Harper database design, API implementation,\n  and deployment.\nlicense: Apache-2.0\nmetadata:\n  author: harper\n  version: '1.0.0'\n---\n\n# Harper Best Practices\n\nGuidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.\n\n## When to Use\n\nReference these guidelines when:\n\n- Defining or modifying database schemas\n- Implementing or extending REST/WebSocket APIs\n- Handling authentication and session management\n- Working with custom resources and extensions\n- Optimizing data storage and retrieval (Blobs, Vector Indexing)\n- Deploying applications to Harper Fabric\n\n## How It Works\n\n1. Review the requirements for the task (schema design, API needs, or infrastructure setup).\n2. Consult the relevant category under \"Rule Categories by Priority\" to understand the impact of your decisions.\n3. Apply specific rules from the \"Quick Reference\" section below by reading their detailed rule files.\n4. If you're building a new table, prioritize the `schema-` rules.\n5. If you're extending functionality, consult the `logic-` and `api-` rules.\n6. Validate your implementation against the `ops-` rules before deployment.\n\n## Examples\n\nSee the concrete examples embedded in each rule subsection below (GraphQL schemas, REST query patterns, and deployment workflow snippets).\n\n<!-- BEGIN GENERATED INDEX -->\n\n## Rule Categories by Priority\n\n| Priority | Category             | Impact | Prefix    |\n| -------- | -------------------- | ------ | --------- |\n| 1        | Schema & Data Design | HIGH   | `schema-` |\n| 2        | API & Communication  | HIGH   | `api-`    |\n| 3        | Logic & Extension    | MEDIUM | `logic-`  |\n| 4        | Infrastructure & Ops | MEDIUM | `ops-`    |\n\n## Quick Reference\n\n### 1. Schema & Data Design (HIGH)\n\n- `adding-tables-with-schemas` — Guidelines for adding tables to a Harper database using GraphQL schemas.\n- `schema-design-tooling` — Best practices for Harper schema design, including core directives and GraphQL tooling configuration.\n- `defining-relationships` — How to define and use relationships between tables in Harper using GraphQL.\n- `vector-indexing` — How to enable and query vector indexes for similarity search in Harper.\n- `using-blob-datatype` — How to use the Blob data type for efficient binary storage in Harper.\n- `handling-binary-data` — How to store and serve binary data like images or audio in Harper.\n\n### 2. API & Communication (HIGH)\n\n- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs.\n- `querying-rest-apis` — How to use query parameters to filter, sort, and paginate Harper REST APIs.\n- `real-time-apps` — How to build real-time features in Harper using WebSockets and Pub/Sub.\n- `checking-authentication` — How to handle user authentication and sessions in Harper Resources.\n\n### 3. Logic & Extension (MEDIUM)\n\n- `custom-resources` — How to define custom REST endpoints with JavaScript or TypeScript in Harper.\n- `extending-tables` — How to add custom logic to automatically generated table resources in Harper.\n- `programmatic-table-requests` — How to interact with Harper tables programmatically using the `tables` object.\n- `typescript-type-stripping` — How to run TypeScript files directly in Harper without a build step.\n- `caching` — How to implement integrated data caching in Harper from external sources.\n\n### 4. Infrastructure & Ops (MEDIUM)\n\n- `deploying-to-harper-fabric` — How to deploy a Harper application to the Harper Fabric cloud.\n- `creating-a-fabric-account-and-cluster` — How to create a Harper Fabric account, organization, and cluster.\n- `creating-harper-apps` — How to initialize a new Harper application using the CLI.\n- `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper.\n- `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.\n- `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin.\n\n<!-- END GENERATED INDEX -->\n\n## How to Use\n\nRead individual rule files for detailed explanations and code examples:\n\n```\nrules/adding-tables-with-schemas.md\nrules/schema-design-tooling.md\nrules/automatic-apis.md\nrules/creating-harper-apps.md\nrules/logging.md\n```\n\n## Full Compiled Document\n\nFor the complete guide with all rules expanded: `AGENTS.md`\n";

package/harper-best-practices/AGENTS.md

@@ -40,70 +40,153 @@ type ExamplePerson @table @export {
 }
 ```
 
-### 1.2 Schema Design & Tooling
+### 1.2 Schema Design and Tooling
 
-Harper uses GraphQL schemas to define database tables, relationships, and APIs. To ensure the best development experience for both humans and AI agents, it's important to understand the core directives and configure your project tooling correctly.
+Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
-#### Core Harper Directives
+#### When to Use
+
+Apply 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.
+
+#### How It Works
+
+1. **Create a GraphQL schema file** with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
 
-Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harper/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
+   ```graphql
+   type Dog @table {
+   	id: Long @primaryKey
+   	name: String
+   	breed: String
+   	age: Int
+   }
+
+   type Breed @table {
+   	id: Long @primaryKey
+   	name: String @indexed
+   }
+   ```
+
+2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin key:
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   ```
 
-##### Table Definition
+   Both plugins and applications can specify schemas this way.
 
-- `@table`: Marks a GraphQL type as a Harper database table.
-- `@export`: Automatically generates REST and WebSocket APIs for the table.
-- `@table(expiration: Int)`: Configures a time-to-expire for records in the table (useful for caching).
+3. **Mark every table type with `@table`**. The type name becomes the table name by default. Use optional arguments to override behavior:
 
-##### Attribute Constraints & Indexing
+   | Argument       | Type      | Default                       | Description                                                   |
+   | -------------- | --------- | ----------------------------- | ------------------------------------------------------------- |
+   | `table`        | `String`  | type name                     | Override the table name                                       |
+   | `database`     | `String`  | `"data"`                      | Database to place the table in                                |
+   | `expiration`   | `Int`     | —                             | Seconds until a record goes stale                             |
+   | `eviction`     | `Int`     | `0`                           | Additional seconds after `expiration` before physical removal |
+   | `scanInterval` | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                |
+   | `replicate`    | `Boolean` | `true`                        | Enable replication of this table                              |
 
-- `@primaryKey`: Specifies the unique identifier for the table.
-- `@indexed`: Creates a standard index on the field for faster lookups.
-- `@indexed(type: "HNSW", distance: "cosine" | "euclidean" | "dot")`: Creates a vector index for similarity search.
+4. **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:
+   - `String` or `ID` → UUID string
+   - `Int`, `Long`, or `Any` → auto-incrementing integer
 
-##### Relationships
+   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
 
-- `@relationship(from: String)`: Defines a relationship to another table. `from` specifies the local field holding the foreign key.
+5. **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.
 
-##### Authentication & Authorization
+   ```graphql
+   type Product @table {
+   	id: Long @primaryKey
+   	category: String @indexed
+   	price: Float @indexed
+   }
+   ```
 
-- `@auth(role: String)`: Restricts access to a table or field based on user roles.
+6. **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.
 
-#### Configuring GraphQL Tooling
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
+   ```
 
-To get the best IDE support (autocompletion, validation) and to help AI agents understand your schema context, you should create a `graphql.config.yml` file in your project root.
+7. **Restrict extra properties** with `@sealed` when records must not include attributes beyond those declared. By default, Harper allows additional properties.
 
-This file tells GraphQL tools where to find Harper's built-in types and directives alongside your own schema files.
+   ```graphql
+   type StrictRecord @table @sealed {
+   	id: Long @primaryKey
+   	name: String
+   }
+   ```
 
-##### Creating `graphql.config.yml`
+8. **Configure expiration, eviction, and scan behavior** together when building caching tables. These three arguments control the full record lifecycle:
+   - `expiration` — record becomes stale; next request triggers a source fetch
+   - `eviction` — additional time after `expiration` before physical removal
+   - `scanInterval` — how often Harper scans for records to evict; clock-aligned, not startup-aligned
 
-Create a file named `graphql.config.yml` in your project root with the following content:
+#### Examples
 
-```yaml
-schema:
-  - 'node_modules/harper/schema.graphql'
-  - 'schema.graphql'
-  - 'schemas/*.graphql'
+**Caching table with tuned expiration:**
+
+```graphql
+# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
+type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
+	id: ID @primaryKey
+	temperature: Float
+}
 ```
 
-##### Why this is important:
+**Table in a named database with expiration and an indexed field:**
+
+```graphql
+type Event @table(database: "analytics", expiration: 86400) {
+	id: Long @primaryKey
+	name: String @indexed
+}
+```
 
-1. **Shared Directives**: It includes `@table`, `@primaryKey`, etc., so they aren't marked as "unknown directives".
-2. **Context for Agents**: When an agent reads your project, seeing this config helps it locate the core Harper definitions, leading to more accurate code generation.
-3. **Consistency**: The `npm create harper@latest` command includes this by default. Manually adding it to existing projects ensures they follow the same standards.
+**Session cache with auto-expiry:**
+
+```graphql
+type Session @table(expiration: 3600) {
+	id: Long @primaryKey
+	userId: String
+}
+```
+
+**Table with audit timestamps:**
+
+```graphql
+type Order @table @export(name: "orders") {
+	id: Long @primaryKey
+	createdAt: Long @createdTime
+	updatedAt: Long @updatedTime
+	status: String @indexed
+}
+```
 
-#### Example Project Structure
+**Overriding the table name and disabling replication:**
 
-A typical Harper project with proper schema tooling:
+```graphql
+type Product @table(table: "products") {
+	id: Long @primaryKey
+	name: String
+}
 
-```text
-my-harper-app/
-├── config.yaml
-├── graphql.config.yml
-├── package.json
-├── schema.graphql
-└── resources.js
+type LocalRecord @table(replicate: false) {
+	id: Long @primaryKey
+	value: String
+}
 ```
 
+#### Notes
+
+- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
+- 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.
+- `scanInterval` is clock-aligned to the server's local timezone. The server's startup time does not affect when eviction runs.
+- If replication is disabled on a table and later re-enabled, it will not catch up on writes made while replication was disabled.
+- Null values are indexed by `@indexed` fields, enabling queries such as `GET /Product/?category=null`.
+
 ### 1.3 Defining Relationships
 
 Instructions for the agent to follow when defining relationships between Harper tables.
@@ -1138,34 +1221,60 @@ for await (const record of tables.Product.search({
 
 Be very careful when performing updates and deletions! You may be dealing with live production data. The wrong request to delete, without approval from a human, could be devastating to a business. Always use the proper approval process.
 
-### 3.4 TypeScript Type Stripping
+### 3.4 TypeScript Type Stripping in Harper
 
-Instructions for the agent to follow when using TypeScript in Harper.
+Instructions for the agent to run `.ts` files directly in Harper without a build step using Node.js's built-in type stripping.
 
 #### When to Use
 
-Use this skill when you want to write Harper Resources in TypeScript and have them execute directly in Node.js without an intermediate build or compilation step.
+Apply 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.
 
 #### How It Works
 
-1. **Verify Node.js Version**: Ensure you are using Node.js v22.6.0 or higher.
-2. **Name Files with `.ts`**: Create your resource files in the `resources/` directory with a `.ts` extension.
-3. **Use TypeScript Syntax**: Write your resource classes using standard TypeScript (interfaces, types, etc.).
-   ```typescript
-   import { Resource } from 'harper';
-   export class MyResource extends Resource {
-   	async get(): Promise<{ message: string }> {
-   		return { message: 'Running TS directly!' };
-   	}
-   }
-   ```
-4. **Use Explicit Extensions in Imports**: When importing other local modules, include the `.ts` extension: `import { helper } from './helper.ts'`.
-5. **Configure `config.yaml`**: Ensure `jsResource` points to your `.ts` files:
+1. **Ensure Node.js version**: Require Node.js 22.6 or later. Type stripping is unavailable on earlier versions.
+
+2. **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:
+
    ```yaml
    jsResource:
      files: 'resources/*.ts'
    ```
 
+3. **Use explicit `.ts` extensions in local imports**: Node's loader does not resolve `'./helper'` to `'./helper.ts'`, so always include the full extension:
+
+   ```typescript
+   import { helper } from './helper.ts';
+   ```
+
+4. **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.
+
+#### Examples
+
+A complete Harper resource written in TypeScript, using imports from the `harper` package:
+
+```typescript
+import { type RequestTargetOrId, Resource, tables } from 'harper';
+
+export class MyResource extends Resource {
+	async get(target?: RequestTargetOrId): Promise<{ message: string }> {
+		return { message: 'Hello from TS' };
+	}
+}
+```
+
+Paired `config.yaml` entry loading the file via `jsResource`:
+
+```yaml
+jsResource:
+  files: 'resources/*.ts'
+```
+
+#### Notes
+
+- No build step or transpiler is required — Harper runs `.ts` files directly.
+- Type imports (e.g., `import { type RequestTargetOrId }`) from the `harper` package work as usual.
+- Unsupported TypeScript features include: enums with runtime values, namespaces with runtime semantics, and anything requiring code transformation beyond simple type stripping.
+
 ### 3.5 Caching External Data Sources in Harper
 
 Instructions for the agent to implement integrated data caching in Harper by wrapping external sources with a cache table and `sourcedFrom`.
@@ -1456,11 +1565,14 @@ CLI_TARGET='YOUR_CLUSTER_URL'
 
 ### 4.3 Creating Harper Applications
 
-The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command initializes a project with a standard folder structure, essential configuration files, and basic schema definitions.
+The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command
+initializes a project with a standard folder structure, essential configuration files, and basic
+schema definitions.
 
 #### When to Use
 
-Use this command when starting a new Harper application or adding a new Harper microservice to an existing architecture.
+Use this command when starting a new Harper application or adding a new Harper microservice to an
+existing architecture.
 
 #### Commands
 
@@ -1714,3 +1826,91 @@ Tagged entries appear in `hdb.log` with the tag in the header:
 - `console.log` output is only forwarded to `hdb.log` when `logging.console: true` is explicitly set; it is not forwarded by default.
 - When logging to standard streams, run Harper in the foreground (`harper`, not `harper start`).
 - `TaggedLogger` is bound to the configured log level at creation time — always use `?.` on its methods.
+
+### 4.6 Load Environment Variables with loadEnv
+
+Instructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.
+
+#### 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.
+
+#### 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.
+
+   ```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.
+
+   ```yaml
+   # config.yaml — loadEnv must come first
+   loadEnv:
+     files: '.env'
+
+   rest: true
+
+   myApp:
+     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`.
+
+   ```yaml
+   loadEnv:
+     files: '.env'
+     override: true
+   ```
+
+4. **Load multiple files**: Provide a list of files or a glob pattern under `files`. Files are loaded in the order specified.
+   ```yaml
+   loadEnv:
+     files:
+       - '.env'
+       - '.env.local'
+   ```
+   Or using a glob pattern:
+   ```yaml
+   loadEnv:
+     files: 'env-vars/*'
+   ```
+
+#### Examples
+
+A complete `config.yaml` using `loadEnv` with multiple files and override enabled:
+
+```yaml
+# config.yaml — loadEnv must come first
+loadEnv:
+  files:
+    - '.env'
+    - '.env.local'
+  override: true
+
+rest: true
+
+myApp:
+  files: './src/*.js'
+```
+
+A minimal setup loading a single `.env` file:
+
+```yaml
+loadEnv:
+  files: '.env'
+
+myApp:
+  files: './src/*.js'
+```
+
+#### 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.

package/harper-best-practices/SKILL.md

@@ -82,6 +82,7 @@ See the concrete examples embedded in each rule subsection below (GraphQL schema
 - `creating-harper-apps` — How to initialize a new Harper application using the CLI.
 - `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper.
 - `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.
+- `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin.
 
 <!-- END GENERATED INDEX -->
 

package/harper-best-practices/rules/creating-harper-apps.md

@@ -7,11 +7,14 @@ metadata:
 
 # Creating Harper Applications
 
-The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command initializes a project with a standard folder structure, essential configuration files, and basic schema definitions.
+The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command
+initializes a project with a standard folder structure, essential configuration files, and basic
+schema definitions.
 
 ## When to Use
 
-Use this command when starting a new Harper application or adding a new Harper microservice to an existing architecture.
+Use this command when starting a new Harper application or adding a new Harper microservice to an
+existing architecture.
 
 ## Commands
 

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

@@ -0,0 +1,100 @@
+---
+name: load-env
+description: >-
+  How to load environment variables from .env files into a Harper application
+  using the loadEnv plugin.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/environment-variables/overview.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: c73a0caf28a2b833
+---
+
+# Load Environment Variables with loadEnv
+
+Instructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.
+
+## 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.
+
+## 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.
+
+   ```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.
+
+   ```yaml
+   # config.yaml — loadEnv must come first
+   loadEnv:
+     files: '.env'
+
+   rest: true
+
+   myApp:
+     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`.
+
+   ```yaml
+   loadEnv:
+     files: '.env'
+     override: true
+   ```
+
+4. **Load multiple files**: Provide a list of files or a glob pattern under `files`. Files are loaded in the order specified.
+   ```yaml
+   loadEnv:
+     files:
+       - '.env'
+       - '.env.local'
+   ```
+   Or using a glob pattern:
+   ```yaml
+   loadEnv:
+     files: 'env-vars/*'
+   ```
+
+## Examples
+
+A complete `config.yaml` using `loadEnv` with multiple files and override enabled:
+
+```yaml
+# config.yaml — loadEnv must come first
+loadEnv:
+  files:
+    - '.env'
+    - '.env.local'
+  override: true
+
+rest: true
+
+myApp:
+  files: './src/*.js'
+```
+
+A minimal setup loading a single `.env` file:
+
+```yaml
+loadEnv:
+  files: '.env'
+
+myApp:
+  files: './src/*.js'
+```
+
+## 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.

package/harper-best-practices/rules/schema-design-tooling.md

@@ -1,70 +1,161 @@
 ---
 name: schema-design-tooling
-description: Best practices for Harper schema design, including core directives and GraphQL tooling configuration.
+description: >-
+  Best practices for Harper schema design, including core directives and GraphQL
+  tooling configuration.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/database/schema.md#Overview
+    - reference/v5/database/schema.md#Type Directives
+    - reference/v5/database/schema.md#Field Directives
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 4faa3baed7cfa854
 ---
 
-# Schema Design & Tooling
+# Schema Design and Tooling
 
-Harper uses GraphQL schemas to define database tables, relationships, and APIs. To ensure the best development experience for both humans and AI agents, it's important to understand the core directives and configure your project tooling correctly.
+Instructions for the agent to follow when designing Harper schemas, applying core directives, and configuring GraphQL tooling.
 
-## Core Harper Directives
+## When to Use
 
-Harper extends GraphQL with custom directives that define database behavior. These are typically defined in `node_modules/harper/schema.graphql`. If you don't have access to that file, here is a reference of the most important ones:
+Apply 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.
 
-### Table Definition
+## How It Works
 
-- `@table`: Marks a GraphQL type as a Harper database table.
-- `@export`: Automatically generates REST and WebSocket APIs for the table.
-- `@table(expiration: Int)`: Configures a time-to-expire for records in the table (useful for caching).
+1. **Create a GraphQL schema file** with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
 
-### Attribute Constraints & Indexing
+   ```graphql
+   type Dog @table {
+   	id: Long @primaryKey
+   	name: String
+   	breed: String
+   	age: Int
+   }
 
-- `@primaryKey`: Specifies the unique identifier for the table.
-- `@indexed`: Creates a standard index on the field for faster lookups.
-- `@indexed(type: "HNSW", distance: "cosine" | "euclidean" | "dot")`: Creates a vector index for similarity search.
+   type Breed @table {
+   	id: Long @primaryKey
+   	name: String @indexed
+   }
+   ```
 
-### Relationships
+2. **Register the schema in `config.yaml`** using the `graphqlSchema` plugin key:
 
-- `@relationship(from: String)`: Defines a relationship to another table. `from` specifies the local field holding the foreign key.
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   ```
 
-### Authentication & Authorization
+   Both plugins and applications can specify schemas this way.
 
-- `@auth(role: String)`: Restricts access to a table or field based on user roles.
+3. **Mark every table type with `@table`**. The type name becomes the table name by default. Use optional arguments to override behavior:
 
-## Configuring GraphQL Tooling
+   | Argument       | Type      | Default                       | Description                                                   |
+   | -------------- | --------- | ----------------------------- | ------------------------------------------------------------- |
+   | `table`        | `String`  | type name                     | Override the table name                                       |
+   | `database`     | `String`  | `"data"`                      | Database to place the table in                                |
+   | `expiration`   | `Int`     | —                             | Seconds until a record goes stale                             |
+   | `eviction`     | `Int`     | `0`                           | Additional seconds after `expiration` before physical removal |
+   | `scanInterval` | `Int`     | `(expiration + eviction) / 4` | Seconds between eviction scans                                |
+   | `replicate`    | `Boolean` | `true`                        | Enable replication of this table                              |
 
-To get the best IDE support (autocompletion, validation) and to help AI agents understand your schema context, you should create a `graphql.config.yml` file in your project root.
+4. **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:
+   - `String` or `ID` → UUID string
+   - `Int`, `Long`, or `Any` → auto-incrementing integer
 
-This file tells GraphQL tools where to find Harper's built-in types and directives alongside your own schema files.
+   Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
 
-### Creating `graphql.config.yml`
+5. **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.
 
-Create a file named `graphql.config.yml` in your project root with the following content:
+   ```graphql
+   type Product @table {
+   	id: Long @primaryKey
+   	category: String @indexed
+   	price: Float @indexed
+   }
+   ```
 
-```yaml
-schema:
-  - 'node_modules/harper/schema.graphql'
-  - 'schema.graphql'
-  - 'schemas/*.graphql'
+6. **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.
+
+   ```graphql
+   type MyTable @table @export(name: "my-table") {
+   	id: Long @primaryKey
+   }
+   ```
+
+7. **Restrict extra properties** with `@sealed` when records must not include attributes beyond those declared. By default, Harper allows additional properties.
+
+   ```graphql
+   type StrictRecord @table @sealed {
+   	id: Long @primaryKey
+   	name: String
+   }
+   ```
+
+8. **Configure expiration, eviction, and scan behavior** together when building caching tables. These three arguments control the full record lifecycle:
+   - `expiration` — record becomes stale; next request triggers a source fetch
+   - `eviction` — additional time after `expiration` before physical removal
+   - `scanInterval` — how often Harper scans for records to evict; clock-aligned, not startup-aligned
+
+## Examples
+
+**Caching table with tuned expiration:**
+
+```graphql
+# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
+type WeatherCache @table(expiration: 300, eviction: 3300, scanInterval: 600) {
+	id: ID @primaryKey
+	temperature: Float
+}
+```
+
+**Table in a named database with expiration and an indexed field:**
+
+```graphql
+type Event @table(database: "analytics", expiration: 86400) {
+	id: Long @primaryKey
+	name: String @indexed
+}
+```
+
+**Session cache with auto-expiry:**
+
+```graphql
+type Session @table(expiration: 3600) {
+	id: Long @primaryKey
+	userId: String
+}
 ```
 
-### Why this is important:
+**Table with audit timestamps:**
 
-1. **Shared Directives**: It includes `@table`, `@primaryKey`, etc., so they aren't marked as "unknown directives".
-2. **Context for Agents**: When an agent reads your project, seeing this config helps it locate the core Harper definitions, leading to more accurate code generation.
-3. **Consistency**: The `npm create harper@latest` command includes this by default. Manually adding it to existing projects ensures they follow the same standards.
+```graphql
+type Order @table @export(name: "orders") {
+	id: Long @primaryKey
+	createdAt: Long @createdTime
+	updatedAt: Long @updatedTime
+	status: String @indexed
+}
+```
 
-## Example Project Structure
+**Overriding the table name and disabling replication:**
 
-A typical Harper project with proper schema tooling:
+```graphql
+type Product @table(table: "products") {
+	id: Long @primaryKey
+	name: String
+}
 
-```text
-my-harper-app/
-├── config.yaml
-├── graphql.config.yml
-├── package.json
-├── schema.graphql
-└── resources.js
+type LocalRecord @table(replicate: false) {
+	id: Long @primaryKey
+	value: String
+}
 ```
+
+## Notes
+
+- Use unique `database` names in plugins and applications to avoid table naming collisions, since all tables default to the `"data"` database.
+- 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.
+- `scanInterval` is clock-aligned to the server's local timezone. The server's startup time does not affect when eviction runs.
+- If replication is disabled on a table and later re-enabled, it will not catch up on writes made while replication was disabled.
+- Null values are indexed by `@indexed` fields, enabling queries such as `GET /Product/?category=null`.

package/harper-best-practices/rules/typescript-type-stripping.md

@@ -2,33 +2,63 @@
 name: typescript-type-stripping
 description: How to run TypeScript files directly in Harper without a build step.
 metadata:
-  mode: synthesized
+  mode: generate
+  sources:
+    - reference/v5/components/javascript-environment.md#TypeScript Support
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 4e6bd8b610edd595
 ---
 
-# TypeScript Type Stripping
+# TypeScript Type Stripping in Harper
 
-Instructions for the agent to follow when using TypeScript in Harper.
+Instructions for the agent to run `.ts` files directly in Harper without a build step using Node.js's built-in type stripping.
 
 ## When to Use
 
-Use this skill when you want to write Harper Resources in TypeScript and have them execute directly in Node.js without an intermediate build or compilation step.
+Apply 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.
 
 ## How It Works
 
-1. **Verify Node.js Version**: Ensure you are using Node.js v22.6.0 or higher.
-2. **Name Files with `.ts`**: Create your resource files in the `resources/` directory with a `.ts` extension.
-3. **Use TypeScript Syntax**: Write your resource classes using standard TypeScript (interfaces, types, etc.).
-   ```typescript
-   import { Resource } from 'harper';
-   export class MyResource extends Resource {
-   	async get(): Promise<{ message: string }> {
-   		return { message: 'Running TS directly!' };
-   	}
-   }
-   ```
-4. **Use Explicit Extensions in Imports**: When importing other local modules, include the `.ts` extension: `import { helper } from './helper.ts'`.
-5. **Configure `config.yaml`**: Ensure `jsResource` points to your `.ts` files:
+1. **Ensure Node.js version**: Require Node.js 22.6 or later. Type stripping is unavailable on earlier versions.
+
+2. **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:
+
    ```yaml
    jsResource:
      files: 'resources/*.ts'
    ```
+
+3. **Use explicit `.ts` extensions in local imports**: Node's loader does not resolve `'./helper'` to `'./helper.ts'`, so always include the full extension:
+
+   ```typescript
+   import { helper } from './helper.ts';
+   ```
+
+4. **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.
+
+## Examples
+
+A complete Harper resource written in TypeScript, using imports from the `harper` package:
+
+```typescript
+import { type RequestTargetOrId, Resource, tables } from 'harper';
+
+export class MyResource extends Resource {
+	async get(target?: RequestTargetOrId): Promise<{ message: string }> {
+		return { message: 'Hello from TS' };
+	}
+}
+```
+
+Paired `config.yaml` entry loading the file via `jsResource`:
+
+```yaml
+jsResource:
+  files: 'resources/*.ts'
+```
+
+## Notes
+
+- No build step or transpiler is required — Harper runs `.ts` files directly.
+- Type imports (e.g., `import { type RequestTargetOrId }`) from the `harper` package work as usual.
+- Unsupported TypeScript features include: enums with runtime values, namespaces with runtime semantics, and anything requiring code transformation beyond simple type stripping.

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

@@ -9,6 +9,9 @@
 # Phase 3 flips 7 obvious 1:1 rules to mode: generate (automatic-apis,
 # querying-rest-apis, real-time-apps, checking-authentication, logging,
 # deploying-to-harper-fabric, caching). All others remain synthesized.
+# Phase 4 migrates schema-design-tooling and typescript-type-stripping to
+# mode: generate. creating-harper-apps stays synthesized pending dedicated
+# create-harper CLI documentation.
 
 rules:
   # ===========================================================================
@@ -27,7 +30,23 @@ rules:
     category: schema
     priority: 1
     order: 2
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/database/schema.md
+        section: 'Overview'
+        role: primary
+      - path: reference/v5/database/schema.md
+        section: 'Type Directives'
+        role: primary
+      - path: reference/v5/database/schema.md
+        section: 'Field Directives'
+        role: primary
+    must_cover:
+      - '@table'
+      - '@export'
+      - '@primaryKey'
+      - '@indexed'
+      - 'graphqlSchema'
 
   - rule: defining-relationships
     description: How to define and use relationships between tables in Harper using GraphQL.
@@ -178,7 +197,16 @@ rules:
     category: logic
     priority: 3
     order: 4
-    mode: synthesized
+    mode: generate
+    sources:
+      - path: reference/v5/components/javascript-environment.md
+        section: 'TypeScript Support'
+        role: primary
+    must_cover:
+      - '.ts'
+      - 'jsResource'
+      - 'Node.js 22.6'
+      - 'type stripping'
 
   - rule: caching
     description: How to implement integrated data caching in Harper from external sources.
@@ -256,3 +284,19 @@ rules:
       - 'console.log'
       - 'logger'
       - 'withTag('
+
+  - rule: load-env
+    description: How to load environment variables from .env files into a Harper application using the loadEnv plugin.
+    category: ops
+    priority: 4
+    order: 6
+    mode: generate
+    sources:
+      - path: reference/v5/environment-variables/overview.md
+        role: primary
+    must_cover:
+      - 'loadEnv'
+      - 'files'
+      - 'process.env'
+      - 'override'
+      - 'config.yaml'

package/package.json

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