@harperfast/template-react-studio 1.2.1 → 1.3.0

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

@@ -0,0 +1,258 @@
+# Harper Best Practices
+
+Guidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.
+
+---
+
+## Table of Contents
+
+1. [Schema & Data Design](#1-schema--data-design) — **HIGH**
+   - 1.1 [Adding Tables with Schemas](#11-adding-tables-with-schemas)
+   - 1.2 [Defining Relationships](#12-defining-relationships)
+   - 1.3 [Vector Indexing](#13-vector-indexing)
+   - 1.4 [Using Blobs](#14-using-blobs)
+   - 1.5 [Handling Binary Data](#15-handling-binary-data)
+2. [API & Communication](#2-api--communication) — **HIGH**
+   - 2.1 [Automatic REST APIs](#21-automatic-rest-apis)
+   - 2.2 [Querying REST APIs](#22-querying-rest-apis)
+   - 2.3 [Real-time Applications](#23-real-time-applications)
+   - 2.4 [Checking Authentication](#24-checking-authentication)
+3. [Logic & Extension](#3-logic--extension) — **MEDIUM**
+   - 3.1 [Custom Resources](#31-custom-resources)
+   - 3.2 [Extending Table Resources](#32-extending-table-resources)
+   - 3.3 [Programmatic Table Requests](#33-programmatic-table-requests)
+   - 3.4 [TypeScript Type Stripping](#34-typescript-type-stripping)
+   - 3.5 [Caching](#35-caching)
+4. [Infrastructure & Ops](#4-infrastructure--ops) — **MEDIUM**
+   - 4.1 [Deploying to Harper Fabric](#41-deploying-to-harper-fabric)
+   - 4.2 [Serving Web Content](#42-serving-web-content)
+
+---
+
+## 1. Schema & Data Design
+
+**Impact: HIGH**
+
+### 1.1 Adding Tables with Schemas
+
+Instructions for the agent to follow when adding tables to a Harper database.
+
+#### When to Use
+Use this skill when you need to define new data structures or modify existing ones in a Harper database.
+
+#### Steps
+1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file.
+2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
+3. **Define Relationships**: Link tables together using the `@relationship` directive. 
+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. 
+5. **Consider Table Extensions**: If you are going to extend the table in your resources, then do not `@export` the table from the schema.
+
+#### Example
+```graphql
+type ExamplePerson @table @export {
+	id: ID @primaryKey
+	name: String
+	tag: String @indexed
+}
+```
+
+### 1.2 Defining Relationships
+
+Using the `@relationship` directive to link tables.
+
+#### When to Use
+Use this when you have two or more tables that need to be logically linked (e.g., a "Product" table and a "Category" table).
+
+#### Steps
+1. **Identify the Relationship**: Determine which table should "own" the relationship. This is typically the table that will hold the foreign key.
+2. **Apply the `@relationship` Directive**: In your GraphQL schema, use the `@relationship` directive on the field that links to another table.
+3. **Specify the `name` and `path` Arguments**:
+   - `name`: A unique name for the relationship.
+   - `path`: The field name in the current table that holds the value to match in the related table.
+4. **Define the Inverse Relationship (Optional but Recommended)**: For better queryability, define the relationship in the related table as well.
+
+#### Example
+```graphql
+type Product @table @export {
+    id: ID @primaryKey
+    name: String
+    category: Category @relationship(name: "product_category", path: "category_id")
+    category_id: ID
+}
+
+type Category @table @export {
+    id: ID @primaryKey
+    name: String
+    products: [Product] @relationship(name: "product_category", path: "id")
+}
+```
+
+### 1.3 Vector Indexing
+
+How to define and use vector indexes for efficient similarity search.
+
+#### When to Use
+Use this when you need to perform similarity searches on high-dimensional data, such as image embeddings, text embeddings, or any other numeric vectors.
+
+#### Steps
+1. **Define the Vector Field**: In your GraphQL schema, define a field with a list of floats (e.g., `[Float]`).
+2. **Apply the `@indexed` Directive**: Use the `@indexed` directive on the vector field and specify the index type as `vector`.
+3. **Configure the Index (Optional)**: You can provide additional configuration for the vector index, such as the distance metric (e.g., `cosine`, `euclidean`).
+4. **Querying**: Use the `vector` operator in your REST or programmatic requests to perform similarity searches.
+
+#### Example
+```graphql
+type Document @table @export {
+    id: ID @primaryKey
+    content: String
+    embedding: [Float] @indexed(type: "vector", options: { dims: 1536, metric: "cosine" })
+}
+```
+
+### 1.4 Using Blobs
+
+How to store and retrieve large data in HarperDB.
+
+#### When to Use
+Use this when you need to store large, unstructured data such as files, images, or large text documents that exceed the typical size of a standard database field.
+
+#### Steps
+1. **Define the Blob Field**: Use the `Blob` scalar type in your GraphQL schema.
+2. **Storing Data**: Send the data as a buffer or a stream when creating or updating a record.
+3. **Retrieving Data**: Access the blob field, which will return the data as a stream or buffer.
+
+### 1.5 Handling Binary Data
+
+How to store and serve binary data like images or MP3s.
+
+#### When to Use
+Use this when your application needs to handle binary files, particularly for storage and retrieval.
+
+#### Steps
+1. **Use the `Blob` type**: As with general large data, the `Blob` type is best for binary files.
+2. **Streaming**: For large files, use streaming to minimize memory usage during upload and download.
+3. **MIME Types**: Store the MIME type alongside the binary data to ensure it is served correctly by your application logic.
+
+---
+
+## 2. API & Communication
+
+**Impact: HIGH**
+
+### 2.1 Automatic REST APIs
+
+Details on the CRUD endpoints automatically generated for exported tables.
+
+#### Endpoints
+- `GET /{TableName}`: Describes the schema.
+- `GET /{TableName}/`: Lists records (supports filtering/sorting).
+- `GET /{TableName}/{id}`: Gets a record by ID.
+- `POST /{TableName}/`: Creates a record.
+- `PUT /{TableName}/{id}`: Updates a record.
+- `PATCH /{TableName}/{id}`: Partial update.
+- `DELETE /{TableName}/`: Deletes records.
+- `DELETE /{TableName}/{id}`: Deletes by ID.
+
+### 2.2 Querying REST APIs
+
+How to use filters, operators, sorting, and pagination in REST requests.
+
+#### Query Parameters
+- `limit`: Number of records to return.
+- `offset`: Number of records to skip.
+- `sort`: Field to sort by.
+- `order`: `asc` or `desc`.
+- `filter`: JSON object for filtering.
+
+### 2.3 Real-time Applications
+
+Implementing WebSockets and Pub/Sub for live data updates.
+
+#### When to Use
+Use this for applications that require live updates, such as chat apps, live dashboards, or collaborative tools.
+
+#### Steps
+1. **WebSocket Connection**: Connect to the Harper WebSocket endpoint.
+2. **Subscribing**: Subscribe to table updates or specific records.
+3. **Pub/Sub**: Use the internal bus to publish and subscribe to custom events.
+
+### 2.4 Checking Authentication
+
+How to use sessions to verify user identity and roles.
+
+#### When to Use
+Use this to secure your application by ensuring that only authorized users can access certain resources or perform specific actions.
+
+#### Steps
+1. **Session Handling**: Access the session object from the request context.
+2. **Identity Verification**: Check for the presence of a user ID or token.
+3. **Role Checks**: Verify if the user has the required roles for the action.
+
+---
+
+## 3. Logic & Extension
+
+**Impact: MEDIUM**
+
+### 3.1 Custom Resources
+
+How to define custom REST endpoints using JavaScript or TypeScript.
+
+#### Steps
+1. **Create Resource File**: Define your logic in a JS or TS file.
+2. **Export Handlers**: Export functions like `GET`, `POST`, etc.
+3. **Registration**: Ensure the resource is correctly registered in your application configuration.
+
+### 3.2 Extending Table Resources
+
+Adding custom logic to automatically generated table resources.
+
+#### Steps
+1. **Define Extension**: Create a resource file that targets an existing table.
+2. **Intercept Requests**: Use handlers to add custom validation or data transformation.
+3. **No `@export`**: If extending, remember not to `@export` the table in the schema.
+
+### 3.3 Programmatic Table Requests
+
+How to use filters, operators, sorting, and pagination in programmatic table requests.
+
+#### Usage
+When writing custom resources, use the internal API to query tables with full support for advanced filtering and sorting.
+
+### 3.4 TypeScript Type Stripping
+
+Using TypeScript directly without build tools via Node.js Type Stripping.
+
+#### Configuration
+Harper supports native TypeScript type stripping, allowing you to run `.ts` files directly. Ensure your environment is configured to take advantage of this for faster development cycles.
+
+### 3.5 Caching
+
+How caching is defined and implemented in Harper applications.
+
+#### Strategies
+- **In-memory**: For fast access to frequently used data.
+- **Distributed**: For scaling across multiple nodes in Harper Fabric.
+
+---
+
+## 4. Infrastructure & Ops
+
+**Impact: MEDIUM**
+
+### 4.1 Deploying to Harper Fabric
+
+Globally scaling your Harper application.
+
+#### Benefits
+- **Global Distribution**: Low latency for users everywhere.
+- **Automatic Sync**: Data is synced across the fabric automatically.
+- **Free Tier**: Start for free and scale as you grow.
+
+### 4.2 Serving Web Content
+
+Two ways to serve web content from a Harper application.
+
+#### Methods
+1. **Static Serving**: Serve HTML, CSS, and JS files directly.
+2. **Dynamic Rendering**: Use custom resources to render content on the fly.

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

@@ -0,0 +1,88 @@
+---
+name: harper-best-practices
+description: 
+  Best practices for building Harper applications, covering schema definition,
+  automatic APIs, authentication, custom resources, and data handling.
+  Triggers on tasks involving Harper database design, API implementation,
+  and deployment.
+license: MIT
+metadata:
+  author: harper
+  version: '1.0.0'
+---
+
+# Harper Best Practices
+
+Guidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.
+
+## When to Use
+
+Reference these guidelines when:
+
+- Defining or modifying database schemas
+- Implementing or extending REST/WebSocket APIs
+- Handling authentication and session management
+- Working with custom resources and extensions
+- Optimizing data storage and retrieval (Blobs, Vector Indexing)
+- Deploying applications to Harper Fabric
+
+## Steps
+
+1. Review the requirements for the task (schema design, API needs, or infrastructure setup).
+2. Consult the relevant category under "Rule Categories by Priority" to understand the impact of your decisions.
+3. Apply specific rules from the "Quick Reference" section below by reading their detailed rule files.
+4. If you're building a new table, prioritize the `schema-` rules.
+5. If you're extending functionality, consult the `logic-` and `api-` rules.
+6. Validate your implementation against the `ops-` rules before deployment.
+
+## Rule Categories by Priority
+
+| Priority | Category                | Impact | Prefix          |
+| -------- | ----------------------- | ------ | --------------- |
+| 1        | Schema & Data Design    | HIGH   | `schema-`       |
+| 2        | API & Communication     | HIGH   | `api-`          |
+| 3        | Logic & Extension       | MEDIUM | `logic-`        |
+| 4        | Infrastructure & Ops    | MEDIUM | `ops-`          |
+
+## Quick Reference
+
+### 1. Schema & Data Design (HIGH)
+
+- `adding-tables-with-schemas` - Define tables using GraphQL schemas and directives
+- `defining-relationships` - Link tables using the `@relationship` directive
+- `vector-indexing` - Efficient similarity search with vector indexes
+- `using-blob-datatype` - Store and retrieve large data (Blobs)
+- `handling-binary-data` - Manage binary data like images or MP3s
+
+### 2. API & Communication (HIGH)
+
+- `automatic-apis` - Leverage automatically generated CRUD endpoints
+- `querying-rest-apis` - Filters, sorting, and pagination in REST requests
+- `real-time-apps` - WebSockets and Pub/Sub for live data updates
+- `checking-authentication` - Secure apps with session-based identity verification
+
+### 3. Logic & Extension (MEDIUM)
+
+- `custom-resources` - Define custom REST endpoints using JS/TS
+- `extending-tables` - Add custom logic to generated table resources
+- `programmatic-table-requests` - Advanced filtering and sorting in code
+- `typescript-type-stripping` - Use TypeScript without build tools
+- `caching` - Implement and define caching for performance
+
+### 4. Infrastructure & Ops (MEDIUM)
+
+- `deploying-to-harper-fabric` - Scale globally with Harper Fabric
+- `serving-web-content` - Ways to serve web content from Harper
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/adding-tables-with-schemas.md
+rules/automatic-apis.md
+```
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

package/.agents/skills/harper-best-practices/rules/adding-tables-with-schemas.md

@@ -0,0 +1,40 @@
+---
+name: adding-tables-with-schemas
+description: Guidelines for adding tables to a Harper database using GraphQL schemas.
+---
+
+# Adding Tables with Schemas
+
+Instructions for the agent to follow when adding tables to a Harper database.
+
+## When to Use
+
+Use this skill when you need to define new data structures or modify existing ones in a Harper database.
+
+## Steps
+
+1. **Create Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file.
+2. **Use Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/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. 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}/`: 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.
+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.
+
+### Example
+
+In a hypothetical `schemas/ExamplePerson.graphql`:
+
+```graphql
+type ExamplePerson @table @export {
+	id: ID @primaryKey
+	name: String
+	tag: String @indexed
+}
+```

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

@@ -0,0 +1,34 @@
+---
+name: automatic-apis
+description: How to use Harper's automatically generated REST and WebSocket APIs.
+---
+
+# Automatic APIs
+
+Instructions for the agent to follow when utilizing Harper's automatic APIs.
+
+## When to Use
+
+Use this skill when you want to interact with Harper tables via REST or WebSockets without writing custom resource logic. This is ideal for basic CRUD operations and real-time updates.
+
+## Steps
+
+1. **Enable Automatic APIs**: Ensure your GraphQL schema includes the `@export` directive for the table:
+   ```graphql
+   type MyTable @table @export {
+   	id: ID @primaryKey
+   	# ... other fields
+   }
+   ```
+2. **Access REST Endpoints**: Use the following endpoints for a table named `TableName` (Note: Paths are **case-sensitive**):
+   - **Describe Schema**: `GET /{TableName}`
+   - **List Records**: `GET /{TableName}/` (Supports filtering, sorting, and pagination. See [Querying REST APIs](querying-rest-apis.md)).
+   - **Get Single Record**: `GET /{TableName}/{id}`
+   - **Create Record**: `POST /{TableName}/` (Request body should be JSON).
+   - **Update Record (Full)**: `PUT /{TableName}/{id}`
+   - **Update Record (Partial)**: `PATCH /{TableName}/{id}`
+   - **Delete All/Filtered Records**: `DELETE /{TableName}/`
+   - **Delete Single Record**: `DELETE /{TableName}/{id}`
+3. **Use Automatic WebSockets**: Connect to `ws://your-harper-instance/{TableName}` to receive events whenever updates are made to that table. This is the easiest way to add real-time capabilities. For more complex needs, see [Real-time Applications](real-time-apps.md).
+4. **Apply Filtering and Querying**: Use query parameters with `GET /{TableName}/` and `DELETE /{TableName}/`. See the [Querying REST APIs](querying-rest-apis.md) skill for advanced details.
+5. **Customize if Needed**: If the automatic APIs don't meet your requirements, [customize the resources](./custom-resources.md).

package/.agents/skills/harper-best-practices/rules/caching.md

@@ -0,0 +1,46 @@
+---
+name: caching
+description: How to implement integrated data caching in Harper from external sources.
+---
+
+# Caching
+
+Instructions for the agent to follow when implementing caching in Harper.
+
+## When to Use
+
+Use this skill when you need high-performance, low-latency storage for data from external sources. It's ideal for reducing API calls to third-party services, preventing cache stampedes, and making external data queryable as if it were native Harper tables.
+
+## Steps
+
+1. **Configure a Cache Table**: Define a table in your `schema.graphql` with an `expiration` (in seconds):
+   ```graphql
+   type MyCache @table(expiration: 3600) @export {
+   	id: ID @primaryKey
+   }
+   ```
+2. **Define an External Source**: Create a Resource class that fetches the data:
+   ```js
+   import { Resource } from 'harperdb';
+
+   export class ThirdPartyAPI extends Resource {
+   	async get() {
+   		const id = this.getId();
+   		const response = await fetch(`https://api.example.com/items/${id}`);
+   		if (!response.ok) {
+   			throw new Error('Source fetch failed');
+   		}
+   		return await response.json();
+   	}
+   }
+   ```
+3. **Attach Source to Table**: Use `sourcedFrom` to link your resource to the table:
+   ```js
+   import { tables } from 'harperdb';
+   import { ThirdPartyAPI } from './ThirdPartyAPI.js';
+
+   const { MyCache } = tables;
+   MyCache.sourcedFrom(ThirdPartyAPI);
+   ```
+4. **Implement Active Caching (Optional)**: Use `subscribe()` for proactive updates. See [Real Time Apps](real-time-apps.md).
+5. **Implement Write-Through Caching (Optional)**: Define `put` or `post` in your resource to propagate updates upstream.

package/.agents/skills/harper-best-practices/rules/checking-authentication.md

@@ -0,0 +1,165 @@
+---
+name: checking-authentication
+description: How to handle user authentication and sessions in Harper Resources.
+---
+
+# Checking Authentication
+
+Instructions for the agent to follow when handling authentication and sessions.
+
+## When to Use
+
+Use this skill when you need to implement sign-in/sign-out functionality, protect specific resource endpoints, or identify the currently logged-in user in a Harper application.
+
+## Steps
+
+1. **Configure Harper for Sessions**: Ensure `harperdb-config.yaml` has sessions enabled and local auto-authorization disabled for testing:
+   ```yaml
+   authentication:
+     authorizeLocal: false
+     enableSessions: true
+   ```
+2. **Implement Sign In**: Use `this.getContext().login(username, password)` to create a session:
+   ```ts
+   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 });
+   }
+   ```
+3. **Identify Current User**: Use `this.getCurrentUser()` to access session data:
+   ```ts
+   async get() {
+     const user = this.getCurrentUser?.();
+     if (!user) return new Response(null, { status: 401 });
+     return { username: user.username, role: user.role };
+   }
+   ```
+4. **Implement Sign Out**: Use `this.getContext().logout()` or delete the session from context:
+   ```ts
+   async post() {
+     const context = this.getContext();
+     await context.session?.delete?.(context.session.id);
+     return new Response('Logged out', { status: 200 });
+   }
+   ```
+5. **Protect Routes**: In your Resource, use `allowRead()`, `allowUpdate()`, etc., to enforce authorization logic based on `this.getCurrentUser()`. For privileged actions, verify `user.role.permission.super_user`.
+
+## Status code conventions used here
+
+- 200: Successful operation. For `GET /me`, a `200` with empty body means “not signed in”.
+- 400: Missing required fields (e.g., username/password on sign-in).
+- 401: No current session for an action that requires one (e.g., sign out when not signed in).
+- 403: Authenticated but not authorized (bad credentials on login attempt, or insufficient privileges).
+
+## Client considerations
+
+- Sessions are cookie-based; the server handles setting and reading the cookie via Harper. If you make cross-origin requests, ensure the appropriate `credentials` mode and CORS settings.
+- If developing locally, double-check the server config still has `authentication.authorizeLocal: false` to avoid accidental superuser bypass.
+
+## Token-based auth (JWT + refresh token) for non-browser clients
+
+Cookie-backed sessions are great for browser flows. For CLI tools, mobile apps, or other non-browser clients, it’s often easier to use **explicit tokens**:
+
+- **JWT (`operation_token`)**: short-lived bearer token used to authorize API requests.
+- **Refresh token (`refresh_token`)**: longer-lived token used to mint a new JWT when it expires.
+
+This project includes two Resource patterns for that flow:
+
+### Issuing tokens: `IssueTokens`
+
+**Description / use case:** Generate `{ refreshToken, jwt }` either:
+
+- with an existing Authorization token (either Basic Auth or a JWT) and you want to issue new tokens, or
+- from an explicit `{ username, password }` payload (useful for direct “login” from a CLI/mobile client).
+
+```
+js
+export class IssueTokens extends Resource {
+static loadAsInstance = false;
+
+	async get(target) {
+		const { refresh_token: refreshToken, operation_token: jwt } =
+			await databases.system.hdb_user.operation(
+				{ operation: 'create_authentication_tokens' },
+				this.getContext(),
+			);
+		return { refreshToken, jwt };
+	}
+
+	async post(target, data) {
+		if (!data.username || !data.password) {
+			throw new Error('username and password are required');
+		}
+
+		const { refresh_token: refreshToken, operation_token: jwt } =
+			await databases.system.hdb_user.operation({
+				operation: 'create_authentication_tokens',
+				username: data.username,
+				password: data.password,
+			});
+		return { refreshToken, jwt };
+	}
+}
+```
+
+**Recommended documentation notes to include:**
+
+- `GET` variant: intended for “I already have an Authorization token, give me new tokens”.
+- `POST` variant: intended for “I have credentials, give me tokens”.
+- Response shape:
+  - `refreshToken`: store securely (long-lived).
+  - `jwt`: attach to requests (short-lived).
+
+### Refreshing a JWT: `RefreshJWT`
+
+**Description / use case:** When the JWT expires, the client uses the refresh token to get a new JWT without re-supplying username/password.
+
+```
+js
+export class RefreshJWT extends Resource {
+static loadAsInstance = false;
+
+	async post(target, data) {
+		if (!data.refreshToken) {
+			throw new Error('refreshToken is required');
+		}
+
+		const { operation_token: jwt } = await databases.system.hdb_user.operation({
+			operation: 'refresh_operation_token',
+			refresh_token: data.refreshToken,
+		});
+		return { jwt };
+	}
+}
+```
+
+**Recommended documentation notes to include:**
+
+- Requires `refreshToken` in the request body.
+- Returns a new `{ jwt }`.
+- If refresh fails (expired/revoked), client must re-authenticate (e.g., call `IssueTokens.post` again).
+
+### Suggested client flow (high-level)
+
+1. **Sign in (token flow)**
+   - POST /IssueTokens/ with a body of `{ "username": "your username", "password": "your password" }` or GET /IssueTokens/ with an existing Authorization token.
+   - Receive `{ jwt, refreshToken }` in the response
+2. **Call protected APIs**
+   - Send the JWT with each request in the Authorization header (as your auth mechanism expects)
+3. **JWT expires**
+   - POST /RefreshJWT/ with a body of `{ "refreshToken": "your refresh token" }`.
+   - Receive `{ jwt }` in the response and continue
+
+## Quick checklist
+
+- [ ] Public endpoints explicitly `allowRead`/`allowCreate` as needed.
+- [ ] Sign-in uses `context.login` and handles 400/403 correctly.
+- [ ] Protected routes call `ensureSuperUser(this.getCurrentUser())` (or another role check) before doing work.
+- [ ] Sign-out verifies a session and deletes it.
+- [ ] `authentication.authorizeLocal` is `false` and `enableSessions` is `true` in Harper config.
+- [ ] If using tokens: `IssueTokens` issues `{ jwt, refreshToken }`, `RefreshJWT` refreshes `{ jwt }` with a `refreshToken`.

package/.agents/skills/harper-best-practices/rules/custom-resources.md

@@ -0,0 +1,35 @@
+---
+name: custom-resources
+description: How to define custom REST endpoints with JavaScript or TypeScript in Harper.
+---
+
+# Custom Resources
+
+Instructions for the agent to follow when creating custom resources in Harper.
+
+## When to Use
+
+Use 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.
+
+## Steps
+
+1. **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.
+2. **Create the Resource File**: Create a `.ts` or `.js` file in the directory specified by `jsResource` in `config.yaml` (typically `resources/`).
+3. **Define the Resource Class**: Export a class extending `Resource` from `harperdb`:
+   ```typescript
+   import { type RequestTargetOrId, Resource } from 'harperdb';
+
+   export class MyResource extends Resource {
+   	async get(target?: RequestTargetOrId) {
+   		return { message: 'Hello from custom GET!' };
+   	}
+   }
+   ```
+4. **Implement HTTP Methods**: Add methods like `get`, `post`, `put`, `patch`, or `delete` to handle corresponding requests. Note that paths are **case-sensitive** and match the class name.
+5. **Access Tables (Optional)**: Import and use the `tables` object to interact with your data:
+   ```typescript
+   import { tables } from 'harperdb';
+   // ... inside a method
+   const results = await tables.MyTable.list();
+   ```
+6. **Configure Loading**: Ensure `config.yaml` points to your resource files (e.g., `jsResource: { files: 'resources/*.ts' }`).