@harperfast/template-react-ts-studio 1.11.3 → 1.11.5

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

@@ -7,8 +7,8 @@ metadata:
   mode: generate
   sources:
     - reference/v5/environment-variables/overview.md
-  sourceCommit: 42231db17c025a4a455e3d91875fad4084a01cb5
-  inputHash: fe610fc245226357
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: b4db5ede6b93d426
 ---
 
 # Load Environment Variables with loadEnv
@@ -17,18 +17,18 @@ Instructions for the agent to follow when loading environment variables from `.e
 
 ## When to Use
 
-Apply this rule when a Harper application needs to load secrets or configuration values from `.env` files into `process.env` at startup. Use it whenever hardcoding values must be avoided and environment-specific configuration must be supplied to Harper components.
+Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use `loadEnv` any time you need to load one or more `.env` files at application startup.
 
 ## How It Works
 
-1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as a top-level key. It is built into Harper and requires no installation.
+1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as the first entry in `config.yaml`. It is built into Harper and requires no installation.
 
    ```yaml
    loadEnv:
      files: '.env'
    ```
 
-2. **Place `loadEnv` first**: Always list `loadEnv` before any other components in `config.yaml` so that environment variables are available on `process.env` before dependent components start.
+2. **Place `loadEnv` first**: Harper is a single-process application. List `loadEnv` before all other components so that environment variables are available on `process.env` before dependent components start.
 
    ```yaml
    # config.yaml — loadEnv must come first
@@ -41,9 +41,9 @@ Apply this rule when a Harper application needs to load secrets or configuration
      files: './src/*.js'
    ```
 
-3. **Configure the `files` option**: Provide one or more paths or glob patterns pointing to the env files to load. This option is required.
+3. **Access loaded values in component code**: After `loadEnv` runs, all loaded values are available on `process.env` and shared across all components.
 
-4. **Set `override` if needed**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this and have loaded values win.
+4. **Control override behavior**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to make loaded values win instead.
 
    ```yaml
    loadEnv:
@@ -51,14 +51,17 @@ Apply this rule when a Harper application needs to load secrets or configuration
      override: true
    ```
 
-5. **Load multiple files when required**: Supply a list of files or a glob pattern. Files are loaded in the order specified.
+5. **Load multiple files**: Pass an array of paths or a glob pattern to `files`. Files are loaded in the order specified.
+
    ```yaml
    loadEnv:
      files:
        - '.env'
        - '.env.local'
    ```
-   or
+
+   or with a glob:
+
    ```yaml
    loadEnv:
      files: 'env-vars/*'
@@ -73,17 +76,23 @@ Apply this rule when a Harper application needs to load secrets or configuration
 
 ## Examples
 
-**Minimal setup — single `.env` file:**
+**Single file, default behavior:**
 
 ```yaml
+# config.yaml
 loadEnv:
   files: '.env'
+
+rest: true
+
+myApp:
+  files: './src/*.js'
 ```
 
-**Full `config.yaml` with load order, multiple files, and override:**
+**Multiple files with override:**
 
 ```yaml
-# config.yaml — loadEnv must come first
+# config.yaml
 loadEnv:
   files:
     - '.env'
@@ -96,16 +105,8 @@ myApp:
   files: './src/*.js'
 ```
 
-**Glob pattern:**
-
-```yaml
-loadEnv:
-  files: 'env-vars/*'
-```
-
 ## Notes
 
-- `loadEnv` is built into Harper — do not install it separately; only declare it in `config.yaml`.
-- Because Harper is a single-process application, variables loaded onto `process.env` are shared across all components.
-- Without `override: true`, variables already set in the shell or container environment will not be overwritten by values in `.env` files.
-- `files` is the only required option; omitting it will produce an invalid configuration.
+- `loadEnv` loads values into `process.env` for **application** code only — it does not configure Harper itself.
+- Harper's own instance-wide configuration is composed at startup **before** any component's `loadEnv` runs. Variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored. Set Harper configuration directly in the configuration file or export variables in the real process/container environment before Harper starts.
+- For production credentials, prefer the encrypted secrets store over a committed `.env` file. Secrets are also delivered to components via `process.env`.

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

@@ -14,8 +14,8 @@ metadata:
       reference/v5/resources/resource-api.md#`addTo(property: string, value:
       number)`
     - reference/v5/components/javascript-environment.md#Module Loading
-  sourceCommit: be709f9978319dcdb669c05d794effc82bcda8b7
-  inputHash: 3d2417fbff687c42
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: ace5c3f4a0ad4519
 ---
 
 # Programmatic Table Requests
@@ -24,11 +24,11 @@ Instructions for the agent to interact with Harper tables programmatically using
 
 ## When to Use
 
-Apply this rule when writing server-side Harper code that reads from or writes to tables directly — for example, in request handlers, background jobs, or SSR entry points — instead of going through the REST API. Use it whenever you need to construct queries with `conditions`, paginate results, select specific fields, or perform CRDT-safe mutations with `addTo`.
+Apply this rule when writing server-side code that reads from or writes to Harper tables directly — for example, in request handlers, background jobs, or SSR rendering — without going through the REST API. Use it whenever you need to construct queries with `conditions`, `select`, `sort`, or `search(`.
 
 ## How It Works
 
-1. **Import `tables`**: Import from the `harper` package. Each table defined in `schema.graphql` with `@table` is available as a named property.
+1. **Import `tables`**: Pull `tables` from the `harper` package. Each property on `tables` corresponds to a table defined in `schema.graphql`.
 
    ```javascript
    import { tables } from 'harper';
@@ -36,10 +36,9 @@ Apply this rule when writing server-side Harper code that reads from or writes t
    // same as: databases.data.Product
    ```
 
-2. **Define your schema**: Declare tables in `schema.graphql` using `@table` and `@primaryKey`.
+2. **Define your schema**: Declare tables with `@table` in `schema.graphql`. Each type becomes a property on `tables`.
 
    ```graphql
-   # schema.graphql
    type Product @table {
    	id: Long @primaryKey
    	name: String
@@ -47,57 +46,75 @@ Apply this rule when writing server-side Harper code that reads from or writes t
    }
    ```
 
-3. **Create and mutate records**: Use `create`, `patch`, `get`, and `update` on the table class.
+3. **Create and modify records**: Use `create`, `patch`, and `get` for basic CRUD.
 
    ```javascript
-   // Create a new record (id auto-generated)
    const created = await Product.create({ name: 'Shirt', price: 9.5 });
-
-   // Modify the record
    await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
-
-   // Retrieve by primary key
    const record = await Product.get(created.id);
    ```
 
-4. **Query with `search(` and `conditions`**: Pass a query object to `search()` to filter records. Iterate the async result.
+4. **Query with `search(`**: Pass a query object to `Product.search(query)`. It returns an async iterable.
 
    ```javascript
    const query = {
    	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
    };
    for await (const record of Product.search(query)) {
-   	// ...
+   	// process record
    }
    ```
 
-5. **Use `select` to shape results**: Pass a `select` array to return only specific properties, including nested relationship fields.
+5. **Build `conditions`**: Each condition object filters records. Nest conditions with `operator` for boolean logic.
+
+   | Property     | Description                                                                                                                                              |
+   | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `attribute`  | Property name, or array for chained/joined properties (e.g. `['brand', 'name']`)                                                                         |
+   | `value`      | The value to match                                                                                                                                       |
+   | `comparator` | `equals` (default), `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `starts_with`, `contains`, `ends_with`, `between`, `not_equal` |
+   | `conditions` | Nested conditions array                                                                                                                                  |
+   | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
+
+6. **Use `select`** to control which properties are returned. Accepts an array of property names, a string for a single property, or nested objects for relationships.
 
    ```javascript
-   const book = await Book.get({ id: 42, select: ['id', 'title', 'author'] });
-   book.author.name; // full related Author record
+   // Array of names
+   Product.search({ select: ['name', 'price'] });
 
-   // Partial related record
-   const book = await Book.get({
-   	id: 42,
-   	select: ['id', 'title', { name: 'author', select: ['name'] }],
-   });
+   // Nested relationship select
+   Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
-6. **Use `addTo` for concurrent-safe increments**: Call `addTo` on a mutable resource instance obtained via `update()`. This uses CRDT incrementation, safe across threads and nodes.
+   Special `select` values:
+   - `$id` — returns the primary key regardless of its name
+   - `$updatedtime` — returns the last-updated timestamp
+   - `$distance` — returns the computed distance when querying a vector index
+
+7. **Use `addTo`** for concurrent-safe numeric increments (CRDT incrementation, safe across threads and nodes).
 
    ```javascript
-   static async post(target, data) {
-     const record = await this.update(target.id);
-     record.addTo('quantity', -1); // decrement safely across nodes
-   }
+   const record = await Product.update(target.id);
+   record.addTo('quantity', -1);
    ```
 
-7. **Scope destructive operations carefully**: `update`, `patch`, and `delete` operate directly on stored data. Always use specific `conditions`, validate the affected set before writing, and gate behind authorization controls.
+8. **Apply `sort`, `limit`, and `offset`** for ordering and pagination. A `sort` attribute must be `@indexed`, or at least one `conditions` entry must be present. Pass `allowFullScan: true` to permit an unconditional ordered scan.
+
+   ```javascript
+   Product.search({
+   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+   	sort: { attribute: 'id' },
+   });
+   ```
+
+   | Sort property | Description                                                |
+   | ------------- | ---------------------------------------------------------- |
+   | `attribute`   | Property name (or array for chained relationship property) |
+   | `descending`  | Sort descending if `true` (default: `false`)               |
+   | `next`        | Secondary sort to resolve ties (same structure)            |
 
 ## Examples
 
-### Nested conditions query
+**Nested conditions with `or`:**
 
 ```javascript
 Product.search({
@@ -114,23 +131,25 @@ Product.search({
 });
 ```
 
-### Chained attribute reference (relationship join)
+**Chained attribute reference (relationship join):**
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-### Deep nested `select`
+**Deep nested `select` across multiple relationships:**
 
 ```javascript
-select: [
-	'id',
-	'name',
-	{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
-];
+Product.search({
+	select: [
+		'id',
+		'name',
+		{ name: 'segments', select: ['id', 'name', { name: 'client', select: ['id', 'name'] }] },
+	],
+});
 ```
 
-### SSR usage
+**SSR usage — read directly from `tables` in a render function:**
 
 ```typescript
 import { tables } from 'harper';
@@ -143,44 +162,9 @@ export async function render(url: string): Promise<string> {
 
 ## Notes
 
-### `conditions` comparator values
-
-| Comparator           | Description            |
-| -------------------- | ---------------------- |
-| `equals`             | Default equality match |
-| `greater_than`       | Strictly greater       |
-| `greater_than_equal` | Greater than or equal  |
-| `less_than`          | Strictly less          |
-| `less_than_equal`    | Less than or equal     |
-| `starts_with`        | String prefix match    |
-| `contains`           | String contains        |
-| `ends_with`          | String suffix match    |
-| `between`            | Range match            |
-| `not_equal`          | Inequality match       |
-
-### Query object options
-
-| Property                | Description                                                             |
-| ----------------------- | ----------------------------------------------------------------------- |
-| `conditions`            | Array of condition objects to filter records                            |
-| `operator`              | Top-level `and` (default) or `or` for the `conditions` array            |
-| `limit`                 | Maximum number of records to return                                     |
-| `offset`                | Number of records to skip (for pagination)                              |
-| `select`                | Properties to include in each returned record                           |
-| `sort`                  | Sort order object with `attribute`, `descending`, and `next` properties |
-| `explain`               | If `true`, returns conditions reordered as Harper will execute them     |
-| `enforceExecutionOrder` | If `true`, forces conditions to execute in the order supplied           |
-
-### `select` special properties
-
-- `$id` — Returns the primary key regardless of its name
-- `$updatedtime` — Returns the last-updated timestamp
-- `$distance` — Returns the computed distance from the target vector when the query uses a vector index
-
-### Relationship join behavior
-
-- Selecting a relationship **without** filtering on it behaves as a **LEFT JOIN** — records with no related row are still returned.
-- Adding a `conditions` entry on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN** — only records with a matching related row are returned.
-
-- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime instead of being bundled.
-- `tables`, `databases`, and other Harper APIs are the same live, process-wide objects regardless of whether accessed as globals or via `import { tables } from 'harper'`.
+- Scope destructive operations (`update`, `patch`, `delete`) with specific `conditions` and validate the affected set before writing. These operate on live data and are not easily reversible.
+- Sorting by a bare `@primaryKey` with no conditions raises `HdbError: <attribute> is not indexed and not combined with any other conditions`. Add an open-ended condition or pass `allowFullScan: true`.
+- Selecting a relationship field without filtering on it behaves as a **LEFT JOIN**. Adding a condition on a related attribute (e.g. `attribute: ['author', 'name']`) behaves as an **INNER JOIN**.
+- A to-many relationship resolves to an array; `await` the property before iterating when needed.
+- `tables` and `databases.data` reference the same live objects — a record written through one component is immediately visible to all others.
+- Keep `harper` external when bundling for SSR (e.g. `ssr: { external: ['harper'] }` in `vite.config`) so it resolves to the runtime.

package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md

@@ -5,17 +5,17 @@ metadata:
   mode: generate
   sources:
     - reference/v5/rest/querying.md
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 9f8c981a629ef606
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: d5ed0e937cd2d7e0
 ---
 
-# Querying REST APIs
+# Querying Harper REST APIs
 
-Instructions for the agent to filter, sort, select, and paginate Harper REST API collections using URL query parameters.
+Instructions for the agent to filter, sort, select, and paginate records using Harper's URL-based query language on REST collection endpoints.
 
 ## When to Use
 
-Apply 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)).
+Apply this rule when building or debugging REST API calls against Harper tables that require filtering by attribute values, comparison ranges, sorting, field selection, or result pagination. This rule also covers OR logic, grouping, and querying across related tables via dot-syntax joins. See [automatic-apis.md](automatic-apis.md) for how Harper exposes tables as REST endpoints.
 
 ## How It Works
 
@@ -26,21 +26,27 @@ Apply this rule when building or modifying code that queries Harper REST endpoin
    GET /Product/?category=software&inStock=true
    ```
 
-2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators directly in query parameter values.
+2. **Filter for null values**: Use `=null` as the value to match null or non-null records.
 
-   | Operator     | Meaning                                |
-   | ------------ | -------------------------------------- |
-   | `==`         | Equal                                  |
-   | `=lt=`       | Less than                              |
-   | `=le=`       | Less than or equal                     |
-   | `=gt=`       | Greater than                           |
-   | `=ge=`       | Greater than or equal                  |
-   | `=ne=`, `!=` | Not equal                              |
-   | `=ct=`       | Contains (strings)                     |
-   | `=sw=`       | Starts with (strings)                  |
-   | `=ew=`       | Ends with (strings)                    |
-   | `=`, `===`   | Strict equality (no type conversion)   |
-   | `!==`        | Strict inequality (no type conversion) |
+   ```
+   GET /Product/?discount=null
+   ```
+
+3. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in query parameters for range and string matching.
+
+   | Operator             | Meaning                                |
+   | -------------------- | -------------------------------------- |
+   | `==`                 | Equal                                  |
+   | `=lt=`               | Less than                              |
+   | `=le=`               | Less than or equal                     |
+   | `=gt=`               | Greater than                           |
+   | `=ge=`               | Greater than or equal                  |
+   | `=ne=`, `!=`         | Not equal                              |
+   | `=ct=`               | Contains (strings)                     |
+   | `=sw=`, `==<value>*` | Starts with (strings)                  |
+   | `=ew=`               | Ends with (strings)                    |
+   | `=`, `===`           | Strict equality (no type conversion)   |
+   | `!==`                | Strict inequality (no type conversion) |
 
    ```
    GET /Product/?price=gt=100
@@ -55,32 +61,52 @@ Apply this rule when building or modifying code that queries Harper REST endpoin
    GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
    ```
 
-3. **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.
+4. **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 for chaining.
 
    ```
    GET /Product/?price=gt=100&lt=200
    ```
 
-4. **Combine conditions with OR logic**: Use `|` instead of `&`.
+5. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit prefixes to force a type.
+
+   | Syntax                                    | Behavior                                    |
+   | ----------------------------------------- | ------------------------------------------- |
+   | `name==null`                              | Converts to `null`                          |
+   | `name==123`                               | Converts to number if attribute is untyped  |
+   | `name==true`                              | Converts to boolean if attribute is untyped |
+   | `name==number:123`                        | Explicit number conversion                  |
+   | `name==boolean:true`                      | Explicit boolean conversion                 |
+   | `name==string:some%20text`                | Keep as string with URL decode              |
+   | `name==date:2024-01-05T20%3A07%3A27.955Z` | Explicit Date conversion                    |
+
+   For strict operators (`=`, `===`, `!==`), no automatic type conversion is applied.
+
+6. **Combine conditions with OR logic**: Use `|` instead of `&` to express OR between conditions.
 
    ```
    GET /Product/?rating=5|featured=true
    ```
 
-5. **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 `]`.
+7. **Group conditions**: Use parentheses or square brackets to control evaluation order. Prefer square brackets when building queries from user input, since `[` and `]` are safely URI-encoded.
 
    ```
    GET /Product/?rating=5|(price=gt=100&price=lt=200)
    GET /Product/?rating=5&[tag=fast|tag=scalable|tag=efficient]
    ```
 
-   Construct grouped queries from JavaScript:
+   Build grouped queries in JavaScript:
 
    ```javascript
    let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;
    ```
 
-6. **Select specific properties with `select(`**: Use `select()` to control which fields are returned.
+   Nest groups for complex conditions:
+
+   ```
+   GET /Product/?price=lt=100|[rating=5&[tag=fast|tag=scalable|tag=efficient]&inStock=true]
+   ```
+
+8. **Select specific properties with `select(`**: Append `select(...)` as a query function separated by `&` to control which fields are returned.
 
    | Syntax                                 | Returns                                     |
    | -------------------------------------- | ------------------------------------------- |
@@ -95,108 +121,109 @@ Apply this rule when building or modifying code that queries Harper REST endpoin
    GET /Product/?brand.name=Microsoft&select(name,brand{name})
    ```
 
-7. **Limit results with `limit(`**: Use `limit(end)` or `limit(start,end)` to paginate.
+9. **Paginate results with `limit(`**: Use `limit(end)` or `limit(start,end)` to restrict the number of records returned.
 
    ```
    GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
    GET /Product/?rating=gt=3&limit(10,30)
    ```
 
-8. **Sort results with `sort(`**: Use `sort(property)` or `sort(+property,-property,...)`. Prefix `+` or no prefix = ascending; `-` = descending.
+10. **Sort results with `sort(`**: Use `sort(property)` or `sort(+property,-property,...)` to order results. Prefix `+` or no prefix = ascending; `-` = descending.
 
-   ```
-   GET /Product/?rating=gt=3&sort(+name)
-   GET /Product/?sort(+rating,-price)
-   ```
+    ```
+    GET /Product/?rating=gt=3&sort(+name)
+    GET /Product/?sort(+rating,-price)
+    ```
 
-9. **Query across relationships**: Use dot-syntax to filter by related table attributes. Relationships must be defined in the schema using `@relation`.
+11. **Query across relationships using dot-syntax**: Filter on related table attributes using dot-chained property names. Relationships must be defined in the schema with `@relationship`.
 
-   ```
-   GET /Product/?brand.name=Microsoft
-   GET /Brand/?products.name=Keyboard
-   ```
+    ```
+    GET /Product/?brand.name=Microsoft
+    GET /Brand/?products.name=Keyboard
+    ```
 
-   Use `select()` to include relationship attributes in the response (they are not included by default):
+    Use `select()` to include relationship attributes in the response (they are excluded by default):
 
-   ```
-   GET /Product/?brand.name=Microsoft&select(name,brand{name})
-   ```
+    ```
+    GET /Product/?brand.name=Microsoft&select(name,brand)
+    GET /Product/?brand.name=Microsoft&select(name,brand{name})
+    ```
 
-10. **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.
+12. **Access a specific property by URL**: Append `.propertyName` to a record ID in the URL path. Only works for properties declared in the schema.
     ```
     GET /MyTable/123.propertyName
     ```
 
 ## Examples
 
-**Range filter with select and limit:**
+**Range filter with select and limit**:
 
 ```
 GET /Product/?category=software&price=gt=100&price=lt=200&select(name,price)&limit(20)
 ```
 
-**Sort descending with multiple fields:**
+**Sort and paginate**:
 
 ```
-GET /Product/?sort(+rating,-price)
+GET /Product/?rating=gt=3&sort(+rating,-price)&limit(10,30)
 ```
 
-**OR logic with grouping:**
+**OR with grouping**:
 
 ```
 GET /Product/?price=lt=100|[rating=5&[tag=fast|tag=scalable|tag=efficient]&inStock=true]
 ```
 
-**Relationship join with nested select:**
-
-```
-GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
-```
-
-**Schema defining a relationship for join queries:**
+**Join query with nested select** — schema first:
 
 ```graphql
 type Product @table @export {
 	id: Long @primaryKey
 	name: String
 	brandId: Long @indexed
-	brand: Brand @relation(from: "brandId")
+	brand: Brand @relationship(from: "brandId")
 }
 type Brand @table @export {
 	id: Long @primaryKey
 	name: String
-	products: [Product] @relation(to: "brandId")
+	products: [Product] @relationship(to: "brandId")
 }
 ```
 
-**Many-to-many relationship query:**
+Then query:
+
+```
+GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
+```
+
+**Many-to-many relationship** — schema:
 
 ```graphql
 type Product @table @export {
 	id: Long @primaryKey
 	name: String
 	resellerIds: [Long] @indexed
-	resellers: [Reseller] @relation(from: "resellerId")
+	resellers: [Reseller] @relationship(from: "resellerIds")
 }
 ```
 
+Query:
+
 ```
 GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
 ```
 
-**Type conversion with explicit prefix:**
+**Date range with URL-encoded colons**:
 
 ```
-GET /Product/?price==number:123
-GET /Product/?active==boolean:true
-GET /Product/?listDate==date:2024-01-05T20%3A07%3A27.955Z
+GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
 ```
 
 ## Notes
 
-- 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.
-- 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.
-- FIQL comparators (`==`, `!=`, `=gt=`, etc.) apply automatic type conversion based on value syntax or schema-declared type. Strict operators (`=`, `===`, `!==`) skip automatic type conversion.
-- 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.
-- The array order of foreign key values in many-to-many relationships is preserved when resolving the relationship.
-- See [automatic-apis.md](automatic-apis.md) for how Harper tables are automatically exposed as REST endpoints.
+- All filtered attributes must be indexed unless at least one other attribute in the same query is indexed.
+- Null queries (`?attr=null`) require indexes created after null indexing support was added. Rebuild existing indexes (remove and re-add) to enable null queries on them.
+- When selecting a related attribute without filtering on it, the join behaves as a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+- The array order of foreign key values (e.g., `resellerIds`) is preserved when resolving many-to-many relationships.
+- Square brackets (`[`, `]`) are preferred over parentheses for grouping when constructing queries programmatically, because standard URI encoding safely encodes them.
+- `directURLMapping: true` can be set on a resource to change URL path handling semantics; see your schema configuration for details.