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

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

@@ -6,8 +6,8 @@ metadata:
   sources:
     - reference/v5/rest/overview.md
     - reference/v5/rest/websockets.md
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: 8fcf0cfe190e013e
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: 6c7013b1307d9f7b
 ---
 
 # Automatic APIs
@@ -20,13 +20,13 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
 
 ## 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.
+1. **Enable the REST plugin**: Add `rest: true` to your application's `config.yaml`. This activates the HTTP REST interface on the application server port (default `9926`) and enables WebSocket support automatically.
 
    ```yaml
    rest: true
    ```
 
-   To configure optional behavior:
+   To configure options explicitly:
 
    ```yaml
    rest:
@@ -34,69 +34,26 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
      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`).
+2. **Export your resource in the schema**: Tables are not exposed by default. Use the `@export` directive in your schema definition to expose a table as a REST endpoint. The exported name defines the base URL path.
 
-3. **Use the correct URL structure**: The REST interface follows a consistent path convention.
+3. **Use the correct URL structure**: Target resources using these path conventions:
 
-   | 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                                              |
+   | Path                                         | Description                                                 |
+   | -------------------------------------------- | ----------------------------------------------------------- |
+   | `/my-resource`                               | Returns resource metadata                                   |
+   | `/my-resource/`                              | Collection — all records; append query parameters to search |
+   | `/my-resource/record-id`                     | Specific record by primary key                              |
+   | `/my-resource/record-id/`                    | 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()`.
+4. **Map operations to HTTP methods**: Each HTTP method maps to a resource method:
+   - **GET** — Retrieve a record or search. Calls `get()`. Responses include an `ETag` header; send `If-None-Match` on subsequent requests to receive `304 Not Modified` when unchanged.
+   - **PUT** — Create or replace a record (upsert). Calls `put(record)`. The stored record exactly matches the submitted body; omitted properties are removed.
+   - **POST** — Create a record without specifying a primary key. Calls `post(data)`. The assigned key is returned in the `Location` response header.
+   - **PATCH** — Partially update a record, merging only provided top-level properties. Calls the resource's patch handler. Merge is **shallow** — nested objects are replaced entirely, not deep-merged.
+   - **DELETE** — Delete a record by id or all records matching a query.
 
-     ```
-     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.
+5. **Connect via WebSocket**: A WebSocket connection to a resource URL subscribes to that resource and streams change events. See [real-time-apps.md](real-time-apps.md) for full real-time patterns.
 
    ```javascript
    let ws = new WebSocket('wss://server/my-resource/341');
@@ -105,13 +62,17 @@ Apply this rule when adding REST or WebSocket API access to Harper tables or cus
    };
    ```
 
-   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.
+6. **Implement a custom `connect()` handler** on a resource class to control WebSocket behavior. The method receives `incomingMessages` and must return an async iterable producing messages to send to the client.
+
+7. **Retrieve the OpenAPI spec**: Harper auto-generates an OpenAPI specification for all exported resources, available at:
 
-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.
+   ```
+   GET /openapi
+   ```
 
 ## Examples
 
-**Simple echo server using an async generator**:
+**Simple echo WebSocket server**:
 
 ```javascript
 export class Echo extends Resource {
@@ -123,7 +84,7 @@ export class Echo extends Resource {
 }
 ```
 
-**Using the default `connect()` with event-style access and a timer**:
+**Custom `connect()` using the default iterable with `send()` and `close` event**:
 
 ```javascript
 export class Example extends Resource {
@@ -147,19 +108,26 @@ export class Example extends Resource {
 }
 ```
 
-**Minimal `config.yaml` enabling REST with WebSocket disabled**:
+**Common REST operations**:
+
+```
+GET /MyTable/123
+GET /MyTable/?name=Harper
+PUT /MyTable/123
+PATCH /MyTable/123
+DELETE /MyTable/?status=archived
+```
 
-```yaml
-rest:
-  webSocket: false
+```json
+{ "name": "some data" }
 ```
 
 ## 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.
+- `rest: true` is the minimal config to enable both REST and WebSocket support. Set `webSocket: false` under the `rest` key to disable WebSocket only.
+- The `@export` directive in the schema is required for any table to appear as a REST endpoint — tables are not exported by default.
+- PATCH merges are shallow (top-level only). Nested objects in the request body replace the entire existing sub-object. Dot-path keys (e.g., `"settings.theme"`) are stored as literal keys, not interpreted as paths.
+- For MQTT over WebSocket, set the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
+- In distributed environments, non-retained messages are delivered in arrival order; retained messages (PUT/updated records) keep only the latest timestamp as the winning record.
+- For full query syntax on GET and DELETE, see [querying-rest-apis.md](querying-rest-apis.md).
+- For building real-time features with WebSocket subscriptions, see [real-time-apps.md](real-time-apps.md).

package/.agents/skills/harper-best-practices/rules/defining-relationships.md

@@ -6,8 +6,8 @@ metadata:
   sources:
     - reference/v5/database/schema.md#Relationships
     - reference/v5/rest/querying.md#Relationships and Joins
-  sourceCommit: 4fe4c9c95e0974eaa77032f6f10e36fbd8ec64ac
-  inputHash: 6953f507f0cde0f7
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: fd399fd81a88f13e
 ---
 
 # Defining Relationships Between Tables in Harper
@@ -16,17 +16,17 @@ Instructions for the agent to follow when defining and querying relationships be
 
 ## When to Use
 
-Apply this rule whenever a schema requires linking two tables via a foreign key — for example, modeling shows and networks, products and brands, or orders and items. Use it when queries need to filter or select nested related records using dot-syntax.
+Apply this rule when adding foreign key relationships between schema tables, enabling join queries, or returning nested related records in query results. Use it any time a schema type needs to reference records in another table via a foreign key attribute.
 
 ## How It Works
 
-1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on a field in the current table when the foreign key lives in this table and references the primary key of the target table.
+1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on the field in the table that holds the foreign key. The `from` parameter names the attribute on this table that stores the foreign key referencing the target table's primary key.
 
    ```graphql
    type RealityShow @table @export {
    	id: Long @primaryKey
    	networkId: Long @indexed
-   	network: Network @relationship(from: networkId)
+   	network: Network @relationship(from: networkId) # many-to-one
    	title: String @indexed
    }
 
@@ -36,7 +36,7 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    }
    ```
 
-   For a many-to-many relationship, make the foreign key an array:
+   If the foreign key attribute is an array, the relationship becomes many-to-many:
 
    ```graphql
    type RealityShow @table @export {
@@ -46,24 +46,24 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    }
    ```
 
-2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on a field in the current table when the foreign key lives in the target table and references the primary key of this table. The result type must be an array.
+2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on the table whose primary key is referenced by the foreign key in the target table. The `to` parameter names the attribute on the target table that holds the foreign key. The result type **must** be an array.
 
    ```graphql
    type Network @table @export {
    	id: Long @primaryKey
    	name: String @indexed
-   	shows: [RealityShow] @relationship(to: networkId)
+   	shows: [RealityShow] @relationship(to: networkId) # one-to-many
    }
    ```
 
-3. **Use `@relationship(from: attribute, to: attribute)` for foreign key to foreign key joins**: Specify both `from` and `to` when neither side uses the primary key. This is useful for joining on non-primary-key attributes.
+3. **Use `@relationship(from: attribute, to: attribute)` for foreign key to foreign key joins**: Specify both `from` and `to` when neither side uses the primary key. Harper resolves the relationship by searching the target table's `to` attribute for matches using this record's `from` attribute value. The result type must be an array.
 
    ```graphql
    type OrderItem @table @export {
    	id: Long @primaryKey
    	orderId: Long @indexed
    	productSku: Long @indexed
-   	product: Product @relationship(from: productSku, to: sku)
+   	products: [Product] @relationship(from: productSku, to: sku)
    }
 
    type Product @table @export {
@@ -73,15 +73,14 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    }
    ```
 
-4. **Query across relationships using dot-syntax**: Filter by related table attributes using chained dot notation. This behaves as an INNER JOIN.
+4. **Query across relationships using dot-syntax**: Filter records by related table attributes using chained dot notation. This behaves as an INNER JOIN — only records with a matching related record are returned.
 
    ```
-   GET /RealityShow?network.name=Bravo
    GET /Product/?brand.name=Microsoft
    GET /Brand/?products.name=Keyboard
    ```
 
-5. **Select nested relationship fields with `select()`**: Relationship attributes are not included by default. Use `select()` to include them in results. When selecting without a filter on the related table, this acts as a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
+5. **Include relationship fields in results using `select()`**: Relationship attributes are not returned by default. Use `select()` to include them, optionally specifying nested fields with `{}`.
 
    ```
    GET /Product/?brand.name=Microsoft&select(name,brand)
@@ -89,77 +88,56 @@ Apply this rule whenever a schema requires linking two tables via a foreign key
    GET /Product/?name=Keyboard&select(name,brand{name,id})
    ```
 
-## Examples
-
-**Many-to-one relationship** — a show belongs to a network:
+   When selecting a relationship without filtering on it, Harper performs a LEFT JOIN — the relationship property is omitted if the foreign key is null or references a non-existent record.
 
-```graphql
-type RealityShow @table @export {
-	id: Long @primaryKey
-	networkId: Long @indexed
-	network: Network @relationship(from: networkId)
-	title: String @indexed
-}
+6. **Model many-to-many without a junction table**: Store an array of foreign key values and use `@relationship(from: ...)` pointing to that array attribute. The array order of the foreign key values is preserved when resolving the relationship.
 
-type Network @table @export {
-	id: Long @primaryKey
-	name: String @indexed
-}
-```
+   ```graphql
+   type Product @table @export {
+   	id: Long @primaryKey
+   	name: String
+   	resellerIds: [Long] @indexed
+   	resellers: [Reseller] @relationship(from: "resellerIds")
+   }
+   ```
 
-Query:
+7. **Define self-referential relationships** for parent-child hierarchies by pointing `@relationship` back at the same table type.
 
-```
-GET /RealityShow?network.name=Bravo
-```
+## Examples
 
-**One-to-many relationship** — a network has many shows:
+**Full schema with bidirectional relationships:**
 
 ```graphql
-type Network @table @export {
+type Product @table @export {
 	id: Long @primaryKey
-	name: String @indexed
-	shows: [RealityShow] @relationship(to: networkId)
+	name: String
+	brandId: Long @indexed
+	brand: Brand @relationship(from: "brandId")
 }
-```
 
-**Many-to-many with array foreign keys** — a product has multiple resellers:
-
-```graphql
-type Product @table @export {
+type Brand @table @export {
 	id: Long @primaryKey
 	name: String
-	resellerIds: [Long] @indexed
-	resellers: [Reseller] @relationship(from: resellerIds)
+	products: [Product] @relationship(to: "brandId")
 }
 ```
 
-Query with nested select:
+**Querying with joins and nested select:**
 
 ```
-GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
+GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
+GET /Brand/?products.name=Keyboard
 ```
 
-**Foreign key to foreign key join** — order item joined on SKU:
+**Many-to-many query with nested select:**
 
-```graphql
-type OrderItem @table @export {
-	id: Long @primaryKey
-	orderId: Long @indexed
-	productSku: Long @indexed
-	product: Product @relationship(from: productSku, to: sku)
-}
-
-type Product @table @export {
-	id: Long @primaryKey
-	sku: Long @indexed
-	name: String
-}
+```
+GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
 ```
 
 ## Notes
 
-- The `@relationship` directive requires the referenced attribute to be `@indexed` on the foreign key side.
-- Self-referential relationships are supported, enabling parent-child hierarchies within a single table.
-- The array order of foreign key values (e.g., `resellerIds`) is preserved when resolving many-to-many relationships.
-- When using `select()` without a filter on the related table, the join behaves as a LEFT JOIN — missing or null foreign keys result in the relationship property being omitted rather than causing an error.
+- Every attribute named in `from` or `to` must exist on the respective table and be annotated with `@indexed` to support join queries.
+- The `to`-only and `from`+`to` forms both require the result field type to be an array (e.g., `[RealityShow]`).
+- The `from`-only form on a non-array attribute produces a many-to-one relationship; on an array attribute it produces many-to-many.
+- Self-referential relationships are supported for hierarchical data within a single table.

package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md

@@ -8,28 +8,32 @@ metadata:
     - >-
       fabric/cluster-creation-management.md#Connecting the Harper CLI to a
       Cluster
-  sourceCommit: b7fbddadd42eb4487190b650a9abc4bcfeef5819
-  inputHash: ccdefbbf8f3b8657
+  sourceCommit: 3749d0c54be457a2a65d9a63c738a5dc88989ecd
+  inputHash: 39faf283b6964e93
 ---
 
 # Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying a Harper application to the Harper Fabric cloud using the Harper CLI.
+Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cloud instance.
 
 ## When to Use
 
-Apply this rule when deploying a Harper application to a remote Harper instance or Harper Fabric cluster. This covers interactive deployments, CI/CD pipelines, and any scenario where the agent must push a local or remote package to a target environment.
+Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. Use it when setting up CI/CD pipelines that push application packages to a target environment, or when deploying from a local directory or external package source to a remote cluster.
 
 ## How It Works
 
-1. **Authenticate with the remote target**: Run `harper login` once to store an authentication token. The CLI writes `HARPER_CLI_TARGET` to a local `.env` so subsequent commands do not need credentials repeated. Find the **Application URL** on the cluster's **Config → Overview** page (see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md)).
+1. **Obtain the target URL**: Get the cluster's **Application URL** from the cluster's **Config → Overview** page. This is the hostname passed to all CLI commands as `target`.
+
+2. **Authenticate with `harper login`**: Run `harper login` once to store an authentication token locally. The CLI also writes `HARPER_CLI_TARGET` to a local `.env` for subsequent commands.
 
    ```bash
    harper login <Application URL>
    # Provide cluster username and password when prompted
    ```
 
-2. **Deploy the application**: Run `harper deploy` with the required parameters. After logging in, no credentials are needed inline.
+   See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for setting up a cluster before this step.
+
+3. **Deploy with `harper deploy`**: After logging in, deploy without repeating credentials.
 
    ```bash
    harper deploy \
@@ -40,83 +44,93 @@ Apply this rule when deploying a Harper application to a remote Harper instance
      replicated=true
    ```
 
-3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and deploy the current local directory.
-
-   | Value                                                | Effect                                           |
-   | ---------------------------------------------------- | ------------------------------------------------ |
-   | _(omitted)_                                          | Packages and deploys the current local directory |
-   | `"@harperdb/status-check"`                           | npm package                                      |
-   | `"HarperDB/status-check"`                            | GitHub repo (short form)                         |
-   | `"https://github.com/HarperDB/status-check"`         | GitHub repo (full URL)                           |
-   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                             |
-   | `"https://example.com/application.tar.gz"`           | Remote tarball                                   |
-
-   For git tags, use the `semver` directive for reliable versioning:
+4. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables before running `harper deploy`.
 
-   ```
-   HarperDB/application-template#semver:v1.0.0
+   ```bash
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
    ```
 
-4. **Authenticate for CI/CD pipelines**: Use environment variables instead of interactive login. Set credentials before running `harper deploy`.
+5. **Use inline auth parameters for one-off commands**: Pass `auth_username` and `auth_password` directly. These take precedence over environment variables and saved login tokens. Not recommended for production.
 
    ```bash
-   export HARPER_CLI_USERNAME=<username>
-   export HARPER_CLI_PASSWORD=<password>
    harper deploy \
      project=<name> \
      package=<package> \
+     auth_username=<username> \
+     auth_password=<password> \
      target=<remote> \
      restart=true \
      replicated=true
    ```
 
-5. **Register SSH keys for private repos**: Before deploying from an SSH-based private repository, use the Add SSH Key operation to register the key with the remote instance.
+6. **Choose a package source**: Set the `package` parameter to any valid npm dependency value, or omit it to package and deploy the current local directory.
+
+   | Value                                                | Meaning                                        |
+   | ---------------------------------------------------- | ---------------------------------------------- |
+   | _(omitted)_                                          | Package and deploy the current local directory |
+   | `"@harperdb/status-check"`                           | npm package                                    |
+   | `"HarperDB/status-check"`                            | GitHub shorthand                               |
+   | `"https://github.com/HarperDB/status-check"`         | GitHub full URL                                |
+   | `"git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo via SSH                           |
+   | `"https://example.com/application.tar.gz"`           | Remote tarball                                 |
+
+   For pinned git tags, use the `semver` directive:
+
+   ```
+   HarperDB/application-template#semver:v1.0.0
+   ```
+
+   For SSH-based private repos, register keys with the `Add SSH Key` operation before deploying.
 
 ## Examples
 
-**Interactive login then deploy (recommended):**
+**Interactive login then deploy:**
 
 ```bash
-# Log in once
-harper login <remote>
-# Provide your username and password when prompted
+harper login https://my-cluster.harperdbcloud.com
+# Enter username and password when prompted
 
-# Subsequently deploy without credentials
 harper deploy \
-  project=<name> \
-  package=<package> \
-  target=<remote> \
+  project=my-app \
+  package="HarperDB/application-template#semver:v1.0.0" \
+  target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy with inline credentials (not recommended for production):**
+**CI/CD pipeline deploy using environment variables:**
 
 ```bash
+export HARPER_CLI_USERNAME=admin
+export HARPER_CLI_PASSWORD=secret
 harper deploy \
-  project=<name> \
-  package=<package> \
-  username=<username> \
-  password=<password> \
-  target=<remote> \
+  project=my-app \
+  package="@harperdb/status-check" \
+  target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
-**Deploy a specific GitHub release by semver tag:**
+**Deploy current local directory:**
 
 ```bash
 harper deploy \
   project=my-app \
-  package="HarperDB/application-template#semver:v1.0.0" \
-  target=<remote> \
+  target=https://my-cluster.harperdbcloud.com \
   restart=true \
   replicated=true
 ```
 
 ## Notes
 
-- Always prefer `harper login` for interactive use and environment variables (`HARPER_CLI_USERNAME`, `HARPER_CLI_PASSWORD`) for CI/CD. Avoid inline `username`/`password` parameters in production.
-- Omitting `package` causes the CLI to package the current local directory. Specifying a local file path creates a symlink, so changes are picked up between restarts without redeploying.
-- Harper generates a `package.json` from component configurations and resolves dependencies using a form of `npm install`.
-- For SSH-based private repos, register keys with the Add SSH Key operation before deploying.
+- Authentication precedence (highest to lowest): inline `auth_username`/`auth_password` parameters → environment variables (`HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`) → saved login token from `harper login`.
+- `harper login` writes `HARPER_CLI_TARGET` to a local `.env`, so subsequent commands do not need `target` repeated if that file is present.
+- Harper generates a `package.json` from component configurations and resolves packages via `npm install`. A local file path creates a symlink, so changes are picked up between restarts without redeploying.
+- For SSH-based private repos, register the SSH key with the `Add SSH Key` operation before running `harper deploy`.