@harperfast/template-vue-ts-studio 1.13.0 → 1.13.2

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

@@ -2320,24 +2320,25 @@ await fetch('http://localhost:9926/JokeCache/1', {
 
 ### 4.1 Deploying to Harper Fabric
 
-Instructions for the agent to follow when deploying a Harper application to a remote Harper Fabric cloud cluster.
+Instructions for the agent to follow when deploying a Harper application to a Harper Fabric cluster, or any remote Harper instance, with the `harper` CLI, and when checking, staging, or going back to a release.
 
 #### When to Use
 
-Apply this rule when deploying a Harper application to a remote Harper Fabric cluster, whether from a local machine or a CI/CD pipeline. Use it to configure authentication, select a package source, and run `harper deploy` with the correct parameters.
-
-See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md) to set up a cluster before deploying.
+Apply this rule when deploying to a remote cluster, choosing how it restarts, reading a deploy's `certification`, staging a release to make live later, or rolling back to a previous release. To deploy from CI with no stored credential, see [deploying-from-ci.md](deploying-from-ci.md). To set up the cluster first, see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md).
 
 #### How It Works
 
-1. **Authenticate against the cluster**: Run `harper login` once, pointing at the cluster's Application URL (found on the cluster's **Config → Overview** page). The CLI stores the token so subsequent commands need no credentials. If the current directory already has a `.env` file that sets no target, it also appends `HARPER_CLI_TARGET` to it.
+1. **Log in to the cluster once**: Pass the cluster's **Application URL**, from its **Config → Overview** page, to `harper login`. The CLI stores the token, so later commands don't repeat credentials. If the current directory already has a `.env` file that sets no target, it also appends `HARPER_CLI_TARGET` to it.
 
    ```bash
    harper login <Application URL>
    # Provide cluster username and password when prompted
    ```
 
-2. **Deploy the application**: After logging in, run `harper deploy` without repeating credentials. Omit `package` to package and deploy the current local directory.
+   - For CI/CD on GitHub Actions, use workload identity (OIDC) instead, so the pipeline stores no Harper credential. From v5.4.0, `harper deploy setup=true provider=github-actions` sets it up in one command: see [deploying-from-ci.md](deploying-from-ci.md). Elsewhere, give the pipeline a refresh token from `harper login --for-ci` rather than a password.
+   - For a one-off command, `auth_username=` and `auth_password=` also work, and take precedence over environment variables and saved login tokens. Don't use them in production.
+
+2. **Deploy with a restart**: Run `harper deploy`, with `restart=true` or `restart=rolling` so the release is certified before it serves (step 3).
 
    ```bash
    harper deploy \
@@ -2348,141 +2349,494 @@ See [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-clu
      replicated=true
    ```
 
-3. **Choose a package source**: Set `package` to any valid npm dependency value.
+   - On Harper Pro and Fabric, a deploy goes to every node in the cluster unless you pass `replicated=false`. Harper core on its own does not replicate.
+   - `project` defaults to the current directory's name for a directory deploy, or is derived from the package for a package deploy.
+   - A bare `target` host defaults to `https://<host>:9925`.
+   - Pass `json=true` to print the result as JSON instead of YAML.
+   - Every result carries a `deployment_id`, staged or not. It names this release when you go back to it later (step 4).
+
+3. **Choose the restart, and read `certification`**: `restart=true` restarts Harper after deploying. On a cluster, use `restart=rolling`, the staggered, zero-downtime restart: the command exits `0` once the node you called has taken the release and started the rolling restart's job, and returns its `restartJobId`.
 
-   | Value                                                        | Meaning                                        |
-   | ------------------------------------------------------------ | ---------------------------------------------- |
-   | _(omit)_                                                     | Package and deploy the current local directory |
-   | `package="@harperdb/status-check"`                           | npm package                                    |
-   | `package="HarperFast/status-check"`                          | GitHub shorthand                               |
-   | `package="https://github.com/HarperFast/status-check"`       | GitHub URL                                     |
-   | `package="git+ssh://git@github.com:HarperDB/secret-app.git"` | Private repo (SSH)                             |
-   | `package="https://example.com/application.tar.gz"`           | Tarball                                        |
+   Both certify the release in a canary worker before rolling it out. The canary replaces worker 0 and loads every component, but is held out of traffic until it reports whether the deployed component loaded. Until then, the workers already running keep serving the previous release. A deploy that succeeds, and is not staged, reports the result in `certification`:
 
-   When using git tags, use the `semver` directive:
+   | `certification` | Meaning                                                                                                                                                                                             |
+   | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `certified`     | The canary loaded the release, and the rollout went on.                                                                                                                                             |
+   | `uncertified`   | The rollout went on unchecked: the component ran nothing as it loaded (`loadComponent: dev-only`, an absent `if-installed` component, or safe mode), or no worker was replaced.                     |
+   | `unavailable`   | The deploy restarted unchecked: no worker on this node loads the component, its `isolated` setting changed, it was already live, or it was deployed from a local directory (`package: file:<dir>`). |
+   | `not-requested` | The deploy did not restart.                                                                                                                                                                         |
+   - **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes. The error's `certification` is an object whose `status` is `rejected`, or `interrupted` for a restart that stopped before the canary decided.
+   - **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed. Deploy a fix, or once the cause is fixed, activate the same `deployment_id` again with `restart`.
+   - **A rolling deploy exits before every node has taken the release.** The other nodes stage it, and the job activates it on each in turn, each with a canary of its own. A node that rejects it keeps the previous release, or fails closed if it had none. Nothing is rolled back on the others, and the job fails naming each node that did not activate it. The deployment record reports `success` while the job runs and after it fails, so poll the job instead: `harper get_job id=<restartJobId>` ends `COMPLETE`, or `ERROR` with a `message` listing each node's outcome under `activated`.
+   - **Poll the node that received the deploy.** A job is recorded only on the node that ran it, so any other node answers `get_job` with an empty array. A role with an `operations` allowlist, or a token with an `operations` scope, must list `get_job` to poll it.
+   - Another deploy or `drop_component` of the component on that node is refused with `409` until the rollout has finished.
+   - A node running a version before v5.4.0 activates the release without a canary.
 
+4. **Go back to a previous release by its `deployment_id`**: When a deploy replaces the live release, Harper keeps the replaced one under the `deployment_id` that deployed it. Activating that id puts back the exact installed release with no fetch, rebuild, or reinstall, where deploying an older commit installs it again from source. Find the id with `list_deployments`, then deploy it. On a cluster, restart with `rolling` and poll its job (step 3):
+
+   ```bash
+   harper list_deployments project=my-app status=success
+   harper deploy project=my-app deployment_id=<id> restart=rolling
    ```
-   HarperFast/application-template#semver:v1.0.0
+
+   ```json
+   {
+   	"operation": "deploy_component",
+   	"project": "my-app",
+   	"deployment_id": "<id of the deployment you want back>",
+   	"restart": "rolling"
+   }
    ```
 
-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 that exact commit.
+   - `list_deployments` returns records newest first. Filter by `project` and `status`; omit `limit` to return every matching record. A deploy in progress reads `pending`, or `loading`, until its `completed_at` is set.
+   - The newest `success` is not necessarily the release every node is serving: a rolling deploy's record says `success` before the other nodes have taken the release, and keeps saying it if one rejects it.
+   - Redeploy an older commit by `ref` (step 7) only when the release is no longer kept.
+   - The activation restores the root config entry that deployment published. The release it replaces is kept in turn, so you can go forward again the same way.
+   - Kept releases and staged builds count against `deployment.stagingRetention.maxCount` (default `5`). Each kept release is a full installed copy of the component, `node_modules` included, so budget disk for it. `0` keeps no replaced release.
+   - A release made live before v5.3.0, or deployed from a `file:` directory, is not kept.
+   - Each node answers for itself. A node that never had the release, or no longer keeps it, answers `404`, which `deploy_component` reports as a failed peer. `409` means the build is there but can't be activated.
 
-   ```bash
-   harper deploy by_ref=true restart=true replicated=true
+5. **Stage a release to make live later**: `activate=false` (`activate: false` in the operation) builds and installs the release on each node without making it live, so the slow, fallible part happens when you choose and the cut-over is quick. The result's `deployment_id` names the staged build:
+
+   ```json
+   {
+   	"operation": "deploy_component",
+   	"project": "my-app",
+   	"package": "npm:@my-org/my-app@1.2.3",
+   	"activate": false
+   }
    ```
 
-   - `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`. Resolved to a full commit SHA before being sent.
-   - `credential` _(optional)_ — Set to `true` to authenticate the clone with the stored credential for the repository's host. Omit for public repositories.
+   ```json
+   {
+   	"deployment_id": "a3f8c2d1-...",
+   	"message": "Staged: my-app. Deploy it with deploy_component deployment_id=a3f8c2d1-..."
+   }
+   ```
+
+   Make it live by deploying that `deployment_id`, as in step 4. Nothing changes until then, and `get_deployment` reports it as `staged`.
+   - Pass `restart` on the activation, not the stage: `restart` is rejected alongside `activate: false`.
+   - The activation takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host`. They are rejected, because the staged build already decided them.
+   - Activating the release that is already live succeeds without a swap, so if an activation fails partway (a peer was unreachable, or the root config entry wasn't written), retry the same `deployment_id`. A node that already switched answers success, one still holding the build switches now, and one that holds neither answers `404`; the retry also finishes what the failed attempt left half done. With `restart`, a node where the release is already live still restarts every worker, isolated applications' included. Without it, the node marks the component as needing a restart.
+   - A staged build outlives later deploys: stage v2, deploy v3, and activating v2's id returns the component to v2.
+   - `file:` directory sources cannot be staged.
+   - Upgrade every node before staging. A node before v5.3.0 doesn't recognize `activate: false`, and serves the release immediately. A peer that doesn't confirm staging fails the operation with the node names.
+
+6. **Choose a package source**: The `package` field accepts any valid npm dependency value:
 
-   Deploy a specific tag or commit:
+   | Source                  | `package` value                                                                               |
+   | ----------------------- | --------------------------------------------------------------------------------------------- |
+   | Current local directory | Omit `package`                                                                                |
+   | npm package             | `package="@harperdb/status-check"`                                                            |
+   | GitHub (public)         | `package="HarperFast/status-check"` or `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: `HarperFast/application-template#semver:v1.0.0`. For an SSH-based private repo, register the key with `add_ssh_key` first.
+
+7. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`. Pass `ref` to deploy a specific tag or commit instead of `HEAD`; it implies `by_ref`.
 
    ```bash
+   harper deploy by_ref=true restart=true replicated=true
    harper deploy ref=v1.2.0 restart=true replicated=true
    harper deploy ref=9f8c2a1 restart=true replicated=true
    ```
 
-   Valid `ref` values must resolve to `refs/heads/*` or `refs/tags/*`, or a bare branch or tag name. Qualified refs outside those two namespaces (e.g. `refs/pull/123/head`) are rejected. A full commit SHA is always accepted directly with no resolution attempted. Run `git fetch` if a ref can't be resolved, or pass a full commit SHA.
+   - A `ref` is resolved to a full commit SHA before the deploy is sent, from the local checkout or the remote. A full commit SHA is accepted directly. If a `ref` can't be resolved, the deploy stops: run `git fetch` and retry, or pass a full SHA.
+   - Any other `ref` must name something a clone can fetch: `refs/heads/*` or `refs/tags/*`, or a bare branch or tag name. A qualified ref outside those, such as `refs/pull/123/head`, is rejected up front.
+   - Commit and push first: the cluster clones from the remote. `by_ref` warns when the working tree is dirty, and when the commit isn't on any remote branch. The second check is skipped under GitHub Actions.
+   - On a GitHub Actions `pull_request` run, `by_ref` deploys the pull request's head commit. If the event payload isn't readable, the deploy stops; pass the commit explicitly.
+   - The cluster installs and builds from source on each node, so commit your lockfile if the build must be reproducible. If the build can't run on the node, deploy the built output as a payload instead.
+
+8. **Deploy a private repository by reference**: Pass `credential=true` with `by_ref=true`. The CLI attaches a `credentials` reference, and the cluster resolves the secret in memory at clone time, so no token travels in the operation body or lands on disk.
+
+   ```bash
+   harper deploy by_ref=true credential=true restart=true replicated=true
+   ```
+
+   Provision that credential once per component and source with `harper deploy setup=true`. (With `provider=github-actions`, it sets up GitHub Actions deploys instead: see [deploying-from-ci.md](deploying-from-ci.md).) It is interactive, and its operations require **super_user**, so run it with an administrative credential, not the CI identity it provisions for. It:
+   1. Fetches the cluster's public key with `get_secrets_public_key`.
+   2. Encrypts the token locally into an `enc:v1:` envelope, so the plaintext never leaves your machine.
+   3. Stores only the ciphertext with `set_secret`, scoped to the component, never in the global `processEnv` 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 with **Contents: Read-only** on that one repository. Avoid the `gh` CLI's session token: it typically carries `repo`, `read:org`, `gist`, and `workflow` scopes across your whole account. The sealed token is durable, and later deploys reuse it.
+
+#### Examples
+
+**Deploy after logging in, and wait for a rolling restart:**
+
+```bash
+harper login https://my-cluster.harperdbcloud.com
+harper deploy \
+  project=my-app \
+  package="HarperFast/my-app" \
+  target=https://my-cluster.harperdbcloud.com \
+  restart=rolling \
+  json=true > deploy.json
+# Poll the node that received the deploy until the job is COMPLETE or ERROR
+harper get_job id=<restartJobId from deploy.json> json=true
+```
+
+**Roll back to the release a deploy replaced, node by node:**
+
+```bash
+harper list_deployments project=my-app status=success
+harper deploy project=my-app deployment_id=<previous deployment_id> restart=rolling json=true
+# Then poll its restartJobId with get_job, as above
+```
+
+**Stage a release now, and make it live in a maintenance window:**
+
+```bash
+harper deploy project=my-app package=npm:@my-org/my-app@1.2.3 activate=false
+# Later, with the deployment_id the stage returned
+harper deploy project=my-app deployment_id=<staged deployment_id> restart=rolling
+```
+
+**Deploy a pull request's head commit by reference in GitHub Actions:**
+
+```bash
+harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
+```
+
+**Deploy a private repository by reference:**
+
+```bash
+# Once, as super_user
+harper deploy setup=true
+
+# Every deploy
+harper deploy by_ref=true credential=true restart=true replicated=true
+```
 
-   **Commit and push before deploying by reference.** The cluster clones from the remote and only sees pushed commits.
+### 4.2 Deploying a Harper Application from GitHub Actions with OIDC
 
-5. **Roll back to a previous release**: Activate a kept release by its `deployment_id` to restore the exact installed release without a fetch, rebuild, or reinstall.
+Instructions for the agent to configure and execute credential-free Harper deployments from GitHub Actions using OIDC trusted publishing, including one-command setup and complete workflow examples.
+
+#### When to Use
+
+Apply this rule when asked to deploy from CI, to set up or fix a deploy workflow (including the `.github/workflows/deploy.yaml` that create-harper projects ship), or to move a pipeline off a stored Harper credential such as `HARPER_CLI_REFRESH_TOKEN`. Use it when setting up OIDC trust for the first time, writing or debugging a deploy workflow, or revoking/rotating pipeline access.
+
+#### How It Works
+
+##### One-Command Setup (Branch-Based Deploys)
+
+1. **Run setup once** from the project checkout, signed in as a `super_user`:
 
    ```bash
-   harper deploy project=<name> deployment_id=<id> restart=true
+   harper login https://my-cluster.example.com:9925
+   harper deploy setup=true provider=github-actions project=my-app
    ```
 
-6. **Provision a deploy credential for private repositories**: Run `harper deploy setup=true` once per component and source. This requires **super_user** privileges — run it with an administrative credential.
+   If your workflow file is not `.github/workflows/deploy.yaml`, pass `workflow=` explicitly — otherwise the policy pins `deploy.yaml` and runs of your workflow cannot match it:
 
    ```bash
-   harper deploy setup=true
+   harper deploy setup=true provider=github-actions project=my-app workflow=.github/workflows/deploy.yml
    ```
 
-   The setup flow:
-   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`, scoped to the component.
-   4. Grants the component permission to resolve it with `grant_secret`.
-   5. Prints the `credentials` reference for the deploy to use.
+2. **Understand what setup does** — in order:
+   - Resolves the GitHub repository's numeric id and canonical name from the `origin` remote (or `repo=<owner>/<name>`). Pass `repository_id=<id>` when the API is unavailable (e.g., private repo without `gh`).
+   - **The workflow is checked before anything is written.** It must be able to run on `main` (`branch=`) and run a job in the `production` environment (`environment=`) with `permissions: id-token: write`; one that never could stops setup. What it can't decide is reported as not verified.
+   - Creates a role and a user named `<project>-ci-deploy` with permissions limited to `deploy_component`, `get_job`, and `registration_info`, and a trust policy named `github-actions-<project>`.
+   - Reads the policy back and compares it claim by claim with what it intended to write.
+   - Sets the repository's `HARPER_CLI_TARGET` Actions variable via `gh` if one does not already exist.
 
-   The plaintext never leaves your machine. Prefer a **fine-grained** personal access token with **Contents: Read-only** on the target repository. Avoid broad session tokens — they typically carry `read:org`, `gist`, and `workflow` scopes across your whole account.
+3. **Handle idempotency**: setup only creates — it never updates. A role, user, or policy that already exists but differs stops setup and names what differs. To replace a policy:
 
-7. **Deploy from a private repository**: Pass `credential=true` after provisioning the deploy credential.
+   ```bash
+   harper drop_oidc_trust id=github-actions-<project>
+   harper deploy setup=true provider=github-actions project=my-app
+   ```
+
+##### Manual Setup (Tag-Based or Custom Deploys)
+
+Use this path when deploying on version tags, because a branch-pinned policy cannot match a tag ref.
+
+1. **Create a deploy-only role and user**:
 
    ```bash
-   harper deploy by_ref=true credential=true restart=true replicated=true
+   harper add_role role=ci_deploy permission='{"operations":["deploy_component","get_job","get_deployment","registration_info"]}'
+   harper add_user username=ci-deploy role=ci_deploy active=true password="$(openssl rand -base64 32)"
    ```
 
-8. **Use one-off authentication parameters** (not recommended for production): Pass `auth_username` and `auth_password` directly. These take precedence over environment variables and saved login tokens.
+   - `deploy_component` — the deploy itself.
+   - `get_job` — required for the wait step; an `operations` allowlist refuses anything not listed, so without it the wait step fails with `403`.
+   - `get_deployment` — reads the deployment record.
+   - `registration_info` — version check `harper deploy` makes before uploading.
+   - `restart_service` is not needed: Harper starts the rolling restart's job itself. The password is required to create the user but a GitHub Actions pipeline never uses it, so this command discards it.
+
+2. **Add a trust policy** pinned to `repository_id`, `workflow_path`, and `environment` (use this shape when the tag is unknown at policy-write time):
 
    ```bash
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     auth_username=<username> \
-     auth_password=<password> \
-     target=<remote> \
-     restart=true \
-     replicated=true
+   harper add_oidc_trust \
+     id=my-app-release \
+     issuer=https://token.actions.githubusercontent.com \
+     audience=https://my-cluster.example.com:9925/ \
+     user=ci-deploy \
+     claims='{"repository_id":"67890","workflow_path":"my-org/my-app/.github/workflows/deploy.yml","environment":"production"}'
    ```
 
-9. **Use CI/CD pipelines**: For GitHub Actions, use workload identity (OIDC) so no Harper credential is stored in the pipeline. Alternatively, supply a refresh token from `harper login --for-ci`. On a `pull_request` run, pass the head SHA explicitly:
+   Key claim rules:
+   - `repository_id` is immutable — survives renames. Look it up with `gh api repos/my-org/my-app --jq .id`.
+   - `workflow_path` pins the workflow file. Harper derives it from the token's `workflow_ref` by removing the `@<ref>` suffix, so it is `<owner>/<repo>/<path>`.
+   - `environment` is the ref gate. Without it, anyone who can push a branch can mint a token.
+   - `audience` must be the exact target URL with its port and a **trailing slash**.
+   - A workflow that deploys on a push to `main` can pin `workflow_ref` (`my-org/my-app/.github/workflows/deploy.yml@refs/heads/main`) instead, which gates the ref by itself.
+
+3. **Configure the GitHub environment**: in **Settings → Environments → production**, set **Deployment branches and tags** to the `v*` tag pattern. Add required reviewers if a release needs approval.
+
+4. **Store the target as a repository variable** (not a secret — it is not sensitive):
 
    ```bash
-   harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
+   gh variable set HARPER_CLI_TARGET --repo my-org/my-app --body https://my-cluster.example.com:9925/
    ```
 
+##### How OIDC Authentication Works in the Workflow
+
+Once a trust policy exists, every `harper` command in the deploy job authenticates through it automatically when all four conditions hold:
+
+1. **The job may request an identity token.** On GitHub Actions that is `permissions: id-token: write` on the job.
+2. **`HARPER_CLI_TARGET` is the policy's `audience`.** The CLI requests its token for the target it connects to, so the target must be the URL the policy names, with its port and trailing slash. Use `vars.HARPER_CLI_TARGET` — it is not sensitive, so a repository variable rather than a secret.
+3. **The run matches the policy's claims**: its repository, its workflow file and branch, and its environment.
+4. **Nothing else is configured to authenticate.** `auth_username=`/`auth_password=`, credentials in the target URL, `HARPER_CLI_USERNAME`/`HARPER_CLI_PASSWORD`, `HARPER_CLI_REFRESH_TOKEN` or `HARPER_CLI_OPERATION_TOKEN`, and a saved `harper login` all outrank the exchange.
+
+What each command may then do is up to the role of the user the policy names: a role that lists only `deploy_component`, `get_job` and `registration_info`, like the one setup creates, refuses anything else with a `403`.
+
+The exchange runs only when GitHub sets `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, which it does for a job that declares `permissions: id-token: write`. Without them, the CLI falls through to its other credential sources rather than reporting a failure.
+
+Nothing in the workflow names the policy. The CLI prints to stderr which policy authenticated it and as whom:
+
+```
+Requesting a GitHub Actions identity token for https://my-instance.harperdb.io:9925/...
+Authenticated as 'ci-deploy' via OIDC trust policy 'my-app-prod'.
+```
+
+Diagnose a rejected exchange with `list_oidc_trust` (check for `invalid_reason` on each entry) and the instance's `oidc-trust` log. The server deliberately does not report which check failed.
+
+##### Policy Specificity for GitHub Actions
+
+For `https://token.actions.githubusercontent.com`, a policy must satisfy all three of these:
+
+| Requirement            | Satisfied by one of                                                      | Left open otherwise                             |
+| ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
+| **Pin the repository** | `repository_id`, `repository`                                            | Any repository                                  |
+| **Pin the workflow**   | `workflow_ref`, `workflow_path`, `job_workflow_ref`, `job_workflow_path` | Any workflow in that repository                 |
+| **Gate the ref**       | `workflow_ref`, `ref`, `environment`                                     | Any branch that can be pushed to the repository |
+
+Additional constraints:
+
+- `repository_id` is preferred over `repository` — it is immutable and survives renames.
+- A tag-triggered release cannot pin `workflow_ref` since the tag is unknown when the policy is written. Pin `workflow_path` and gate on `environment`.
+- `ref_type: tag` is not accepted as a ref gate, `sub` is not accepted as a pin, and `job_workflow_ref` pins the workflow without gating the ref. `pull_request_target` runs are denied unless the policy constrains `event_name`.
+
+##### Revoking Access
+
+- **Stop future runs**: `harper drop_oidc_trust id=github-actions-<project>` (does not revoke already-issued tokens, which are valid up to one hour).
+- **Stop an already-issued token**: `harper alter_user username=<project>-ci-deploy active=false`.
+- **No CI secret to rotate** — there is none.
+
 #### Examples
 
-**Login and deploy the current directory to a remote cluster:**
+##### Path A: Deploy a Tagged Release (`v1.2.3`) from the Repository
 
-```bash
-harper login https://my-cluster.harperdbcloud.com
-harper deploy \
-  project=my-app \
-  target=https://my-cluster.harperdbcloud.com \
-  restart=true \
-  replicated=true
+Push a semver tag (`v1.2.3`), and every node clones and installs that commit. `by_ref=true` deploys `git+https://github.com/<owner>/<repo>.git#<sha>`, where the SHA is the commit the tag points to (`GITHUB_SHA`), and every node clones that exact commit even if the tag moves later. For a private repository, add `credential=true` to attach the stored credential (`deploy.my-app.git.github.com`). If the repository needs a build step to be runnable, don't reach for `install_allow_scripts`: use Path B.
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Harper
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install --global harper@^5.3
+      - name: Deploy the tagged commit
+        run: harper deploy project=my-app by_ref=true restart=rolling json=true > deploy.json
+      - name: Wait for every node to take the release
+        run: |
+          JOB_ID=$(jq -r '.restartJobId // empty' deploy.json)
+          [ -n "$JOB_ID" ] || { echo "The rolling deploy returned no restartJobId"; exit 1; }
+          LAST="could not be read"
+          for attempt in $(seq 60); do
+            sleep 10
+            harper get_job id="$JOB_ID" json=true > job.json || continue
+            case $(jq -r '.[0].status // "MISSING"' job.json) in
+              COMPLETE) exit 0 ;;
+              ERROR) jq -r '.[0].message' job.json; exit 1 ;;
+              MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
+              *) LAST="was still running" ;;
+            esac
+          done
+          echo "After 60 polls, job $JOB_ID $LAST"
+          exit 1
+```
+
+Key details:
+
+- **No secrets.** `HARPER_CLI_TARGET` is the only thing the workflow is given. `id-token: write` lets the CLI request an identity token, and `environment: production` puts the `environment` claim the trust policy requires into it.
+- **`persist-credentials: false`** keeps the job's `GITHUB_TOKEN` out of `.git/config`.
+- **`harper@^5.3`** pins the CLI's major version. 5.3 is the first CLI that authenticates with the identity token.
+- **`replicated` isn't needed.** On Harper Fabric and Harper Pro, a deploy goes to every node unless you pass `replicated=false`. Each node fetches and installs the package itself.
+- **`restart=rolling`** restarts nodes one at a time. Use `restart=true` for a single-node or dev instance.
+- **`json=true`** prints the deploy's result as JSON on stdout; progress and authentication messages go to stderr.
+- **The wait step** polls `restartJobId` via `get_job` until `COMPLETE` or `ERROR`, checking `.[0].status`. It retries a poll that fails (such as one that reaches a node while it restarts) and gives up after 60 polls (~10 minutes).
+- **`certification`**: on v5.4.0 and later, `restart=rolling` loads the release in a canary worker on each node before that node serves it, so a release that fails to load is rejected. The `certification` field in the deploy result reflects this. With `restart=rolling` on v5.4.0 and later, the deploy can report `success` before the rolling job has visited all nodes — wait on the job, not the record.
+- **The job lives on one node.** Through a **load-balanced** cluster URL, polls must eventually reach that node. Routing that always sends polls to a different node than the deploy causes the wait step to fail saying the job was not on the node that answered.
+
+##### Path B: Build in CI, Publish to GitHub Packages, Deploy the Artifact
+
+Give `package.json` a scoped name and `"publishConfig": { "registry": "https://npm.pkg.github.com" }`:
+
+```json
+{
+	"name": "@my-org/my-app",
+	"version": "1.2.3",
+	"publishConfig": { "registry": "https://npm.pkg.github.com" },
+	"files": ["config.yaml", "schema.graphql", "dist/"]
+}
 ```
 
-**Deploy a specific GitHub repository by tag:**
+The deploy installs the version the tag names, and `npm publish` publishes the version in `package.json`, so they must agree: `npm version 1.2.3` sets one and creates the other as `v1.2.3`.
+
+```yaml
+# .github/workflows/deploy.yml
+name: Build, publish, and deploy to Harper
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://npm.pkg.github.com
+          scope: '@my-org'
+      - run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - run: npm run build
+      - run: npm test
+      - name: Publish to GitHub Packages
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  deploy:
+    needs: publish
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      id-token: write
+    env:
+      HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install --global harper@^5.3
+      - name: Deploy the published version
+        run: |
+          harper deploy project=my-app package="@my-org/my-app@${GITHUB_REF_NAME#v}" \
+            credentials='[{"registry":"https://npm.pkg.github.com","scope":"@my-org","secret":"deploy.my-app.npm.pkg.github.com"}]' \
+            restart=rolling json=true > deploy.json
+      - name: Wait for every node to take the release
+        run: |
+          JOB_ID=$(jq -r '.restartJobId // empty' deploy.json)
+          [ -n "$JOB_ID" ] || { echo "The rolling deploy returned no restartJobId"; exit 1; }
+          LAST="could not be read"
+          for attempt in $(seq 60); do
+            sleep 10
+            harper get_job id="$JOB_ID" json=true > job.json || continue
+            case $(jq -r '.[0].status // "MISSING"' job.json) in
+              COMPLETE) exit 0 ;;
+              ERROR) jq -r '.[0].message' job.json; exit 1 ;;
+              MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
+              *) LAST="was still running" ;;
+            esac
+          done
+          echo "After 60 polls, job $JOB_ID $LAST"
+          exit 1
+```
+
+Two jobs keep the identity token isolated: `publish` installs, builds, tests and publishes with `contents: read` and `packages: write` only — it cannot request an identity token. `deploy` runs once `publish` finishes (`needs: publish`), holds `environment: production` and `id-token: write`, and installs only the Harper CLI before deploying.
+
+Credential roles:
+
+- **Publishing** and installing private `@my-org` dependencies use the workflow's ephemeral `GITHUB_TOKEN` (`packages: write` includes read). Both happen entirely inside `publish`.
+- **Installing on Harper nodes** uses the durable `read:packages` token stored as `deploy.my-app.npm.pkg.github.com` — because installs can happen long after this workflow ends.
+
+For `my-app`, the credential names are `deploy.my-app.git.github.com` for the repository and `deploy.my-app.npm.pkg.github.com` for GitHub Packages. Store a durable credential once from your machine:
 
 ```bash
-harper deploy \
-  project=my-app \
-  package="HarperFast/application-template#semver:v1.0.0" \
-  target=https://my-cluster.harperdbcloud.com \
-  restart=true \
-  replicated=true
+harper deploy setup=true provider=github project=my-app
+# or for GitHub Packages:
+harper deploy setup=true provider=npm project=my-app registry=https://npm.pkg.github.com scope=@my-org
 ```
 
-**Deploy by reference from a private repository after provisioning credentials:**
+For a private repository, use a GitHub fine-grained personal access token with **Contents: read-only** scoped to the application repository. For GitHub Packages, use a token with the `read:packages` scope. Do not use the workflow's ephemeral `GITHUB_TOKEN` for the durable credential — it expires when the job ends.
+
+##### Check the Deployment Record
 
 ```bash
-# Provision once (requires super_user)
-harper deploy setup=true
+harper get_deployment deployment_id="$(jq -r .deployment_id deploy.json)" json=true
+```
 
-# Deploy by reference with credential
-harper deploy by_ref=true credential=true restart=true replicated=true
+Only the node you called writes that record, so with `restart=rolling` on v5.4.0 and later it can report `success` before the job has visited the other nodes, and keeps reporting it if one of them rejects the release. Wait on the job, not the record, to confirm all nodes took the release. `list_deployments` gives the history of what was deployed and when.
+
+##### List and Inspect Trust Policies
+
+```bash
+harper list_oidc_trust
 ```
 
-**Roll back to a previous deployment:**
+Returns `{ "policies": [ ... ] }`. Each entry includes `id`, `issuer`, `audience`, `claims`, `user`, `enabled`, and optionally `invalid_reason`. Check `invalid_reason` first when diagnosing a rejected exchange — it is set when the policy is malformed or its user was deleted or deactivated.
+
+##### Drop a Trust Policy
 
 ```bash
-harper deploy project=my-app deployment_id=<id> restart=true
+harper drop_oidc_trust id=github-actions-<project>
 ```
 
 #### Notes
 
-- The cluster's Application URL is found on the **Config → Overview** page.
-- `harper deploy setup=true` requires **super_user** — run it with an administrative credential, not the CI identity it provisions for.
-- Secrets are stored scoped to the component, never in the global `processEnv` tier. The `enc:v1:` envelope is the only form of the token that ever leaves your machine or travels over the operations API.
-- For SSH-based private repos, use the `add_ssh_key` operation to register keys before deploying.
-- A `ref` pointing to `refs/tags` is resolved to a full commit SHA before the deploy is sent. Tags that move mid-deploy could otherwise leave cluster nodes running different code.
-- 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 a built payload instead.
+- `HARPER_CLI_REFRESH_TOKEN` and any other stored credential outrank the OIDC exchange. Remove them from the workflow if switching to OIDC.
+- **Go back to a previous release** by activating its `deployment_id`, with no rebuild or reinstall: `harper deploy project=my-app deployment_id=<id> restart=rolling`. To deploy a release that is no longer kept, re-run the deploy with its tag or version.
+- **Rotating the deploy credential**: run `harper deploy setup=true` again with the same name and a new value. The pipeline doesn't change.
+- **Revoking the pipeline's access**: `harper drop_oidc_trust` stops new runs; `harper alter_user` also stops a token already issued (valid up to one hour).
+- The `<project>-ci-deploy` user created by setup can deploy any component on the cluster, not only the named project. Access control comes down to who can merge to the branch.
+- The `audience` in `add_oidc_trust` must be the exact target URL with its port and a trailing slash.
+- For tag-triggered workflows, `provider=github-actions` setup is not sufficient — it pins a branch. Write the policy manually using `add_oidc_trust` with `workflow_path` and `environment` claims.
+- `token.actions.githubusercontent.com` is the required `issuer` value for GitHub Actions OIDC policies.
+- Git-host credentials require git ≥ 2.31 on the Harper nodes and are not supported on Windows nodes. Registry credentials have no such constraints.
+- See [deploying-to-harper-fabric.md](deploying-to-harper-fabric.md) for cluster-level deployment context.
 
-### 4.2 Creating a Harper Fabric Account and Cluster
+### 4.3 Creating a Harper Fabric Account and Cluster
 
 Follow these steps to set up your Harper Fabric environment for deployment.
 
@@ -2493,7 +2847,7 @@ Follow these steps to set up your Harper Fabric environment for deployment.
 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.
+6. **Connect the CLI**: Run `harper login` with the Application URL to store a token for the cluster, and set the URL as `HARPER_CLI_TARGET` in your `.env` file. Prefer this to putting the cluster username and password in `.env`, and don't store them in GitHub Actions secrets: to deploy from GitHub Actions, set up OIDC trusted publishing instead (see [deploying-from-ci](deploying-from-ci.md)).
 7. **Next Steps**: See the [deploying-to-harper-fabric](deploying-to-harper-fabric.md) rule for detailed instructions on deploying your application successfully.
 
 #### Examples
@@ -2501,12 +2855,15 @@ Follow these steps to set up your Harper Fabric environment for deployment.
 ##### Environment Configuration
 
 ```bash
-CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'
-CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'
-CLI_TARGET='YOUR_CLUSTER_URL'
+harper login YOUR_CLUSTER_URL
+```
+
+```bash
+# .env
+HARPER_CLI_TARGET='YOUR_CLUSTER_URL'
 ```
 
-### 4.3 Creating Harper Applications
+### 4.4 Creating Harper Applications
 
 The fastest way to start a new Harper project is using the `create-harper` CLI tool. This command
 initializes a project with a standard folder structure, essential configuration files, and basic
@@ -2549,12 +2906,79 @@ npm create harper@latest my-app --template default
 
 #### Next Steps
 
-1. **Configure Environment**: Set up your `.env` file with local or cloud credentials.
-2. **Define Schema**: Modify `schema.graphql` to fit your application's data model.
-3. **Start Development**: Run `npm run dev` to start the local Harper instance.
-4. **Deploy**: Use `npm run deploy` to push your application to Harper Fabric.
+1. **Define Schema**: Modify `schema.graphql` to fit your application's data model.
+2. **Start Development**: Run `npm run dev` to start the local Harper instance.
+3. **Connect the CLI to your cluster**: Create a cluster (see
+   [creating-a-fabric-account-and-cluster](creating-a-fabric-account-and-cluster.md)), run `harper login` with its
+   Application URL as a super user, and set that URL as `HARPER_CLI_TARGET` in the project's `.env` file. Don't put a
+   cluster username or password in `.env` or in GitHub secrets.
+4. **Deploy**: See [Deploying](#deploying).
+
+#### Deploying
+
+Every template except the legacy `early-hints` example ships a GitHub Actions workflow,
+`.github/workflows/deploy.yaml`. It tests every pull request and deploys to the cluster when a change merges to `main`.
+The deploy job holds no Harper credential: its `harper` commands authenticate with GitHub's OIDC identity token under a
+trust policy on the cluster. The Next.js templates' workflow also runs `next build` before it uploads.
+
+1. **Set up CI deploys once**: Push the project to a GitHub repository, then run `npm run deploy:setup-ci` from the
+   project, logged in to the cluster as a super user. It runs `harper deploy setup=true provider=github-actions` for the
+   project, which creates a deploy-only role and user and a trust policy matched to the workflow, and sets the
+   repository's `HARPER_CLI_TARGET` variable when the `gh` CLI is signed in (otherwise it prints the command to run).
+   Running it again changes nothing. See [deploying-from-ci](deploying-from-ci.md) for what it checks and how to
+   customize it.
+
+   The command needs the Harper 5.4.0 CLI or later (`harper version`); an earlier CLI can't run it. Without 5.4.0, set
+   up the same role, user, policy and variable by hand, as a super user. The policy must match the scaffolded workflow:
+   its `deploy.yaml` file on `main`, in the `production` environment. The `audience` is the cluster URL with its port
+   and a trailing slash, and `HARPER_CLI_TARGET` must be that same string:
+
+   ```bash
+   gh api repos/<owner>/<repo> --jq .id   # the repository_id
+   harper add_role role=<name>-ci-deploy permission='{"operations":["deploy_component","get_job","registration_info"]}'
+   harper add_user username=<name>-ci-deploy role=<name>-ci-deploy active=true password="$(openssl rand -base64 32)"
+   harper add_oidc_trust \
+     id=github-actions-<name> \
+     issuer=https://token.actions.githubusercontent.com \
+     audience=https://my-cluster.example.com:9925/ \
+     user=<name>-ci-deploy \
+     claims='{"repository_id":"<id>","workflow_ref":"<owner>/<repo>/.github/workflows/deploy.yaml@refs/heads/main","environment":"production"}'
+   gh variable set HARPER_CLI_TARGET --repo <owner>/<repo> --body https://my-cluster.example.com:9925/
+   ```
+
+   If you restrict the `production` environment's deployment branches, allow `main`.
+
+2. **Deploy by merging to `main`**, or by running the workflow from the **Actions** tab. The workflow deploys with
+   `restart=rolling` and waits for every node to take the release. The run's summary names the `deployment_id` and its
+   `certification`.
+3. **Deploy by hand with `npm run deploy`**: It runs `harper deploy project=<name> restart=rolling` from your machine, as
+   the user you logged in with.
+4. **Go back to an earlier release** by activating its `deployment_id`, with nothing reinstalled:
+
+   ```bash
+   harper list_deployments project=<name>
+   harper deploy project=<name> deployment_id=<id> restart=rolling
+   ```
+
+   See [deploying-to-harper-fabric](deploying-to-harper-fabric.md).
+
+Use your package manager's equivalent of `npm run` (`pnpm run`, `bun run`, `yarn`) if the project uses another one.
+
+Projects created before create-harper 1.13.0 deploy on version tags with a `HARPER_CLI_REFRESH_TOKEN` secret, and
+don't have `deploy:setup-ci`. To move one over:
+
+1. Scaffold a new project with the same name and template, and copy its `.github/workflows/deploy.yaml` over the old
+   workflow.
+2. Set up the cluster for it, with the `project=` value that workflow passes to `harper deploy` as `<name>`: with the
+   5.4.0 CLI, `harper deploy setup=true provider=github-actions project=<name>`; with an earlier one, by hand as in
+   step 1.
+3. Push the new workflow to `main`.
+4. Once the workflow's run on `main` has succeeded, wait step included, delete the `HARPER_CLI_REFRESH_TOKEN` secret.
+   Deleting it doesn't revoke the token, which stays valid until it expires. To cut it off now, mint a new one for that
+   user with `harper login --for-ci`, which invalidates the old one, or deactivate the user with `alter_user` if
+   nothing else uses it.
 
-### 4.4 Serving Web Content
+### 4.5 Serving Web Content
 
 Instructions for the agent to follow when serving web content from Harper.
 
@@ -2661,7 +3085,7 @@ Because `@harperfast/vite` builds on the node and `static` serves the output, de
 
 On deploy the plugin runs `vite build` at startup (and rebuilds when `files` change) while `static` serves the result. If you prefer to build in CI, commit the build output, point `static` at it, and omit `files` so the plugin stays idle while `static` serves the prebuilt assets. Either way, `npm create harper@latest` scaffolds a working setup for you.
 
-### 4.5 Harper Logging
+### 4.6 Harper Logging
 
 Instructions for the agent to follow when implementing logging in Harper applications, including direct logger usage, tagged loggers, and console capture behavior.
 
@@ -2817,61 +3241,31 @@ Tagged entries appear in `hdb.log` with the tag in the header:
 - When logging to standard streams, run Harper in the foreground (`harper`, not `harper start`).
 - `TaggedLogger` is bound to the configured log level at creation time — always use `?.` on its methods.
 
-### 4.6 Load Environment Variables with loadEnv
+### 4.7 Load Environment Variables with loadEnv
 
 Instructions for the agent to follow when loading environment variables from `.env` files into a Harper application using the `loadEnv` plugin.
 
 #### When to Use
 
-Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use `loadEnv` any time you need to load one or more `.env` files at application startup.
+Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use this whenever a `.env` file must be loaded at application startup.
 
 #### How It Works
 
-1. **Declare `loadEnv` in `config.yaml`**: Add `loadEnv` as the first entry in `config.yaml`. It is built into Harper and requires no installation.
-
-   ```yaml
-   loadEnv:
-     files: '.env'
-   ```
-
-2. **Place `loadEnv` first**: Harper is a single-process application. List `loadEnv` before all other components so that environment variables are available on `process.env` before dependent components start.
+1. **Declare `loadEnv` first in `config.yaml`**: Place `loadEnv` before all other components so environment variables are available when dependent components start.
 
    ```yaml
    # config.yaml — loadEnv must come first
    loadEnv:
      files: '.env'
-
-   rest: true
-
-   myApp:
-     files: './src/*.js'
-   ```
-
-3. **Access loaded values in component code**: After `loadEnv` runs, all loaded values are available on `process.env` and shared across all components.
-
-4. **Control override behavior**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to make loaded values win instead.
-
-   ```yaml
-   loadEnv:
-     files: '.env'
-     override: true
    ```
 
-5. **Load multiple files**: Pass an array of paths or a glob pattern to `files`. Files are loaded in the order specified.
+2. **Set the `files` option**: Provide one or more paths or glob patterns pointing to the env file(s) to load. This option is required.
 
-   ```yaml
-   loadEnv:
-     files:
-       - '.env'
-       - '.env.local'
-   ```
+3. **Access variables in component code**: After loading, all values from the specified files are available on `process.env` and shared across all components in the single Harper process.
 
-   or with a glob:
+4. **Control override behavior with `override`**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to reverse this — loaded values will overwrite variables already present in the shell or container environment.
 
-   ```yaml
-   loadEnv:
-     files: 'env-vars/*'
-   ```
+5. **Load multiple files when needed**: Specify a list or a glob pattern under `files`. Files are loaded in the order specified.
 
 ##### Configuration Options
 
@@ -2882,10 +3276,17 @@ Apply this rule when a Harper application needs to supply secrets, API endpoints
 
 #### Examples
 
-**Single file, default behavior:**
+**Basic usage — load a single `.env` file:**
 
 ```yaml
-# config.yaml
+loadEnv:
+  files: '.env'
+```
+
+**Full `config.yaml` with `loadEnv` declared first:**
+
+```yaml
+# config.yaml — loadEnv must come first
 loadEnv:
   files: '.env'
 
@@ -2895,29 +3296,40 @@ myApp:
   files: './src/*.js'
 ```
 
-**Multiple files with override:**
+**Override existing environment variables:**
+
+```yaml
+loadEnv:
+  files: '.env'
+  override: true
+```
+
+**Load multiple files as a list:**
 
 ```yaml
-# config.yaml
 loadEnv:
   files:
     - '.env'
     - '.env.local'
-  override: true
+```
 
-rest: true
+**Load multiple files using a glob pattern:**
 
-myApp:
-  files: './src/*.js'
+```yaml
+loadEnv:
+  files: 'env-vars/*'
 ```
 
 #### Notes
 
-- `loadEnv` loads values into `process.env` for **application** code only — it does not configure Harper itself.
-- Harper's own instance-wide configuration is composed at startup **before** any component's `loadEnv` runs. Variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored. Set Harper configuration directly in the configuration file or export variables in the real process/container environment before Harper starts.
-- For production credentials, prefer the encrypted secrets store over a committed `.env` file. Secrets are also delivered to components via `process.env`.
+- `loadEnv` is built into Harper — it does not need to be installed, only declared in `config.yaml`.
+- Variables are loaded onto `process.env` and shared across all components. Declare `loadEnv` before any component that depends on those variables.
+- `loadEnv` supplies **application** environment variables only. It does **not** configure Harper itself. Harper's own configuration is composed at startup before any `loadEnv` runs, so variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored.
+- To change Harper's own configuration, use the configuration file directly or export variables in the real process/container environment before Harper starts.
+- For production credentials, prefer the encrypted secrets store over a committed `.env` file. Secrets are delivered to components via `process.env` and never appear in operation logs or replication payloads.
+- Individual `.env` values can also be stored encrypted so plaintext never reaches the API, logs, or replication payload.
 
-### 4.7 v5 Upgrade: Breaking Changes and Migration Guide
+### 4.8 v5 Upgrade: Breaking Changes and Migration Guide
 
 Instructions for the agent to follow when migrating a Harper application to v5, covering all breaking changes and required code updates.
 
@@ -3089,7 +3501,7 @@ record = { ...record, property: 'changed' };
 - Automatic context tracking simplifies code but requires explicit `commit()` or new `transaction()` calls when you need to observe data written within the same transaction.
 - Use `getContext` from `'harper'` rather than passing context manually through every call — this is the recommended pattern in v5.
 
-### 4.8 Delegating to the Built-in Agent
+### 4.9 Delegating to the Built-in Agent
 
 Harper 5.2+ ships with a **built-in agent** that runs _inside_ the server, on the main thread
 adjacent to the operations API. Because it runs in-process, it can do things a remote client