@harperfast/template-vue-ts-studio 1.8.2 → 1.9.1

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

@@ -0,0 +1,96 @@
+---
+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: "Apache-2.0"
+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
+
+## How It Works
+
+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.
+
+## Examples
+
+See the concrete examples embedded in each rule subsection below (GraphQL schemas, REST query patterns, and deployment workflow snippets).
+
+<!-- BEGIN GENERATED INDEX -->
+
+## 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` — Guidelines for adding tables to a Harper database using GraphQL schemas.
+- `schema-design-tooling` — Best practices for Harper schema design, including core directives and GraphQL tooling configuration.
+- `defining-relationships` — How to define and use relationships between tables in Harper using GraphQL.
+- `vector-indexing` — How to enable and query vector indexes for similarity search in Harper.
+- `using-blob-datatype` — How to use the Blob data type for efficient binary storage in Harper.
+- `handling-binary-data` — How to store and serve binary data like images or audio in Harper.
+
+### 2. API & Communication (HIGH)
+
+- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs.
+- `querying-rest-apis` — How to use query parameters to filter, sort, and paginate Harper REST APIs.
+- `real-time-apps` — How to build real-time features in Harper using WebSockets and Pub/Sub.
+- `checking-authentication` — How to handle user authentication and sessions in Harper Resources.
+
+### 3. Logic & Extension (MEDIUM)
+
+- `custom-resources` — How to define custom REST endpoints with JavaScript or TypeScript in Harper.
+- `extending-tables` — How to add custom logic to automatically generated table resources in Harper.
+- `programmatic-table-requests` — How to interact with Harper tables programmatically using the `tables` object.
+- `typescript-type-stripping` — How to run TypeScript files directly in Harper without a build step.
+- `caching` — How to implement integrated data caching in Harper from external sources.
+
+### 4. Infrastructure & Ops (MEDIUM)
+
+- `deploying-to-harper-fabric` — How to deploy a Harper application to the Harper Fabric cloud.
+- `creating-a-fabric-account-and-cluster` — How to create a Harper Fabric account, organization, and cluster.
+- `creating-harper-apps` — How to initialize a new Harper application using the CLI.
+- `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper.
+- `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.
+- `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin.
+
+<!-- END GENERATED INDEX -->
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/adding-tables-with-schemas.md
+rules/schema-design-tooling.md
+rules/automatic-apis.md
+rules/creating-harper-apps.md
+rules/logging.md
+```
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

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

@@ -0,0 +1,42 @@
+---
+name: adding-tables-with-schemas
+description: Guidelines for adding tables to a Harper database using GraphQL schemas.
+metadata:
+  mode: synthesized
+---
+
+# 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.
+
+## How It Works
+
+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/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}/`: 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.
+
+## Examples
+
+In a hypothetical `schemas/ExamplePerson.graphql`:
+
+```graphql
+type ExamplePerson @table @export {
+	id: ID @primaryKey
+	name: String
+	tag: String @indexed
+}
+```

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

@@ -0,0 +1,165 @@
+---
+name: automatic-apis
+description: How to use Harper's automatically generated REST and WebSocket APIs.
+metadata:
+  mode: generate
+  sources:
+    - reference/v5/rest/overview.md
+    - reference/v5/rest/websockets.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 8fcf0cfe190e013e
+---
+
+# Automatic APIs
+
+Instructions for the agent to follow when enabling and using Harper's automatically generated REST and WebSocket APIs.
+
+## When to Use
+
+Apply this rule when adding REST or WebSocket API access to Harper tables or custom resources. Use it when configuring `config.yaml` to expose endpoints, mapping HTTP methods to resource operations, or implementing real-time WebSocket connections on a resource class.
+
+## How It Works
+
+1. **Enable the REST plugin**: Add `rest: true` to your application's `config.yaml`. This activates the HTTP REST interface and enables WebSocket support by default.
+
+   ```yaml
+   rest: true
+   ```
+
+   To configure optional behavior:
+
+   ```yaml
+   rest:
+     lastModified: true # enables Last-Modified response header support
+     webSocket: false # disables automatic WebSocket support (enabled by default)
+   ```
+
+2. **Export your resource in the schema**: Tables are not exposed by default. Use the `@export` directive in your schema definition to make a table available as a REST endpoint. The exported name defines the base URL path, served on the application HTTP server port (default `9926`).
+
+3. **Use the correct URL structure**: The REST interface follows a consistent path convention.
+
+   | Path                                         | Description                                                                        |
+   | -------------------------------------------- | ---------------------------------------------------------------------------------- |
+   | `/my-resource`                               | Returns a description of the resource (e.g., table metadata)                       |
+   | `/my-resource/`                              | Trailing slash — represents the full collection; append query parameters to search |
+   | `/my-resource/record-id`                     | A specific record identified by its primary key                                    |
+   | `/my-resource/record-id/`                    | Trailing slash — collection of records with the given id prefix                    |
+   | `/my-resource/record-id/with/multiple/parts` | Record id with multiple path segments                                              |
+
+4. **Map HTTP methods to operations**: Each HTTP method maps to a resource method and operation.
+   - **GET** — Retrieve a record or search. Calls `get()`.
+
+     ```
+     GET /MyTable/123
+     GET /MyTable/?name=Harper
+     GET /MyTable/123.propertyName
+     ```
+
+     Responses include an `ETag` header. Clients may send `If-None-Match` to receive `304 Not Modified` when the record is unchanged.
+
+   - **PUT** — Create or replace a record (upsert). Calls `put(record)`. Properties not in the body are removed.
+
+     ```
+     PUT /MyTable/123
+     Content-Type: application/json
+
+     { "name": "some data" }
+     ```
+
+   - **POST** — Create a new record without specifying a primary key. Calls `post(data)`. The assigned key is returned in the `Location` response header.
+
+     ```
+     POST /MyTable/
+     Content-Type: application/json
+
+     { "name": "some data" }
+     ```
+
+   - **PATCH** — Partially update a record, merging only provided properties. Unspecified properties are preserved.
+
+     ```
+     PATCH /MyTable/123
+     Content-Type: application/json
+
+     { "status": "active" }
+     ```
+
+   - **DELETE** — Delete a record or all records matching a query.
+     ```
+     DELETE /MyTable/123
+     DELETE /MyTable/?status=archived
+     ```
+
+5. **Access the auto-generated OpenAPI spec**: Harper generates an OpenAPI specification for all exported resources. Retrieve it at:
+
+   ```
+   GET /openapi
+   ```
+
+6. **Connect via WebSocket**: When `rest` is enabled, WebSocket support is on by default. Connect to a resource URL to subscribe to change events for that resource.
+
+   ```javascript
+   let ws = new WebSocket('wss://server/my-resource/341');
+   ws.onmessage = (event) => {
+   	let data = JSON.parse(event.data);
+   };
+   ```
+
+   Connecting to `wss://server/my-resource/341` accesses the `my-resource` resource with record id `341` and subscribes to it. When the record changes or a message is published to it, the WebSocket connection receives the update.
+
+7. **Implement a custom `connect()` handler**: Override `connect(incomingMessages)` on a resource class to control WebSocket behavior. The method must return an async iterable or generator that produces messages to send to the client.
+
+## Examples
+
+**Simple echo server using an async generator**:
+
+```javascript
+export class Echo extends Resource {
+	async *connect(incomingMessages) {
+		for await (let message of incomingMessages) {
+			yield message; // echo each message back
+		}
+	}
+}
+```
+
+**Using the default `connect()` with event-style access and a timer**:
+
+```javascript
+export class Example extends Resource {
+	connect(incomingMessages) {
+		let outgoingMessages = super.connect();
+
+		let timer = setInterval(() => {
+			outgoingMessages.send({ greeting: 'hi again!' });
+		}, 1000);
+
+		incomingMessages.on('data', (message) => {
+			outgoingMessages.send(message); // echo incoming messages
+		});
+
+		outgoingMessages.on('close', () => {
+			clearInterval(timer);
+		});
+
+		return outgoingMessages;
+	}
+}
+```
+
+**Minimal `config.yaml` enabling REST with WebSocket disabled**:
+
+```yaml
+rest:
+  webSocket: false
+```
+
+## Notes
+
+- Tables must be explicitly exported using `@export` in the schema — they are not exposed by default.
+- `rest: true` is the minimal configuration to enable both REST and WebSocket support. See [real-time-apps.md](real-time-apps.md) for patterns around real-time WebSocket usage.
+- For full query syntax on `GET` and `DELETE` with query parameters, see [querying-rest-apis.md](querying-rest-apis.md).
+- The default `connect()` returns an iterable with a `send(message)` method and a `close` event for cleanup on disconnect.
+- For MQTT over WebSockets, set the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
+- In distributed environments, non-retained messages are delivered in the order received per node; retained messages (PUT/updated records) keep only the latest-timestamp version as the winning record across the cluster.
+- Use the `Content-Type` request header to specify body format and the `Accept` header to request a specific response format.

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

@@ -0,0 +1,163 @@
+---
+name: caching
+description: How to implement integrated data caching in Harper from external sources.
+metadata:
+  mode: generate
+  sources:
+    - learn/developers/caching-with-harper.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: 8212a7d7dbbd2b18
+---
+
+# Caching External Data Sources in Harper
+
+Instructions for the agent to implement integrated data caching in Harper by wrapping external sources with a cache table and `sourcedFrom`.
+
+## When to Use
+
+Apply this rule when a Harper application needs to cache responses from an external API, microservice, or database to avoid repeated slow or expensive upstream calls. Use it whenever you need to define TTL-based cache expiration, observe ETag-based conditional responses, or manually invalidate cached entries.
+
+## How It Works
+
+1. **Define a cache table with `expiration`**: In `schema.graphql`, add the `expiration` argument to `@table`. The value is in seconds. Any record older than this threshold is considered stale and will be re-fetched on next access.
+
+   ```graphql
+   type JokeCache @table(expiration: 60) @export {
+   	id: ID @primaryKey
+   	setup: String
+   	punchline: String
+   }
+   ```
+
+2. **Wrap the external source in `resources.js`**: Create an object with a `get(id)` method that fetches from the upstream source. Then call `sourcedFrom` on the table to register it.
+
+   ```javascript
+   const jokeAPI = {
+   	async get(id) {
+   		const response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);
+   		return response.json();
+   	},
+   };
+
+   tables.JokeCache.sourcedFrom(jokeAPI);
+   ```
+
+   Harper's caching behavior after `sourcedFrom` is registered:
+   - A request arrives for `/JokeCache/1`.
+   - Harper checks if the record with id `1` exists in `JokeCache` and is not stale.
+   - If fresh, Harper returns it immediately.
+   - If missing or stale, Harper calls `jokeAPI.get()`, stores the result in `JokeCache`, and returns it.
+   - Multiple simultaneous requests for the same missing or stale record wait on a single upstream call — Harper prevents cache stampedes automatically.
+
+3. **Configure plugins in `config.yaml`**: Enable the schema, REST API, and JS resource plugins.
+
+   ```yaml
+   graphqlSchema:
+     files: 'schema.graphql'
+   rest: true
+   jsResource:
+     files: 'resources.js'
+   ```
+
+4. **Observe caching via ETags**: Harper automatically computes an ETag from the record's last-modified timestamp. On the first request you receive a `200` with an `etag` header. Pass that value back in `If-None-Match` on subsequent requests; Harper returns `304 Not Modified` with an empty body if the record is unchanged.
+
+   ```bash
+   curl -i 'http://localhost:9926/JokeCache/1' \
+     -H 'If-None-Match: "abCDefGHij"'
+   ```
+
+5. **Force a cache bypass**: Send `Cache-Control: no-cache` to make Harper skip the local cache and always call the upstream source, regardless of TTL.
+
+   ```bash
+   curl -i 'http://localhost:9926/JokeCache/1' \
+     -H 'Cache-Control: no-cache'
+   ```
+
+6. **Invalidate a cache entry on demand**: Remove `@export` from the schema type, then export a class of the same name in `resources.js` that extends the table and implements a `post` handler calling `this.invalidate(target)`.
+
+   ```graphql
+   type JokeCache @table(expiration: 60) {
+   	id: ID @primaryKey
+   	setup: String
+   	punchline: String
+   }
+   ```
+
+   ```javascript
+   export class JokeCache extends tables.JokeCache {
+   	static async post(target, data) {
+   		const body = await data;
+   		if (body?.action === 'invalidate') {
+   			this.invalidate(target);
+   			return { status: 200, data: { message: 'invalidated' } };
+   		}
+   	}
+   }
+   ```
+
+   Trigger invalidation with a `POST`:
+
+   ```bash
+   curl -X POST 'http://localhost:9926/JokeCache/1' \
+     -H 'Content-Type: application/json' \
+     -d '{"action": "invalidate"}'
+   ```
+
+   The next `GET /JokeCache/1` will fetch fresh data from the upstream source regardless of TTL.
+
+## Examples
+
+Complete `schema.graphql` and `resources.js` for a cached external API with on-demand invalidation:
+
+```graphql
+type JokeCache @table(expiration: 60) {
+	id: ID @primaryKey
+	setup: String
+	punchline: String
+}
+```
+
+```javascript
+// resources.js
+
+const jokeAPI = {
+	async get() {
+		const id = this.getId();
+		const response = await fetch(`https://official-joke-api.appspot.com/jokes/${id}`);
+		return response.json();
+	},
+};
+
+tables.JokeCache.sourcedFrom(jokeAPI);
+
+export class JokeCache extends tables.JokeCache {
+	static async post(target, data) {
+		const body = await data;
+		if (body?.action === 'invalidate') {
+			this.invalidate(target);
+			return { status: 200, data: { message: 'invalidated' } };
+		}
+	}
+}
+```
+
+First request — cache miss, upstream is called, `200` returned:
+
+```bash
+curl -i 'http://localhost:9926/JokeCache/1'
+```
+
+Second request with ETag — cache hit, `304 Not Modified`:
+
+```bash
+curl -i 'http://localhost:9926/JokeCache/1' \
+  -H 'If-None-Match: "abCDefGHij"'
+```
+
+## Notes
+
+- `expiration` is measured in seconds. Harper also supports separate `eviction` and `scanInterval` arguments on `@table` for fine-grained control over physical record removal.
+- The `@export` directive on the schema type is not required when you export a Resource class of the same name from `resources.js` — the class export serves as the endpoint registration. See [custom-resources.md](custom-resources.md) for details on building Resource classes.
+- Harper's REST layer automatically exposes `@export`-ed tables and Resource classes as HTTP endpoints. See [automatic-apis.md](automatic-apis.md) for how endpoints are structured and named.
+- ETag values include their double quotes as part of the value — include them verbatim when passing the value in `If-None-Match`.
+- `sourcedFrom` must be called after the table reference (`tables.JokeCache`) is available, which is guaranteed when the call is at the top level of `resources.js`.

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

@@ -0,0 +1,190 @@
+---
+name: checking-authentication
+description: How to handle user authentication and sessions in Harper Resources.
+metadata:
+  mode: generate
+  sources:
+    - >-
+      reference/v5/resources/resource-api.md#`getCurrentUser(): User |
+      undefined`
+    - reference/v5/resources/resource-api.md#Session and Login from a Resource
+    - reference/v5/security/jwt-authentication.md
+  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
+  inputHash: fdd9ec3b11011490
+---
+
+# Checking Authentication
+
+Instructions for the agent to follow when handling user authentication and session management inside Harper Resources.
+
+## When to Use
+
+Apply this rule when implementing authentication checks, login/logout flows, or token issuance inside a custom Resource. Use it any time a Resource needs to identify the current user, establish a session, or issue JWTs to clients. See [custom-resources.md](custom-resources.md) for the general Resource authoring pattern.
+
+## How It Works
+
+1. **Check the current user** with `getCurrentUser()`. Call it inside any Resource method to retrieve the authenticated user or `undefined` if no user is authenticated. Guard protected endpoints by returning a `401` when the result is `undefined`.
+
+   ```javascript
+   async get(target) {
+     const user = this.getCurrentUser();
+     if (!user) return new Response(null, { status: 401 });
+     return { username: user.username, role: user.role };
+   }
+   ```
+
+   The returned object exposes `username`, `role`, and `role.permission` flags.
+
+2. **Enable sessions** before using session-based login. Set `authentication.enableSessions: true` in `harperdb-config.yaml`:
+
+   ```yaml
+   authentication:
+     enableSessions: true
+   ```
+
+3. **Access login and session helpers** via `getContext()`. The context object exposes `context.login` and `context.session` for sign-in/out flows.
+   - Call `context.login(username, password)` to verify credentials and establish a session cookie on success.
+   - To end a session, delete it via `context.session.delete(context.session.id)`.
+
+4. **Implement sign-in and sign-out Resources** using the context helpers:
+
+   ```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 });
+   	}
+   }
+
+   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 });
+   	}
+   }
+   ```
+
+5. **Issue JWTs for non-browser clients** (CLI tools, mobile apps, service-to-service). Cookie-based sessions are intended for browser clients. For other clients, mint tokens programmatically using `server.operation()`:
+
+   ```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 };
+   	}
+
+   	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 };
+   	}
+   }
+
+   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 };
+   	}
+   }
+   ```
+
+   Pass `true` as the third argument to `server.operation()` when the operation should run as the current authenticated user. Omit it or pass `false` when the operation supplies its own credentials.
+
+6. **Configure JWT token expiry** in `harperdb-config.yaml` under the `authentication` section:
+
+   ```yaml
+   authentication:
+     operationTokenTimeout: 1d
+     refreshTokenTimeout: 30d
+   ```
+
+   Duration strings follow the `jsonwebtoken` package format (e.g., `1d`, `12h`, `60m`).
+
+## Examples
+
+**Protecting a resource endpoint and returning user info:**
+
+```javascript
+async get(target) {
+  const user = this.getCurrentUser();
+  if (!user) return new Response(null, { status: 401 });
+  return { username: user.username, role: user.role };
+}
+```
+
+**Full session-based sign-in/sign-out flow:**
+
+```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 });
+	}
+}
+
+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 });
+	}
+}
+```
+
+**JWT token refresh endpoint:**
+
+```javascript
+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 };
+	}
+}
+```
+
+## Notes
+
+- `getCurrentUser()` and `getContext()` are instance methods; call them with `this` inside non-static Resource methods.
+- `enableSessions` must be `true` in config before `context.login` or `context.session` will function.
+- Cookie-based sessions target browser clients. Use JWT issuance via `server.operation()` for all other client types.
+- When both `operation_token` and `refresh_token` have expired, the client must call `create_authentication_tokens` again with credentials.

package/agent/skills/harper-best-practices/rules/creating-a-fabric-account-and-cluster.md

@@ -0,0 +1,30 @@
+---
+name: creating-a-fabric-account-and-cluster
+description: How to create a Harper Fabric account, organization, and cluster.
+metadata:
+  mode: synthesized
+---
+
+# Creating a Harper Fabric Account and Cluster
+
+Follow these steps to set up your Harper Fabric environment for deployment.
+
+## How It Works
+
+1. **Sign Up/In**: Go to [https://fabric.harper.fast/](https://fabric.harper.fast/) and sign up or sign in.
+2. **Create an Organization**: Create an organization (org) to manage your projects.
+3. **Create a Cluster**: Create a new cluster. This can be on the free tier, no credit card required.
+4. **Set Credentials**: During setup, set the cluster username and password to finish configuring it.
+5. **Get Application URL**: Navigate to the **Config** tab and copy the **Application URL**.
+6. **Configure Environment**: Update your `.env` file or GitHub Actions secrets with cluster-specific credentials.
+7. **Next Steps**: See the [deploying-to-harper-fabric](deploying-to-harper-fabric.md) rule for detailed instructions on deploying your application successfully.
+
+## Examples
+
+### Environment Configuration
+
+```bash
+CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'
+CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'
+CLI_TARGET='YOUR_CLUSTER_URL'
+```