@harperfast/template-react-ts-studio 1.12.3 → 1.12.4

package/.agents/skills/harper-best-practices/AGENTS.md

@@ -18,14 +18,14 @@ Use this skill when you need to define new data structures or modify existing on
 2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harper/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
 3. **Define Relationships**: Link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
 4. **Enable Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. **Important**: REST endpoints also require `rest: true` in `config.yaml` — without it, `@export`ed tables will not respond to HTTP requests. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
-   - `GET /{TableName}`: Describes the schema itself.
+   - `GET /{TableName}`: Describes the resource itself — table, database, and declared attributes. No trailing slash.
    - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
-   - `GET /{TableName}/{id}`: Retrieves a single record by its ID.
-   - `POST /{TableName}/`: Creates a new record.
-   - `PUT /{TableName}/{id}`: Updates an existing record.
-   - `PATCH /{TableName}/{id}`: Performs a partial update on a record.
-   - `DELETE /{TableName}/`: Deletes all records or filtered records.
-   - `DELETE /{TableName}/{id}`: Deletes a single record by its ID.
+   - `GET /{TableName}/{id}`: Retrieves a single record by its primary key.
+   - `POST /{TableName}/`: Creates a record and returns `201` with the Harper-assigned primary key in the `Location` response header (the bare key, not a URL). **The trailing slash is required** — `POST /{TableName}` returns `404`, and `POST /{TableName}/{id}` returns `405`.
+   - `PUT /{TableName}/{id}`: Creates **or replaces** the record at `{id}` (upsert). **Properties omitted from the body are removed** — send the complete record, or use `PATCH` to change a subset. Three exceptions survive the replacement: an `@updatedTime` attribute is re-stamped with the time of the write, a `@createdTime` attribute keeps its original value, and the primary key is forced to match the `{id}` in the URL, so a mismatched key in the body cannot create a second record.
+   - `PATCH /{TableName}/{id}`: Merges the request body into the existing record, preserving unspecified properties. The merge is **shallow** — a nested object in the body replaces the stored one wholesale rather than being deep-merged.
+   - `DELETE /{TableName}/{id}`: Deletes a single record by its primary key.
+   - `DELETE /{TableName}/`: Deletes every record matching the query parameters. **With no query parameters it matches — and deletes — every record in the table.** Always pass a filter unless emptying the table is the intent.
 5. **Consider Table Extensions**: If you are going to [extend the table](./extending-tables.md) in your resources, then do not `@export` the table from the schema.
 
 #### Examples
@@ -1241,207 +1241,100 @@ Instructions for the agent to handle user authentication, sessions, and JWT toke
 
 #### When to Use
 
-Apply this rule when implementing login/logout flows, protecting Resource endpoints by checking the current user, issuing or refreshing JWT tokens, or configuring token expiry in Harper. Use it whenever a custom Resource needs to authenticate callers or mint credentials for downstream consumers. See [custom-resources.md](custom-resources.md) for the broader Resource authoring context.
+Apply this rule when implementing login/logout flows, reading the current authenticated user, issuing or refreshing JWT tokens, or minting scoped tokens from a custom Resource. Use it whenever a Resource must gate behavior on identity or credentials. See [custom-resources.md](custom-resources.md) for the broader Resource authoring model.
 
 #### How It Works
 
-1. **Check the current authenticated user**: Call `getCurrentUser()` inside any Resource method. It returns the user object (with `username`, `role`, and `role.permission`) or `undefined` if unauthenticated. Guard endpoints by returning a 401 when no user is present.
+##### 1. Reading the Current Authenticated User
 
-   ```javascript
-   async get(target) {
-     const user = this.getCurrentUser();
-     if (!user) return new Response(null, { status: 401 });
-     return { username: user.username, role: user.role };
-   }
-   ```
-
-2. **Enable sessions before using login/logout**: Set `authentication.enableSessions: true` in `harperdb-config.yaml`. Without this, `context.login` and `context.session` are unavailable.
-
-3. **Implement login via `getContext()`**: Call `this.getContext()` to obtain the request context, then call `context.login(username, password)` to verify credentials and establish a session cookie.
-
-   ```javascript
-   export class SignIn extends Resource {
-   	async post(_target, data) {
-   		const context = this.getContext();
-   		try {
-   			await context.login(data.username, data.password);
-   		} catch {
-   			return new Response('Invalid credentials', { status: 403 });
-   		}
-   		return new Response('Logged in', { status: 200 });
-   	}
-   }
-   ```
-
-4. **Implement logout**: Delete the session via `context.session.delete(context.session.id)`.
-
-   ```javascript
-   export class SignOut extends Resource {
-   	async post() {
-   		const context = this.getContext();
-   		if (!context.session) return new Response(null, { status: 401 });
-   		await context.session.delete(context.session.id);
-   		return new Response('Logged out', { status: 200 });
-   	}
-   }
-   ```
+**In an instance method**, call `getCurrentUser()` to get the user associated with the current request, or `undefined` if unauthenticated. The returned object exposes `username`, `role`, and `role.permission` flags.
 
-   Cookie-based sessions are intended for browser clients. For non-browser clients, use JWT issuance (steps below).
+**In a static verb**, read the user from the `context` argument instead — `context.user`:
 
-5. **Create authentication tokens**: Call `create_authentication_tokens` with credentials. No `Authorization` header is required for this operation.
+```javascript
+static async get(_target, context) {
+    const user = context?.user;
+    if (!user) return new Response(null, { status: 401 });
+    return { username: user.username, role: user.role };
+}
+```
 
-   ```json
-   {
-   	"operation": "create_authentication_tokens",
-   	"username": "username",
-   	"password": "password"
-   }
-   ```
+##### 2. Reading the Full Context
 
-   Response:
+**In an instance method**, call `getContext()` to retrieve the current context, which includes:
 
-   ```json
-   {
-   	"operation_token": "<jwt-operation-token>",
-   	"refresh_token": "<jwt-refresh-token>"
-   }
-   ```
+- `user` — User object with username, role, and authorization information
+- `transaction` — The current transaction
 
-6. **Use the operation token**: Pass it as a `Bearer` token in the `Authorization` header on subsequent requests.
+**In a static verb**, the context is the trailing argument:
 
-   ```bash
-   curl --location --request POST 'http://localhost:9925' \
-     --header 'Content-Type: application/json' \
-     --header 'Authorization: Bearer <operation_token>' \
-     --data-raw '{
-         "operation": "search_by_hash",
-         "schema": "dev",
-         "table": "dog",
-         "hash_values": [1],
-         "get_attributes": ["*"]
-     }'
-   ```
+- `(target, context)` for `get`/`delete`
+- `(target, data, context)` for `put`/`patch`/`post`
 
-7. **Refresh an expired operation token**: When the `operation_token` expires, use `refresh_operation_token` and pass the `refresh_token` as `Bearer <refresh_token>`.
+When triggered by HTTP, the context also exposes `url`, `method`, `headers`, `responseHeaders`, `pathname`, `host`, `ip`, `body`, `data`, `lastModified`, and `requestContext`.
 
-   ```bash
-   curl --location --request POST 'http://localhost:9925' \
-     --header 'Content-Type: application/json' \
-     --header 'Authorization: Bearer <refresh_token>' \
-     --data-raw '{
-       "operation": "refresh_operation_token"
-     }'
-   ```
+##### 3. Handling Sessions and Login
 
-   Response:
+Enable sessions in `harper-config.yaml`:
 
-   ```json
-   {
-   	"operation_token": "<new-jwt-operation-token>"
-   }
-   ```
-
-   When both tokens have expired, call `create_authentication_tokens` again with username and password.
+```yaml
+authentication:
+  enableSessions: true
+```
 
-8. **Mint scoped tokens for limited access**: A super user can embed an inline role in `create_authentication_tokens` using the same `permission` structure as `add_role`. Include `expires_in` to control lifetime. Do not include a `password` field. The `username` is attribution only and must not match an existing user.
+Use `context.login` in a static `post` verb to verify credentials and establish a session cookie:
 
-   ```json
-   {
-   	"operation": "create_authentication_tokens",
-   	"username": "reporting-service",
-   	"role": {
-   		"permission": {
-   			"operations": ["read_only"],
-   			"dev": {
-   				"tables": {
-   					"dog": {
-   						"read": true,
-   						"insert": false,
-   						"update": false,
-   						"delete": false,
-   						"attribute_permissions": []
-   					}
-   				}
-   			}
-   		}
-   	},
-   	"expires_in": "7d"
-   }
-   ```
-
-   Key constraints for scoped tokens:
-   - No refresh token is issued; no user record is created.
-   - Scoped tokens cannot be revoked before expiry — choose short `expires_in` values.
-   - `super_user` and `cluster_user` are always forced to `false` in the embedded role.
-   - In mixed-version clusters, only nodes with scoped-token support accept these tokens; older nodes return 401.
+```javascript
+export class SignIn extends Resource {
+	static async post(_target, data, context) {
+		const { username, password } = (await data) ?? {};
+		try {
+			await context.login(username, password);
+		} catch {
+			return new Response('Invalid credentials', { status: 403 });
+		}
+		return new Response('Logged in', { status: 200 });
+	}
+}
 
-9. **Issue tokens from a custom Resource using `server.operation`**: Import `server` from `harper` and call `server.operation()` to mint tokens programmatically. Pass `true` as the **third argument** to run the operation as the current authenticated user; omit it when supplying credentials directly.
+export class SignOut extends Resource {
+	static async post(_target, _data, context) {
+		if (!context?.session?.user) return new Response(null, { status: 401 });
+		await context.session.update({ user: null });
+		return new Response('Logged out', { status: 200 });
+	}
+}
+```
 
-   ```javascript
-   import { Resource, server } from 'harper';
-
-   export class IssueTokens extends Resource {
-   	static async get(_target, context) {
-   		const { operation_token, refresh_token } = await server.operation(
-   			{ operation: 'create_authentication_tokens' },
-   			context,
-   			true,
-   		);
-   		return { operation_token, refresh_token };
-   	}
+- `context.login(username, password)` verifies credentials and sets the session cookie on success.
+- To end a session, call `context.session.update({ user: null })` — `update` is the session's only mutator.
+- `context.session` is an empty object (not `undefined`) when sessions are enabled and no session cookie is present; test `context?.session?.user` to detect an established session.
+- Cookie-based sessions are for browser clients. For non-browser clients, use JWT issuance.
 
-   	static async post(_target, data) {
-   		const { username, password } = await data;
-   		if (!username || !password) {
-   			return new Response('username and password required', { status: 400 });
-   		}
-   		const { operation_token, refresh_token } = await server.operation({
-   			operation: 'create_authentication_tokens',
-   			username,
-   			password,
-   		});
-   		return { operation_token, refresh_token };
-   	}
-   }
+##### 4. Creating Authentication Tokens
 
-   export class RefreshJWT extends Resource {
-   	static async post(_target, data) {
-   		const { refresh_token } = await data;
-   		if (!refresh_token) {
-   			return new Response('refresh_token required', { status: 400 });
-   		}
-   		const { operation_token } = await server.operation({
-   			operation: 'refresh_operation_token',
-   			refresh_token,
-   		});
-   		return { operation_token };
-   	}
-   }
-   ```
+Call `create_authentication_tokens` with credentials in the body — no `Authorization` header is required when `username` and `password` are supplied:
 
-10. **Configure token expiry**: Set timeouts in `harper-config.yaml` under the `authentication` section. Values follow the `jsonwebtoken` duration string format (e.g., `1d`, `12h`, `60m`).
+```json
+{
+	"operation": "create_authentication_tokens",
+	"username": "username",
+	"password": "password"
+}
+```
 
-    ```yaml
-    authentication:
-      operationTokenTimeout: 1d # Default: 1 day
-      refreshTokenTimeout: 30d # Default: 30 days
-    ```
+Response:
 
-#### Examples
+```json
+{
+	"operation_token": "<jwt-operation-token>",
+	"refresh_token": "<jwt-refresh-token>"
+}
+```
 
-##### Full JWT flow via cURL
+Pass the `operation_token` as a `Bearer` token on subsequent requests:
 
 ```bash
-# Step 1: Create tokens
-curl --location --request POST 'http://localhost:9925' \
-  --header 'Content-Type: application/json' \
-  --data-raw '{
-      "operation": "create_authentication_tokens",
-      "username": "username",
-      "password": "password"
-  }'
-
-# Step 2: Use operation token
 curl --location --request POST 'http://localhost:9925' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <operation_token>' \
@@ -1452,8 +1345,13 @@ curl --location --request POST 'http://localhost:9925' \
       "hash_values": [1],
       "get_attributes": ["*"]
   }'
+```
 
-# Step 3: Refresh when operation token expires
+##### 5. Refreshing the Operation Token
+
+When the `operation_token` expires, pass the `refresh_token` as `Bearer <refresh_token>` and call `refresh_operation_token`:
+
+```bash
 curl --location --request POST 'http://localhost:9925' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <refresh_token>' \
@@ -1462,14 +1360,138 @@ curl --location --request POST 'http://localhost:9925' \
   }'
 ```
 
-##### Session-based login/logout Resource
+Response:
+
+```json
+{
+	"operation_token": "<new-jwt-operation-token>"
+}
+```
+
+When both tokens have expired, call `create_authentication_tokens` again with username and password.
+
+##### 6. Minting Scoped Tokens
+
+A `super_user` can mint a scoped token with embedded permissions using `create_authentication_tokens` with an inline `role`. The minter must be authenticated; no `password` may be included in the body. Use `add_role`-style `permission` structure:
+
+```json
+{
+	"operation": "create_authentication_tokens",
+	"username": "reporting-service",
+	"role": {
+		"permission": {
+			"operations": ["read_only"],
+			"dev": {
+				"tables": {
+					"dog": {
+						"read": true,
+						"insert": false,
+						"update": false,
+						"delete": false,
+						"attribute_permissions": []
+					}
+				}
+			}
+		}
+	},
+	"expires_in": "7d"
+}
+```
+
+Authenticate the mint request with Basic Authentication or an existing `super_user` `operation_token`:
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Basic <base64 of super_user:password>' \
+  --data-raw '{
+      "operation": "create_authentication_tokens",
+      "username": "reporting-service",
+      "role": { "permission": { "operations": ["read_only"] } },
+      "expires_in": "7d"
+  }'
+```
+
+Key constraints for scoped tokens:
+
+- `username` is attribution only and must not name an existing user.
+- No refresh token is issued; no user record is created.
+- Scoped tokens cannot be revoked before expiry — choose `expires_in` carefully and prefer short lifetimes.
+- `super_user` and `cluster_user` are always forced to `false` in the embedded role.
+- In **mixed-version** clusters, only nodes with scoped-token support accept these tokens; older nodes reject them with 401.
+
+##### 7. Issuing Tokens from a Custom Resource
+
+Use `server.operation()` to mint tokens programmatically inside a Resource. Pass `authorize: true` as the **third argument** when the operation should run as the current authenticated user:
+
+```javascript
+import { Resource, server } from 'harper';
+
+export class IssueTokens extends Resource {
+	static async get(_target, context) {
+		// Issue tokens for the current authenticated user
+		const { operation_token, refresh_token } = await server.operation(
+			{ operation: 'create_authentication_tokens' },
+			context,
+			true, // third argument: authorize as current user
+		);
+		return { operation_token, refresh_token };
+	}
+
+	static async post(_target, data) {
+		// Issue tokens from credentials supplied in the body
+		const { username, password } = await data;
+		if (!username || !password) {
+			return new Response('username and password required', { status: 400 });
+		}
+		const { operation_token, refresh_token } = await server.operation({
+			operation: 'create_authentication_tokens',
+			username,
+			password,
+		});
+		return { operation_token, refresh_token };
+	}
+}
+
+export class RefreshJWT extends Resource {
+	static async post(_target, data) {
+		const { refresh_token } = await data;
+		if (!refresh_token) {
+			return new Response('refresh_token required', { status: 400 });
+		}
+		const { operation_token } = await server.operation({
+			operation: 'refresh_operation_token',
+			refresh_token,
+		});
+		return { operation_token };
+	}
+}
+```
+
+Omit the third argument (or pass `false`) when the operation supplies its own credentials.
+
+##### 8. Configuring Token Expiry
+
+Set timeouts in `harper-config.yaml` under the `authentication` section:
+
+```yaml
+authentication:
+  operationTokenTimeout: 1d # Default: 1 day
+  refreshTokenTimeout: 30d # Default: 30 days
+```
+
+Valid duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`). The `expires_in` field on scoped token minting accepts the same format.
+
+#### Examples
+
+##### Full Sign-In / Sign-Out Resource
 
 ```javascript
 export class SignIn extends Resource {
-	async post(_target, data) {
-		const context = this.getContext();
+	static async post(_target, data, context) {
+		const { username, password } = (await data) ?? {};
 		try {
-			await context.login(data.username, data.password);
+			await context.login(username, password);
 		} catch {
 			return new Response('Invalid credentials', { status: 403 });
 		}
@@ -1478,23 +1500,44 @@ export class SignIn extends Resource {
 }
 
 export class SignOut extends Resource {
-	async post() {
-		const context = this.getContext();
-		if (!context.session) return new Response(null, { status: 401 });
-		await context.session.delete(context.session.id);
+	static async post(_target, _data, context) {
+		if (!context?.session?.user) return new Response(null, { status: 401 });
+		await context.session.update({ user: null });
 		return new Response('Logged out', { status: 200 });
 	}
 }
 ```
 
+##### Reading the Current Authenticated User in a Static Verb
+
+```javascript
+static async get(_target, context) {
+    const user = context?.user;
+    if (!user) return new Response(null, { status: 401 });
+    return { username: user.username, role: user.role };
+}
+```
+
+##### Minting Tokens via cURL
+
+```bash
+curl --location --request POST 'http://localhost:9925' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+      "operation": "create_authentication_tokens",
+      "username": "username",
+      "password": "password"
+  }'
+```
+
 #### Notes
 
-- JWT authentication is **preferred over Basic Auth** when you want to avoid sending credentials on every request, when the client can store tokens, or when making multiple sequential requests. For simple or server-to-server scenarios, use Basic Authentication.
+- JWT authentication is **preferred over Basic Auth** when you want to avoid sending credentials on every request, your client can store tokens, or you have multiple sequential requests. For simple or **server-to-server** scenarios, use **Basic Authentication**.
 - Always use **HTTPS** in production to protect tokens in transit.
 - Treat tokens like passwords. If a token is compromised, it remains valid until expiry — use shorter `operationTokenTimeout` values in high-security environments.
-- `enableSessions` must be `true` in config before `context.login` or `context.session` will work.
-- The `third argument` (`true`) to `server.operation` controls whether the operation runs as the current authenticated user. Omit it when the operation body supplies its own credentials.
-- Scoped tokens have a 12KB limit when encoded into an `Authorization` header.
+- `context.login` and `context.session` require `enableSessions: true` in `harperdb-config.yaml`; they are for browser clients only.
+- The `server.operation()` third argument (`authorize: true`) attributes the operation to — and permission-checks against — the current authenticated user. Omit it when supplying credentials directly in the operation body.
+- In **mixed-version** clusters, scoped tokens are only accepted by nodes that support them; older nodes return 401.
 
 ## 3. Logic & Extension
 
@@ -1504,11 +1547,11 @@ Instructions for the agent to follow when defining custom REST endpoints with Ja
 
 #### When to Use
 
-Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when a specific URL shape is required.
+Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed resource or when a specific URL shape is required.
 
 #### How It Works
 
-1. **Import `Resource` from `harper`**: Always import from the `harper` package rather than relying on globals.
+1. **Import `Resource` from the `harper` package**: Always import explicitly rather than relying on globals.
 
    ```javascript
    import { tables, Resource } from 'harper';
@@ -1526,7 +1569,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-3. **Use `async` static methods for external calls**: Await fetch or other async operations inside `static` handlers.
+3. **Use `async` static methods to call external services**: Return or forward the response directly.
 
    ```javascript
    export class MyExternalData extends Resource {
@@ -1544,7 +1587,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-4. **Export the class to create an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
+4. **Export the class to expose it as an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
 
    | Export form                                 | URL             | Notes                                                           |
    | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
@@ -1555,12 +1598,17 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
    | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
 
-   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+5. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the resource class.
 
-5. **Declare path parameters with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+   ```javascript
+   server.resources.set('my-path', Foo);
+   ```
+
+6. **Declare dynamic path segments with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
 
    ```javascript
    export class Widget extends Resource {
+   	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
    	static path = '/widget/:id/action/:action';
    	static get(target) {
    		return { id: target.id, action: target.action };
@@ -1568,22 +1616,11 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-   A `static path` takes precedence over the export name. A leading `/` makes the path root-relative (top-level). A leading `./` or bare name resolves relative to the component directory.
-
-6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` when the path cannot be known at export time.
-
-   ```javascript
-   server.resources.set('my-path', Foo);
-   ```
-
-7. **Optionally source a table from a custom resource**: Use the resource as a caching layer for a local table.
-   ```javascript
-   tables.MyCache.sourcedFrom(MyExternalData);
-   ```
+7. **Resolve path precedence correctly**: Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats a `:param`, which beats a `*` wildcard, compared left to right.
 
 #### Examples
 
-##### External API wrapper with GET and PUT
+**Wrapping an external API and using it as a cache source:**
 
 ```javascript
 import { tables, Resource } from 'harper';
@@ -1606,19 +1643,9 @@ export class MyExternalData extends Resource {
 tables.MyCache.sourcedFrom(MyExternalData);
 ```
 
-##### Path parameters with `static path`
+**Catch-all wildcard path:**
 
 ```javascript
-import { Resource } from 'harper';
-
-export class Widget extends Resource {
-	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
-	static path = '/widget/:id/action/:action';
-	static get(target) {
-		return { id: target.id, action: target.action };
-	}
-}
-
 export class Files extends Resource {
 	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
 	static path = '/files/*rest';
@@ -1628,28 +1655,27 @@ export class Files extends Resource {
 }
 ```
 
-##### Programmatic registration
+**Root-relative fixed route:**
 
 ```javascript
-import { Resource } from 'harper';
-
-export class Foo extends Resource {
+export class AcmeChallenge extends Resource {
+	static path = '/.well-known/acme-challenge/:token';
 	static get(target) {
-		return { data: doSomething() };
+		return { token: target.token };
 	}
 }
-
-server.resources.set('my-path', Foo);
 ```
 
 #### Notes
 
-- A bare `*` wildcard (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
-- Resolution order: exact/static paths always win over parameterized ones. Among parameterized routes, more specific paths win — a literal segment beats `:param`, which beats `*`, compared left to right.
-- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
-- If a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
+- URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
+- A leading `/` in `static path` makes the path root-relative (top-level), independent of the file's location.
+- A leading `./` or a bare name in `static path` resolves relative to the component directory.
+- A bare `*` (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
+- `static path` takes precedence over the export name when both are present.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as URI templates.
+- When a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
 - Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
-- Harper runs as a single process — `tables`, `databases`, and other APIs are the same live, process-wide objects regardless of which component accesses them.
 
 ### 3.2 Extending Tables
 
@@ -1757,23 +1783,25 @@ if (!authorized) {
 
 ### 3.3 Programmatic Table Requests
 
-Instructions for the agent to interact with Harper tables programmatically using the `tables` object, including querying, transactions, and module integration.
+Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
 
 #### When to Use
 
-Apply this rule when writing server-side Harper component code that reads from or writes to tables directly — bypassing REST endpoints — such as in request handlers, background jobs, timers, or SSR rendering. Use it whenever you need to construct queries with `conditions`, manage transactions explicitly, or perform CRDT-safe mutations.
+Apply this rule when writing server-side Harper component code that reads from or writes to tables directly — for example, in HTTP handlers, background jobs, timers, or SSR render functions. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, `limit`, or `offset`, or when you need explicit transaction control via `transaction()`.
 
 #### How It Works
 
-1. **Import `tables` from `harper`**: Access all tables in the default `data` database via the `tables` object. Each table defined with `@table` in `schema.graphql` is a property.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. Each property is the table class implementing the Resource API.
 
    ```javascript
-   import { tables } from 'harper';
+   import { tables, transaction } from 'harper';
    const { Product } = tables;
-   // same as: databases.data.Product
+   // equivalent to: databases.data.Product
    ```
 
-2. **Define your schema with `@table`**: Tables must be declared in `schema.graphql`. Use `@indexed` on attributes you intend to sort or filter efficiently.
+   For standalone components, run `npm link harper` so imports resolve to the live runtime.
+
+2. **Define your schema with `@table`**: Tables must be declared in `schema.graphql`. Mark attributes you intend to sort or filter on with `@indexed`.
 
    ```graphql
    type Product @table {
@@ -1783,7 +1811,7 @@ Apply this rule when writing server-side Harper component code that reads from o
    }
    ```
 
-3. **Use `search(` to query records**: Pass a Query object to `search(`. Iterate results with `for await`.
+3. **Query records with `search(`**: Pass a Query object to `search(`. Iterate results with `for await`.
 
    ```javascript
    const query = {
@@ -1794,7 +1822,7 @@ Apply this rule when writing server-side Harper component code that reads from o
    }
    ```
 
-4. **Build `conditions` arrays to filter**: Each condition object supports these properties:
+4. **Build `conditions`**: Each condition object supports these properties:
 
    | Property     | Description                                                                                                                                              |
    | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1804,87 +1832,79 @@ Apply this rule when writing server-side Harper component code that reads from o
    | `conditions` | Nested conditions array                                                                                                                                  |
    | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
 
-5. **Apply `select` to shape results**: Return only the fields you need. Supports arrays, nested relationship selects, and special properties.
+5. **Control result shape with `select`**: Pass an array of property names, a single string, or nested objects for relationships.
 
    ```javascript
-   // Array of fields
+   // Scalar fields only
    Product.search({ select: ['name', 'price'] });
 
-   // Nested relationship select
+   // Partial related record
    Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
    Special `select` values: `$id`, `$updatedtime`, `$distance`.
 
-6. **Apply `sort` with an `@indexed` attribute**: Harper uses an index to provide sort order. Sort by an `@indexed` attribute without requiring a condition, or provide at least one condition when sorting by a non-indexed attribute.
+6. **Paginate with `limit` and `offset`**:
 
    ```javascript
-   // Sort by primary key with an open-ended condition to avoid scan error
-   Product.search({
-   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
-   	sort: { attribute: 'id' },
-   });
+   Product.search({ conditions: [...], limit: 20, offset: 40 });
    ```
 
-   Sort object properties:
+7. **Sort with `sort`**: The `sort` object accepts `attribute`, `descending` (default `false`), and `next` for tie-breaking. Harper uses an index for sort order — the sort `attribute` must be `@indexed`, **or** at least one entry in `conditions` must be present.
 
-   | 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)          |
+   Sorting by a non-indexed attribute with zero conditions raises:
 
-7. **Use `limit` and `offset` for pagination**:
+   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+
+   Note: `@primaryKey` alone is treated as not indexed for sort purposes. To scan the whole table in primary-key order, add an open-ended condition:
 
    ```javascript
-   Product.search({ conditions: [...], limit: 20, offset: 40 });
+   Product.search({
+   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+   	sort: { attribute: 'id' },
+   });
    ```
 
-8. **Use `explain` and `enforceExecutionOrder` for debugging**:
+   Alternatively, pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
+
+8. **Debug query planning with `explain` and `enforceExecutionOrder`**:
    - `explain: true` — returns conditions reordered as Harper will execute them.
    - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling automatic re-ordering.
 
 9. **Use `addTo` for concurrent-safe numeric updates**: `addTo` uses 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(32);
+   record.addTo('quantity', -1);
    ```
 
-10. **Wrap background work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural transaction context.
+10. **Wrap background work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a request context. Always `await` the call and `catch` errors.
 
     ```javascript
-    import { tables } from 'harper';
-    const { MyTable } = tables;
-
-    if (isMainThread) {
-    	setInterval(async () => {
-    		let data = await (await fetch('https://example.com/data')).json();
-    		transaction(async (txn) => {
-    			for (let item of data) {
-    				await MyTable.put(item, txn);
-    			}
-    		});
-    	}, 3600000); // every hour
-    }
+    await transaction(async (txn) => {
+    	for (let item of data) {
+    		await MyTable.put(item, txn);
+    	}
+    });
     ```
 
-    The `txn` object members:
+    The `txn` object exposes:
 
-    | Member                | Type            | Description                                            |
-    | --------------------- | --------------- | ------------------------------------------------------ |
-    | `commit()`            | `() => Promise` | Commits the current transaction                        |
-    | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
-    | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
-    | `timestamp`           | `number`        | Timestamp associated with the current transaction      |
+    | Member                | Description                                            |
+    | --------------------- | ------------------------------------------------------ |
+    | `commit()`            | Commits the current transaction                        |
+    | `abort()`             | Aborts and resets the transaction                      |
+    | `resetReadSnapshot()` | Resets the read snapshot to the latest committed state |
+    | `timestamp`           | Timestamp associated with the current transaction      |
 
-11. **Understand atomicity boundaries**: All tables within the same database share one transactional context — writes across multiple tables commit atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
+    **Atomicity**: all tables in the same database share one transactional context — writes across multiple tables commit atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
 
-12. **Keep `harper` external in bundlers**: When using SSR bundlers, mark `harper` as external so it resolves to the live runtime. In `vite.config`:
+    If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — safe to call defensively.
+
+11. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
 
     ```javascript
+    // vite.config
     ssr: {
     	external: ['harper'];
     }
@@ -1892,7 +1912,31 @@ Apply this rule when writing server-side Harper component code that reads from o
 
 #### Examples
 
-##### Nested conditions query
+##### Full CRUD sequence
+
+```javascript
+import { tables } from 'harper';
+const { Product } = tables;
+
+// Create
+const created = await Product.create({ name: 'Shirt', price: 9.5 });
+
+// Patch
+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);
+
+// Query with conditions
+const query = {
+	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
+};
+for await (const record of Product.search(query)) {
+	// process record
+}
+```
+
+##### Nested conditions with `or`
 
 ```javascript
 Product.search({
@@ -1915,28 +1959,35 @@ Product.search({
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-##### Full CRUD sequence
+##### Background job with `transaction()`
 
 ```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);
-
-// Query with conditions
-const query = {
-	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-};
-for await (const record of Product.search(query)) {
-	// process record
+import { isMainThread } from 'node:worker_threads';
+import { tables, transaction } from 'harper';
+const { MyTable } = tables;
+
+if (isMainThread) {
+	let running = false;
+	setInterval(async () => {
+		if (running) return;
+		running = true;
+		try {
+			let data = await (await fetch('https://example.com/data')).json();
+			await transaction(async (txn) => {
+				for (let item of data) {
+					await MyTable.put(item, txn);
+				}
+			});
+		} catch (error) {
+			logger.error('hourly import failed', error);
+		} finally {
+			running = false;
+		}
+	}, 3600000);
 }
 ```
 
-##### SSR rendering with `tables`
+##### SSR render with `tables`
 
 ```typescript
 import { tables } from 'harper';
@@ -1947,23 +1998,12 @@ export async function render(url: string): Promise<string> {
 }
 ```
 
-##### Mutable update with `addTo`
-
-```javascript
-const product = await Product.update(32);
-product.status = 'active';
-product.subtractFrom('quantity', 1);
-product.save();
-```
-
 #### Notes
 
-- `tables` calls run in a trusted server-side context and do **not** automatically apply the target table's role permissions. Enforce authorization in your own application logic.
-- Destructive operations (`update`, `patch`, `delete`) act on live data and are not easily reversible. Always scope with specific `conditions`, validate the affected set before writing, and gate behind authorization controls.
-- Sorting by the bare `@primaryKey` alone with no conditions triggers `HdbError: <attribute> is not indexed and not combined with any other conditions`. Add an open-ended range condition or pass `allowFullScan: true` to permit an unconditional scan.
-- Selecting a relationship field without filtering on it behaves as a **LEFT JOIN**; adding a condition on a related attribute behaves as an **INNER JOIN**.
-- `transaction()` is safe to call defensively — if a transaction is already active on the context, it reuses it and executes the callback immediately.
-- Link the `harper` package for correct typings in standalone component directories: `npm link harper`.
+- `tables` and `databases` do **not** automatically apply role permissions — calls run in a trusted server-side context. Apply your own authorization controls before exposing results.
+- Destructive operations (`update`, `patch`, `delete`) act on live data and are not easily reversible. Scope them with specific `conditions` and validate the affected set before writing.
+- `tables` is the same live, process-wide object whether accessed as a global or via `import { tables } from 'harper'`. A record written through one component is immediately visible to every other.
+- Run `npm link harper` for components in their own directory to ensure typings match the running installation.
 
 ### 3.4 TypeScript Type Stripping in Harper