@harperfast/template-react-ts-studio 1.12.8 → 1.12.10

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

@@ -12,8 +12,8 @@ metadata:
     - reference/v5/rest/overview.md#Content Types
     - reference/v5/rest/overview.md#OpenAPI
     - reference/v5/rest/websockets.md
-  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
-  inputHash: a9356e92dd3dc106
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: fc3e7ae596f475b2
 ---
 
 # Automatic APIs
@@ -22,25 +22,26 @@ Instructions for the agent to follow when using Harper's automatically generated
 
 ## When to Use
 
-Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for Harper tables without writing custom handler code. Use it whenever a schema type needs to be served over HTTP, when configuring real-time subscriptions, or when setting up conditional caching behavior for REST responses.
+Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for Harper tables and custom resources. Use it whenever you need to configure the REST plugin, understand the auto-generated endpoint surface, or wire up real-time WebSocket connections. See [querying-rest-apis.md](querying-rest-apis.md) for query syntax and [real-time-apps.md](real-time-apps.md) for real-time patterns.
 
 ## How It Works
 
-1. **Enable REST in `config.yaml`**: Add `rest: true` to the application configuration file. This registers REST endpoints and, by default, WebSocket subscriptions for all exported resources.
+1. **Enable the REST plugin** by adding `rest: true` to your application's `config.yaml`:
 
    ```yaml
    rest: true
    ```
 
-   To configure options explicitly:
+   Extended options:
 
    ```yaml
    rest:
      lastModified: true # enables Last-Modified response header support
      webSocket: false # disables automatic WebSocket support (enabled by default)
+     exactCount: true # opt in to Prefer: count=exact scans (off by default)
    ```
 
-2. **Export the table in the schema**: Add `@export` to the type definition. Without `@export`, Harper registers no REST route and callers receive `404`. Without `rest: true`, even an exported table does not respond to HTTP requests. Both are required.
+2. **Export the table in your schema** using `@export`. Tables are not exposed by default — `@export` is required for Harper to register a REST route:
 
    ```graphql
    type Product @table @export {
@@ -50,46 +51,41 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
    }
    ```
 
-   Reference the schema file in `config.yaml`:
+   Without `@export`, the table has no REST route and callers receive `404`. Without `rest: true` in `config.yaml`, even an exported table does not respond to HTTP requests.
 
-   ```yaml
-   graphqlSchema:
-     files: schema.graphql
-   rest: true
-   ```
+3. **Understand the auto-generated endpoints**. With both `@export` and `rest: true` in place, Harper registers the following on the application HTTP server port (default `9926`):
 
-3. **Use the automatically registered endpoints**: Harper serves the following endpoints on the application HTTP server port (default `9926`) with no route definitions or handler code required.
+   | Endpoint                     | Description                                                                          |
+   | ---------------------------- | ------------------------------------------------------------------------------------ |
+   | `GET /Product`               | Resource description — table name, database, declared attributes                     |
+   | `GET /Product/`              | Record collection; append query parameters to filter, sort, page                     |
+   | `GET /Product/{id}`          | Single record by primary key; `404` if not found                                     |
+   | `GET /Product/{id}.property` | Single declared property of one record                                               |
+   | `POST /Product/`             | Creates a record; responds `201`; primary key returned in `Location` header          |
+   | `PUT /Product/{id}`          | Creates or replaces the record at `{id}` (upsert); omitted properties are removed    |
+   | `PATCH /Product/{id}`        | Shallow-merges body into existing record; unspecified top-level properties preserved |
+   | `DELETE /Product/{id}`       | Deletes the record at `{id}`                                                         |
+   | `DELETE /Product/?query`     | Deletes every record matching the query                                              |
+   - `HEAD` is served exactly as `GET` with the response body omitted. `QUERY` is accepted on the collection path (`QUERY /Product/`) and runs a search taken from the request body rather than the URL.
 
-   | Endpoint                     | Description                                                                 |
-   | ---------------------------- | --------------------------------------------------------------------------- |
-   | `GET /Product`               | Returns resource description (table name, database, attributes)             |
-   | `GET /Product/`              | Returns the record collection; append query parameters to filter            |
-   | `GET /Product/{id}`          | Returns a single record by primary key; `404` if not found                  |
-   | `GET /Product/{id}.property` | Returns a single declared property of one record                            |
-   | `POST /Product/`             | Creates a record; responds `201`; primary key returned in `Location` header |
-   | `PUT /Product/{id}`          | Creates or replaces the record at `{id}` (upsert)                           |
-   | `PATCH /Product/{id}`        | Merges body into existing record (shallow, top-level only)                  |
-   | `DELETE /Product/{id}`       | Deletes the record at `{id}`                                                |
-   | `DELETE /Product/?query`     | Deletes every record matching the query                                     |
+4. **Use the correct URL structure**. The trailing slash is significant:
 
-4. **Handle `POST` primary key and `Location`**: On a successful `POST`, the new record's primary key is returned in the `Location` response header — the value the body supplied if it carried the primary-key property, otherwise a Harper-assigned key. The header carries the bare key value, not a URL.
+   | Path                      | Addresses                                      |
+   | ------------------------- | ---------------------------------------------- |
+   | `/my-resource`            | The resource itself (metadata)                 |
+   | `/my-resource/`           | The record collection                          |
+   | `/my-resource/record-id`  | A specific record by primary key               |
+   | `/my-resource/record-id/` | Collection of records with the given id prefix |
 
-5. **Understand `PUT` write behavior**: `PUT` replaces the stored record exactly. Three exceptions always apply: a `@createdTime` attribute keeps the original value, an `@updatedTime` attribute is re-stamped with the time of the write, and the primary key is forced to match the `{id}` in the URL.
+5. **Handle `POST` primary keys via `Location`**. On a successful `POST`, the new record's primary key is returned in the `Location` response header — the value supplied by the body, or a Harper-assigned key if the body omitted the primary-key property.
 
-6. **Use conditional requests for caching**: GET responses include an `ETag` header encoding the record's version/last-modification time. Send `If-None-Match` on subsequent requests with the cached `ETag` value. If the record has not changed, Harper returns `304 Not Modified` with no body.
+6. **Use conditional GET requests for caching**. GET responses include an `ETag` header. Send `If-None-Match` on subsequent requests; if the record is unchanged, Harper returns `304 Not Modified` with no body.
 
-7. **Select content type with `Accept`**: Use the `Accept` header to request a specific response format. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors on property paths and take precedence over property names. See [querying-rest-apis.md](querying-rest-apis.md) for query syntax details.
+7. **Apply `@updatedTime` for write timestamps**. On `PUT`, Harper re-stamps any `@updatedTime` attribute with the time of the write, preserves any `@createdTime` value from the original record, and forces the primary key to match the `{id}` in the URL.
 
-8. **Connect via WebSocket**: WebSocket support is enabled automatically when `rest` is enabled. Connecting to a resource URL subscribes to changes for that resource. See [real-time-apps.md](real-time-apps.md) for real-time patterns.
-
-   ```javascript
-   let ws = new WebSocket('wss://server/my-resource/341');
-   ws.onmessage = (event) => {
-   	let data = JSON.parse(event.data);
-   };
-   ```
+8. **Control OpenAPI visibility**. Every non-hidden exported resource appears in the generated OpenAPI document at `GET /openapi`. To exclude a type, mark it `@hidden` in the schema, or set `static hidden = true` on a programmatic resource class.
 
-9. **Implement a custom `connect()` handler** when default subscription behavior is insufficient. The method must return an async iterable that produces messages to send to the client.
+9. **Implement a custom `connect()` handler** when default subscription behavior is insufficient. The method must return an async iterable that produces messages to send to the client:
 
    ```javascript
    export class Echo extends Resource {
@@ -101,9 +97,28 @@ Apply this rule when enabling HTTP REST endpoints or WebSocket subscriptions for
    }
    ```
 
+10. **Connect via WebSocket**. WebSocket support is enabled automatically with `rest: true`. Connect to a resource URL to subscribe to change events:
+
+    ```javascript
+    let ws = new WebSocket('wss://server/my-resource/341');
+    ws.onmessage = (event) => {
+    	let data = JSON.parse(event.data);
+    };
+    ```
+
+    Disable WebSocket support independently with `webSocket: false` under `rest`.
+
+11. **Use MQTT over WebSockets** by setting the sub-protocol header:
+
+    ```
+    Sec-WebSocket-Protocol: mqtt
+    ```
+
+12. **Specify response format** using the `Accept` header. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors on property paths and take precedence over property names.
+
 ## Examples
 
-### Full schema and config setup
+**Schema and config for a REST-enabled table:**
 
 ```graphql
 # schema.graphql
@@ -121,89 +136,77 @@ graphqlSchema:
 rest: true
 ```
 
-### Conditional GET with ETag caching
-
-```
-GET /Product/123
-# Response includes:
-# ETag: "abc123"
+**Conditional GET with ETag caching:**
 
+```http
 GET /Product/123
 If-None-Match: "abc123"
-# Response: 304 Not Modified (no body transferred)
 ```
 
-### POST and read the Location header
+Response when unchanged:
 
 ```
-POST /Product/
-Content-Type: application/json
-
-{ "name": "Widget", "price": 9.99 }
-
-# Response:
-# 201 Created
-# Location: 7f3a9c
+HTTP/1.1 304 Not Modified
+ETag: "abc123"
 ```
 
-### PATCH (shallow merge only)
+**POST and read the Location header:**
 
-```
-PATCH /Product/123
+```http
+POST /Product/
 Content-Type: application/json
 
-{ "price": 12.99 }
+{ "name": "Widget" }
 ```
 
-Only `price` is updated; other top-level properties are preserved. Nested objects in the body replace the stored sub-object wholesale — deep merge does not occur.
-
-### Request MessagePack response
-
 ```
-GET /Product/123
-Accept: application/msgpack
+HTTP/1.1 201 Created
+Location: 7f3a9c
 ```
 
-Alternatively, use the `.msgpack` suffix on the URL path where supported.
+**PATCH (shallow merge only):**
 
-### WebSocket with custom outgoing messages
+```http
+PATCH /Product/123
+Content-Type: application/json
 
-```javascript
-export class Example extends Resource {
-	connect(incomingMessages) {
-		let outgoingMessages = super.connect();
+{ "status": "active" }
+```
 
-		let timer = setInterval(() => {
-			outgoingMessages.send({ greeting: 'hi again!' });
-		}, 1000);
+**Custom WebSocket connect handler:**
 
-		incomingMessages.on('data', (message) => {
-			outgoingMessages.send(message);
-		});
+```javascript
+export class Echo extends Resource {
+	async *connect(incomingMessages) {
+		for await (let message of incomingMessages) {
+			yield message; // echo each message back
+		}
+	}
+}
+```
 
-		outgoingMessages.on('close', () => {
-			clearInterval(timer);
-		});
+**Hide a resource from OpenAPI — schema directive:**
 
-		return outgoingMessages;
-	}
+```graphql
+type InternalLog @table @export @hidden {
+	id: Long @primaryKey
 }
 ```
 
-### Disable WebSocket while keeping REST
+**Hide a resource from OpenAPI — programmatic class:**
 
-```yaml
-rest:
-  webSocket: false
+```javascript
+export class InternalLog extends Resource {
+	static hidden = true;
+}
 ```
 
 ## Notes
 
-- The trailing slash is significant: `/Product` addresses the resource itself; `/Product/` addresses its record collection. `POST /Product` (no trailing slash) returns `404`.
-- `HEAD` is served as `GET` with the body omitted. `QUERY` is accepted on the collection path and reads its search from the request body.
-- A `POST` to an existing primary key fails with `409` — it does not overwrite.
-- A component directory with **no configuration file** gets REST enabled by Harper's built-in default. As soon as a `config.yaml` exists it is used verbatim — add `rest: true` explicitly or REST is off.
-- Do not apply `@export` to a schema type and also export a same-named JavaScript subclass of that table — this produces conflicting endpoints.
-- Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`. They are not affected by the `webSocket` option.
-- Every non-hidden exported resource is included in the generated OpenAPI document at `GET /openapi`. Mark a type `@hidden` or set `static hidden = true` on a programmatic Resource to omit it.
-- MQTT over WebSockets requires the sub-protocol header `Sec-WebSocket-Protocol: mqtt`.
+- A component directory with **no** `config.yaml` inherits Harper's built-in default, which enables `rest` automatically. As soon as a `config.yaml` exists, it is used verbatim — omitting `rest` from it disables REST even if the directory previously had it without a config file. Always add `rest: true` when adding a config file.
+- `POST /Product` (no trailing slash) returns `404`. The trailing slash is required for collection operations.
+- A `POST` to a primary key that already exists fails with `409` rather than overwriting.
+- PATCH merge is **shallow** — a nested object in the body replaces the stored nested object wholesale; nested properties not included in the body are dropped.
+- The `.msgpack` suffix (along with `.json`, `.cbor`, `.csv`) is reserved as a content-type selector and cannot be used as a property name in dot-path access.
+- Server-Sent Events subscriptions are served on the same paths, negotiated via `Accept: text/event-stream`; they are not affected by the `webSocket` option.
+- See [querying-rest-apis.md](querying-rest-apis.md) for full query syntax on collection endpoints and [real-time-apps.md](real-time-apps.md) for real-time subscription patterns.

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

@@ -8,8 +8,8 @@ metadata:
     - >-
       fabric/cluster-creation-management.md#Connecting the Harper CLI to a
       Cluster
-  sourceCommit: 677ad213d67822e109c83619e181ca23a59823db
-  inputHash: e5586ad2bcc7c12a
+  sourceCommit: 2cfb81318f17e0aca2d600109e6ad813d2d0443e
+  inputHash: c821d15a19e2370f
 ---
 
 # Deploying to Harper Fabric
@@ -18,7 +18,7 @@ Instructions for the agent to follow when deploying a Harper application to a re
 
 ## When to Use
 
-Apply this rule when deploying a Harper application to a remote Harper Fabric cluster or any remote Harper instance. This includes first-time deploys, redeployments, rollbacks, CI/CD pipeline deploys, and provisioning credentials for private repositories. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for setting up the cluster before deploying.
+Apply this rule when deploying a Harper application to a remote Harper instance or Fabric cluster, including first-time deploys, redeployments, rollbacks, and CI/CD pipeline deployments. Also apply it when provisioning credentials for private repository deploys. See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) for setting up the cluster before deploying.
 
 ## How It Works
 
@@ -29,7 +29,7 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
    # Provide cluster username and password when prompted
    ```
 
-2. **Deploy the application**: After login, run `harper deploy` without repeating credentials. Set `restart=true` and `replicated=true` for a production deploy.
+2. **Deploy the application**: After login, run `harper deploy` without repeating credentials. Use `restart=true` and `replicated=true` for production deploys.
 
    ```bash
    harper deploy \
@@ -40,42 +40,32 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
      replicated=true
    ```
 
-3. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables before calling `harper deploy`.
+3. **Choose a package source**: Set the `package` parameter to any valid npm dependency value. Options:
 
-   ```bash
-   export HARPER_CLI_USERNAME=<username>
-   export HARPER_CLI_PASSWORD=<password>
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     target=<remote> \
-     restart=true \
-     replicated=true
-   ```
-
-4. **Choose a package source**: The `package` field accepts any valid npm dependency value. Select the form that matches your source:
-
-   | Source                  | `package` value                                      |
-   | ----------------------- | ---------------------------------------------------- |
-   | Current local directory | Omit `package`                                       |
-   | npm package             | `"@harperdb/status-check"`                           |
-   | GitHub (public)         | `"HarperFast/status-check"` or full URL              |
-   | Private repo (SSH)      | `"git+ssh://git@github.com:HarperDB/secret-app.git"` |
-   | Tarball                 | `"https://example.com/application.tar.gz"`           |
+   | Source                  | Example value                                                |
+   | ----------------------- | ------------------------------------------------------------ |
+   | Current local directory | Omit `package`                                               |
+   | npm package             | `package="@harperdb/status-check"`                           |
+   | GitHub (shorthand)      | `package="HarperFast/status-check"`                          |
+   | GitHub (URL)            | `package="https://github.com/HarperFast/status-check"`       |
+   | Private repo (SSH)      | `package="git+ssh://git@github.com:HarperDB/secret-app.git"` |
+   | Tarball                 | `package="https://example.com/application.tar.gz"`           |
 
-   For git tags, use the `semver` directive:
+   When using git tags, use the `semver` directive:
 
    ```
    HarperFast/application-template#semver:v1.0.0
    ```
 
-5. **Deploy by reference for reproducible deploys**: Pass `by_ref=true` to send a pinned git SHA instead of uploading a snapshot. The cluster fetches and builds from that exact commit.
+4. **Deploy by reference (pinned commit)**: Use `by_ref=true` to send a pinned git reference instead of uploading a snapshot. The cluster fetches and builds from that exact commit SHA.
 
    ```bash
    harper deploy by_ref=true restart=true replicated=true
    ```
 
-   Use `ref` to target a specific commit, tag, or branch (resolved to a full SHA before sending):
+   - `by_ref` — Build the package reference from the local repository.
+   - `ref` _(optional)_ — Deploy a specific commit, tag, or branch instead of `HEAD`. Implies `by_ref`. Tags and branches in `refs/tags` and `refs/heads` namespaces are resolved to a full commit SHA before the deploy is sent.
+   - `credential` _(optional)_ — Set to `true` to authenticate the clone with the stored credential for the repository's host. Omit for public repositories.
 
    ```bash
    # Deploy a specific tag
@@ -85,32 +75,61 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
    harper deploy ref=9f8c2a1 restart=true replicated=true
    ```
 
-   **Key constraints for `ref` values:**
-   - Must name something a clone can fetch: `refs/heads/*` and `refs/tags/*`, or a bare branch or tag name.
-   - Anything else (e.g., `refs/pull/123/head`) is rejected up front.
-   - If a ref can't be resolved, the deploy stops — run `git fetch` and retry, or pass a full commit SHA.
-   - Commit and push before deploying: the cluster clones from the remote and only sees pushed commits.
+   **Important constraints on refs:**
+   - A full commit SHA is accepted directly with no resolution.
+   - Every other `ref` must resolve to something a clone can fetch: `refs/tags/*` or `refs/heads/*`, or a bare branch or tag name.
+   - Qualified refs outside those two namespaces (e.g., `refs/pull/123/head`) are rejected.
+   - Commit and push before deploying — the cluster clones from the remote and only sees pushed commits.
+   - Run `git fetch` if a ref can't be resolved, or pass a full commit SHA.
 
-6. **Deploy private repositories by reference**: Pass `credential=true` alongside `by_ref=true`. The CLI attaches a credentials reference; the cluster resolves the secret in memory at clone time — no token travels in the operation body or lands on disk.
+5. **Handle private repositories**: Pass `credential=true` so the CLI attaches a credentials reference that the cluster resolves in memory at clone time. No token travels in the operation body or lands on disk.
 
    ```bash
    harper deploy by_ref=true credential=true restart=true replicated=true
    ```
 
-7. **Provision a deploy credential for private sources**: Run `harper deploy setup=true` once per component and source. This is interactive and requires **super_user** — run it with an administrative credential, not the CI identity.
+   Provision the credential once with `setup=true` before using `credential=true`.
+
+6. **Provision a deploy credential**: Run `harper deploy setup=true` once per component and source to provision credentials for private deploys. This operation requires **super_user** — run it with an administrative credential, not the CI identity.
 
    ```bash
    harper deploy setup=true
    ```
 
-   This command:
+   This interactive command:
    1. Fetches the cluster's public key with `get_secrets_public_key`.
    2. Encrypts the token locally into an `enc:v1:` envelope.
    3. Stores only the ciphertext with `set_secret`, in the component-scoped tier.
    4. Grants the component permission to resolve it with `grant_secret`.
    5. Prints the `credentials` reference for the deploy to use.
 
-   Use a **fine-grained** personal access token (PAT) scoped to **Contents: Read-only** on the specific repository. Avoid session tokens from `gh` CLI — they typically carry `repo`, `read:org`, `gist`, and `workflow` scopes across your whole account.
+   **Use a fine-grained PAT** for GitHub repositories. The prompt defaults to a fine-grained personal access token with **Contents: Read-only** on that one repository. If you use the `gh` CLI session token instead, it typically carries `read:org`, `repo`, `gist`, and `workflow` scopes across your whole account — the CLI prints a warning if you choose it. Use the narrowest credential that does the job, because the stored token is replayed on every cold deploy and rollback.
+
+7. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables.
+
+   ```bash
+   export HARPER_CLI_USERNAME=<username>
+   export HARPER_CLI_PASSWORD=<password>
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
+
+8. **Use dedicated auth parameters for one-off commands** (not recommended for production): Pass `auth_username` and `auth_password` directly. These take precedence over environment variables and saved login tokens.
+
+   ```bash
+   harper deploy \
+     project=<name> \
+     package=<package> \
+     auth_username=<username> \
+     auth_password=<password> \
+     target=<remote> \
+     restart=true \
+     replicated=true
+   ```
 
 ## Examples
 
@@ -126,41 +145,48 @@ harper deploy \
   replicated=true
 ```
 
-**CI/CD deploy using environment variables:**
+**Deploy by reference with a tag:**
 
 ```bash
-export HARPER_CLI_USERNAME=admin
-export HARPER_CLI_PASSWORD=secret
-harper deploy \
-  project=my-app \
-  package="HarperFast/my-app" \
-  target=https://my-cluster.harperdbcloud.com \
-  restart=true \
-  replicated=true
+harper deploy ref=v1.2.0 restart=true replicated=true
 ```
 
-**Deploy by reference in GitHub Actions (pull request):**
+**Deploy a private GitHub repo by reference:**
 
 ```bash
-harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
+# Provision credential once (requires super_user)
+harper deploy setup=true
+
+# Deploy using stored credential
+harper deploy by_ref=true credential=true restart=true replicated=true
 ```
 
-**Deploy a private repo by reference with a provisioned credential:**
+**GitHub Actions — pull request deploy:**
 
 ```bash
-# Provision once (run as super_user)
-harper deploy setup=true
+harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
+```
 
-# Deploy subsequently
-harper deploy by_ref=true credential=true restart=true replicated=true
+**CI/CD deploy using environment variables:**
+
+```bash
+export HARPER_CLI_USERNAME=<username>
+export HARPER_CLI_PASSWORD=<password>
+harper deploy \
+  project=my-app \
+  package="@myorg/my-app" \
+  target=https://my-cluster.harperdbcloud.com \
+  restart=true \
+  replicated=true
 ```
 
 ## Notes
 
-- `auth_username` and `auth_password` can be passed directly as deploy parameters for one-off commands, but this is not recommended for production. Dedicated authentication parameters take precedence over environment variables and saved login tokens.
+- The cluster's Application URL is found on the **Config → Overview** page of the Fabric dashboard.
+- `harper deploy setup=true` calls `get_secrets_public_key`, `set_secret`, and `grant_secret`, all of which require **super_user**. Do not run it with the CI identity.
 - The `enc:v1:` envelope means the plaintext token never leaves your machine — only ciphertext is stored and replicated.
-- Deploy credentials are stored scoped to the component, never in the global `processEnv` tier. If a global secret exists at the derived name, it is converted to the component-scoped tier automatically.
-- Because stored credentials are durable, later deploys and rollbacks reuse them without re-entering anything.
-- The unpushed-commit check is skipped under GitHub Actions; the dirty-tree warning still applies.
-- Deploying by reference means the cluster installs and builds from source. If your application requires a build step that cannot run on the node, deploy the built output as a payload deploy instead.
+- Secrets are stored scoped to the component, not in the global `processEnv` tier. If a global secret already exists at the derived name, it is converted to the scoped tier.
 - For SSH-based private repos, use the `add_ssh_key` operation to register keys before deploying.
+- If your application requires a build step that cannot run on the cluster node, deploy a built payload (omit `by_ref`) instead of deploying by reference.
+- The unpushed-commit check is skipped under GitHub Actions; the dirty-tree warning still applies.
+- Annotated tags in `refs/tags` resolve to the commit they point at, not the tag object.