@harperfast/template-vue-ts-studio 1.12.12 → 1.13.1

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

@@ -1605,7 +1605,7 @@ Instructions for the agent to follow when defining custom REST endpoints with Ja
 
 #### When to Use
 
-Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or registering routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed resource or when a specific URL shape is required.
+Apply this rule when you need to create custom HTTP endpoints, wrap external APIs, or register routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when you need fine-grained control over URL shape and path parameters.
 
 #### How It Works
 
@@ -1615,7 +1615,13 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    import { tables, Resource } from 'harper';
    ```
 
-2. **Define a class that `extends Resource`**: Implement HTTP methods as `static` methods. Each method receives a `target` object.
+   CommonJS alternative:
+
+   ```javascript
+   const { tables, Resource } = require('harper');
+   ```
+
+2. **Define a class that `extends Resource`**: Use `export class` so Harper exposes it as an endpoint. Implement HTTP methods as `static` methods on the class.
 
    ```javascript
    export class CustomEndpoint extends Resource {
@@ -1627,7 +1633,7 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-3. **Use `async` static methods to call external services**: Return or forward the response directly.
+3. **Use `static` async methods to call external services**: Each HTTP verb maps to a `static` method of the same lowercase name.
 
    ```javascript
    export class MyExternalData extends Resource {
@@ -1645,24 +1651,20 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    }
    ```
 
-4. **Export the class to expose it as an endpoint**: The export form controls the resulting URL. Choose the form that matches the URL shape you need.
+4. **Control the URL by choosing the export form**: The shape of the export determines the resulting URL path.
 
    | Export form                                 | URL             | Notes                                                           |
    | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
-   | `export class Foo extends Resource {}`      | `/Foo/`         | Class name becomes the path segment. Case-sensitive.            |
+   | `export class Foo extends Resource {}`      | `/Foo/`         | Class name becomes the path segment; case-sensitive.            |
    | `export const Bar = { Foo };`               | `/Bar/Foo/`     | Nest under an object to add a path prefix.                      |
    | `export const bar = { 'foo-baz': Foo };`    | `/bar/foo-baz/` | Use object keys for lowercase, hyphens, or non-identifier URLs. |
    | `export { Foo as '/widget/:id' }`           | `/widget/:id`   | Rename the export to set the path directly.                     |
    | `static path = '/widget/:id'` (class field) | `/widget/:id`   | Declare path on the class; overrides the export name.           |
-   | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration for dynamic paths.                    |
+   | `server.resources.set('my-path', Foo);`     | `/my-path/`     | Programmatic registration; useful when the path is dynamic.     |
 
-5. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the resource class.
-
-   ```javascript
-   server.resources.set('my-path', Foo);
-   ```
+   URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
 
-6. **Declare dynamic path segments with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
+5. **Declare dynamic path segments with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
 
    ```javascript
    export class Widget extends Resource {
@@ -1672,13 +1674,36 @@ Apply this rule when creating custom HTTP endpoints, wrapping external APIs, or
    		return { id: target.id, action: target.action };
    	}
    }
+
+   export class Files extends Resource {
+   	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
+   	static path = '/files/*rest';
+   	static get(target) {
+   		return { path: target.rest };
+   	}
+   }
    ```
 
-7. **Resolve path precedence correctly**: Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats a `:param`, which beats a `*` wildcard, compared left to right.
+   - A leading `/` in `static path` makes the path root-relative (top-level), independent of the file's location.
+   - A leading `./` or bare name resolves relative to the component directory.
+   - A bare `*` (no name) binds under `target.wildcard`. A wildcard must be the final segment.
+   - `static path` takes precedence over the export name.
+   - Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats `:param`, which beats `*`, compared left to right.
+
+6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the resource class.
+
+   ```javascript
+   server.resources.set('my-path', Foo);
+   ```
+
+7. **Optionally use a resource as a cache source for a local table**: Call `sourcedFrom` on the target table.
+   ```javascript
+   tables.MyCache.sourcedFrom(MyExternalData);
+   ```
 
 #### Examples
 
-**Wrapping an external API and using it as a cache source:**
+**Custom endpoint with external API wrapping:**
 
 ```javascript
 import { tables, Resource } from 'harper';
@@ -1701,9 +1726,19 @@ export class MyExternalData extends Resource {
 tables.MyCache.sourcedFrom(MyExternalData);
 ```
 
-**Catch-all wildcard path:**
+**Path parameters with `static path`:**
 
 ```javascript
+import { Resource } from 'harper';
+
+export class Widget extends Resource {
+	// GET /widget/10/action/jump  ->  target.id === '10', target.action === 'jump'
+	static path = '/widget/:id/action/:action';
+	static get(target) {
+		return { id: target.id, action: target.action };
+	}
+}
+
 export class Files extends Resource {
 	// GET /files/a/b/c.txt  ->  target.rest === 'a/b/c.txt'
 	static path = '/files/*rest';
@@ -1713,27 +1748,26 @@ export class Files extends Resource {
 }
 ```
 
-**Root-relative fixed route:**
+**Programmatic registration:**
 
 ```javascript
-export class AcmeChallenge extends Resource {
-	static path = '/.well-known/acme-challenge/:token';
+import { Resource } from 'harper';
+
+export class Foo extends Resource {
 	static get(target) {
-		return { token: target.token };
+		return { ok: true };
 	}
 }
+
+server.resources.set('my-path', Foo);
 ```
 
 #### Notes
 
-- URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
-- A leading `/` in `static path` makes the path root-relative (top-level), independent of the file's location.
-- A leading `./` or a bare name in `static path` resolves relative to the component directory.
-- A bare `*` (no name) binds under `target.wildcard`. A wildcard must be the final segment of the path.
-- `static path` takes precedence over the export name when both are present.
-- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as URI templates.
-- When a resource `extends` an existing table, avoid conflicting exports between the schema and the JavaScript implementation.
-- Link the `harper` package in your component directory to ensure correct typings: `npm link harper`. All installed components have `harper` automatically linked.
+- Avoid conflicting exports between the schema and the JavaScript implementation when a resource `extends` an existing table.
+- Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
+- When bundling for SSR with a tool like Vite, keep `harper` external so it resolves to the runtime: `ssr: { external: ['harper'] }`.
+- For components in their own directory, run `npm link harper` to ensure typings match the running installation.
 
 ### 3.2 Extending Tables
 
@@ -1833,25 +1867,31 @@ export class MyTable extends tables.MyTable {
 
 ### 3.3 Programmatic Table Requests
 
-Instructions for the agent to interact with Harper tables programmatically using the `tables` object, the Query API, and transactions.
+Instructions for the agent to follow when interacting with Harper tables programmatically using the `tables` object.
 
 #### When to Use
 
-Apply this rule when writing server-side Harper component code that reads from or writes to tables directly — for example, in HTTP handlers, background jobs, timers, or SSR render functions. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, `limit`, or `offset`, or when you need explicit transaction control via `transaction()`.
+Apply this rule when writing server-side Harper component code that reads from or writes to tables using the programmatic API — for example, in HTTP handlers, background jobs, timers, or SSR entry points. Use it whenever you need to construct queries with `conditions`, `sort`, `select`, pagination, or transactions outside of the REST layer.
 
 #### How It Works
 
-1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a named property of `tables`. Each property is the table class implementing the Resource API.
+1. **Import `tables` (and other APIs) from `harper`**: Access every table defined in `schema.graphql` as a property of `tables`. Each property is the table class implementing the Resource API.
 
    ```javascript
    import { tables, transaction } from 'harper';
    const { Product } = tables;
-   // equivalent to: databases.data.Product
+   // same as: databases.data.Product
+   ```
+
+   For components in their own directory, run:
+
+   ```bash
+   npm link harper
    ```
 
-   For standalone components, run `npm link harper` so imports resolve to the live runtime.
+   All installed components have `harper` automatically linked.
 
-2. **Define your schema with `@table`**: Tables must be declared in `schema.graphql`. Mark attributes you intend to sort or filter on with `@indexed`.
+2. **Define your schema with `@table`**: Every type you want to access via `tables` must carry the `@table` directive. Mark queryable fields with `@indexed`.
 
    ```graphql
    type Product @table {
@@ -1861,7 +1901,7 @@ Apply this rule when writing server-side Harper component code that reads from o
    }
    ```
 
-3. **Query records with `search(`**: Pass a Query object to `search(`. Iterate results with `for await`.
+3. **Query records using `search(`**: Pass a Query object to `search()`. The query is an async iterable.
 
    ```javascript
    const query = {
@@ -1872,7 +1912,7 @@ Apply this rule when writing server-side Harper component code that reads from o
    }
    ```
 
-4. **Build `conditions`**: Each condition object supports these properties:
+4. **Build `conditions`**: Each condition object supports the following properties:
 
    | Property     | Description                                                                                                                                              |
    | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1882,53 +1922,60 @@ Apply this rule when writing server-side Harper component code that reads from o
    | `conditions` | Nested conditions array                                                                                                                                  |
    | `operator`   | `and` (default) or `or` for the nested `conditions`                                                                                                      |
 
-5. **Control result shape with `select`**: Pass an array of property names, a single string, or nested objects for relationships.
+5. **Apply `select` to shape results**: Pass an array of property names, a string for a single property, or nested objects for relationships.
 
    ```javascript
-   // Scalar fields only
+   // Flat select
    Product.search({ select: ['name', 'price'] });
 
-   // Partial related record
+   // Nested relationship select
    Book.get({ id: 42, select: ['id', 'title', { name: 'author', select: ['name'] }] });
    ```
 
    Special `select` values: `$id`, `$updatedtime`, `$distance`.
 
-6. **Paginate with `limit` and `offset`**:
-
-   ```javascript
-   Product.search({ conditions: [...], limit: 20, offset: 40 });
-   ```
+6. **Apply `sort`**: Harper uses an index to provide sort order.
 
-7. **Sort with `sort`**: The `sort` object accepts `attribute`, `descending` (default `false`), and `next` for tie-breaking. Harper uses an index for sort order — the sort `attribute` must be `@indexed`, **or** at least one entry in `conditions` must be present.
+   | Property     | Description                                                |
+   | ------------ | ---------------------------------------------------------- |
+   | `attribute`  | Property name (or array for chained relationship property) |
+   | `descending` | Sort descending if `true` (default: `false`)               |
+   | `next`       | Secondary sort to resolve ties (same structure)            |
+   - If the sort `attribute` is `@indexed`, no condition is required.
+   - If the sort `attribute` is not indexed, at least one entry in `conditions` (on **any** attribute) is required.
+   - Sorting by a non-indexed attribute with zero conditions raises:
+     > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+   - The bare `@primaryKey` is treated as not indexed for sort purposes. To iterate in primary-key order, add an open-ended condition:
 
-   Sorting by a non-indexed attribute with zero conditions raises:
+     ```javascript
+     Product.search({
+     	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
+     	sort: { attribute: 'id' },
+     });
+     ```
 
-   > `HdbError: <attribute> is not indexed and not combined with any other conditions`
+   - Pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
 
-   Note: `@primaryKey` alone is treated as not indexed for sort purposes. To scan the whole table in primary-key order, add an open-ended condition:
+7. **Paginate with `limit` and `offset`**:
 
    ```javascript
-   Product.search({
-   	conditions: [{ attribute: 'id', comparator: 'greater_than', value: '' }],
-   	sort: { attribute: 'id' },
-   });
+   Product.search({ conditions: [...], limit: 20, offset: 40 });
    ```
 
-   Alternatively, pass `allowFullScan: true` to permit an unconditional ordered scan, or omit `sort` entirely to iterate without an index requirement.
-
-8. **Debug query planning with `explain` and `enforceExecutionOrder`**:
+8. **Debug with `explain` and `enforceExecutionOrder`**:
    - `explain: true` — returns conditions reordered as Harper will execute them.
-   - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling automatic re-ordering.
+   - `enforceExecutionOrder: true` — forces conditions to execute in the order supplied, disabling Harper's automatic re-ordering.
 
-9. **Use `addTo` for concurrent-safe numeric updates**: `addTo` uses CRDT incrementation, safe across threads and nodes.
+9. **Use `addTo` for concurrent-safe increments**: `addTo(property, value)` uses CRDT incrementation, safe across threads and nodes.
 
    ```javascript
-   const record = await Product.update(32);
-   record.addTo('quantity', -1);
+   static async post(target, data) {
+     const record = await this.update(target.id);
+     record.addTo('quantity', -1);
+   }
    ```
 
-10. **Wrap background work in `transaction()`**: HTTP handlers get a transaction automatically. Use `transaction()` explicitly for timers, background jobs, or any code outside a request context. Always `await` the call and `catch` errors.
+10. **Wrap background work in `transaction()`**: Harper auto-starts transactions for HTTP handlers. Use `transaction()` explicitly for timers, background jobs, or any code outside a natural transaction context.
 
     ```javascript
     await transaction(async (txn) => {
@@ -1940,18 +1987,18 @@ Apply this rule when writing server-side Harper component code that reads from o
 
     The `txn` object exposes:
 
-    | Member                | Description                                            |
-    | --------------------- | ------------------------------------------------------ |
-    | `commit()`            | Commits the current transaction                        |
-    | `abort()`             | Aborts and resets the transaction                      |
-    | `resetReadSnapshot()` | Resets the read snapshot to the latest committed state |
-    | `timestamp`           | Timestamp associated with the current transaction      |
+    | Member                | Type            | Description                                            |
+    | --------------------- | --------------- | ------------------------------------------------------ |
+    | `commit()`            | `() => Promise` | Commits the current transaction                        |
+    | `abort()`             | `() => void`    | Aborts the transaction and resets it                   |
+    | `resetReadSnapshot()` | `() => void`    | Resets the read snapshot to the latest committed state |
+    | `timestamp`           | `number`        | Timestamp associated with the current transaction      |
 
-    **Atomicity**: all tables in the same database share one transactional context — writes across multiple tables commit atomically. Tables in different databases each get their own transaction with no cross-database atomicity guarantee.
+    On normal callback completion the transaction commits automatically. If the callback throws, the transaction is aborted.
 
-    If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — safe to call defensively.
+11. **Understand atomicity**: Transactions span a single database. All tables within the same database share one transactional context — reads return a consistent snapshot and writes across multiple tables commit atomically. Cross-database operations get separate transactions with no cross-database atomicity guarantee.
 
-11. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
+12. **Keep `harper` external when bundling for SSR**: In `vite.config`, mark `harper` as external so it resolves to the runtime rather than being bundled.
 
     ```javascript
     // vite.config
@@ -1962,7 +2009,7 @@ Apply this rule when writing server-side Harper component code that reads from o
 
 #### Examples
 
-##### Full CRUD sequence
+**Full CRUD flow:**
 
 ```javascript
 import { tables } from 'harper';
@@ -1974,19 +2021,18 @@ const created = await Product.create({ name: 'Shirt', price: 9.5 });
 // Patch
 await Product.patch(created.id, { price: Math.round(created.price * 0.8 * 100) / 100 });
 
-// Retrieve by primary key
+// Get by primary key
 const record = await Product.get(created.id);
 
-// Query with conditions
-const query = {
+// Search with conditions
+for await (const record of Product.search({
 	conditions: [{ attribute: 'price', comparator: 'less_than', value: 8.0 }],
-};
-for await (const record of Product.search(query)) {
+})) {
 	// process record
 }
 ```
 
-##### Nested conditions with `or`
+**Nested conditions with `or`:**
 
 ```javascript
 Product.search({
@@ -2003,13 +2049,13 @@ Product.search({
 });
 ```
 
-##### Chained attribute reference (join/relationship)
+**Chained attribute reference (join):**
 
 ```javascript
 Product.search({ conditions: [{ attribute: ['brand', 'name'], value: 'Harper' }] });
 ```
 
-##### Background job with `transaction()`
+**Background job with `transaction()`:**
 
 ```javascript
 import { isMainThread } from 'node:worker_threads';
@@ -2037,7 +2083,7 @@ if (isMainThread) {
 }
 ```
 
-##### SSR render with `tables`
+**SSR with Harper data:**
 
 ```typescript
 import { tables } from 'harper';
@@ -2050,10 +2096,12 @@ export async function render(url: string): Promise<string> {
 
 #### Notes
 
-- `tables` and `databases` do **not** automatically apply role permissions — calls run in a trusted server-side context. Apply your own authorization controls before exposing results.
-- Destructive operations (`update`, `patch`, `delete`) act on live data and are not easily reversible. Scope them with specific `conditions` and validate the affected set before writing.
-- `tables` is the same live, process-wide object whether accessed as a global or via `import { tables } from 'harper'`. A record written through one component is immediately visible to every other.
-- Run `npm link harper` for components in their own directory to ensure typings match the running installation.
+- `tables` and `databases` calls run in a trusted server-side context and do **not** automatically apply the target table's role permissions.
+- Programmatic `update`, `patch`, and `delete` calls operate directly on stored data. Scope destructive operations with specific `conditions`, validate the affected set before writing, and gate them behind authorization controls.
+- If `transaction()` is called with a context that already has an active transaction, it reuses that transaction — making it safe to call defensively.
+- Always `await` the `transaction()` call and `catch` errors when outside a request context; an unawaited call means a failed write is never observed.
+- Guard against timer overlap: if a job can outlast its interval, use a `running` flag to skip a tick rather than opening two transactions over the same rows.
+- CommonJS is also supported: `const { tables, Resource } = require('harper');`
 
 ### 3.4 TypeScript Type Stripping in Harper
 
@@ -2272,22 +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 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.
+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 remote 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 and writes `HARPER_CLI_TARGET` to a local `.env`.
+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 login, run `harper deploy` without repeating credentials. Use `restart=true` and `replicated=true` for production deploys.
+   - 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 \
@@ -2298,100 +2349,123 @@ 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. Options:
+   - 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).
 
-   | 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"`           |
+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`.
 
-   When using git tags, use the `semver` directive:
+   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`:
 
-   ```
-   HarperFast/application-template#semver:v1.0.0
-   ```
+   | `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. **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.
+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 deploy by_ref=true restart=true replicated=true
+   harper list_deployments project=my-app status=success
+   harper deploy project=my-app deployment_id=<id> restart=rolling
    ```
 
-   - `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
-   harper deploy ref=v1.2.0 restart=true replicated=true
-
-   # Roll back by deploying an older commit
-   harper deploy ref=9f8c2a1 restart=true replicated=true
+   ```json
+   {
+   	"operation": "deploy_component",
+   	"project": "my-app",
+   	"deployment_id": "<id of the deployment you want back>",
+   	"restart": "rolling"
+   }
    ```
 
-   **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.
+   - `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.
 
-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.
+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:
 
-   ```bash
-   harper deploy by_ref=true credential=true restart=true replicated=true
+   ```json
+   {
+   	"operation": "deploy_component",
+   	"project": "my-app",
+   	"package": "npm:@my-org/my-app@1.2.3",
+   	"activate": false
+   }
    ```
 
-   Provision the credential once with `setup=true` before using `credential=true`.
+   ```json
+   {
+   	"deployment_id": "a3f8c2d1-...",
+   	"message": "Staged: my-app. Deploy it with deploy_component deployment_id=a3f8c2d1-..."
+   }
+   ```
 
-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.
+   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.
 
-   ```bash
-   harper deploy setup=true
-   ```
+6. **Choose a package source**: The `package` field accepts any valid npm dependency value:
 
-   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.
+   | 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"`                                            |
 
-   **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.
+   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. **Use environment variables for CI/CD**: Instead of `harper login`, export credentials as environment variables.
+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
-   export HARPER_CLI_USERNAME=<username>
-   export HARPER_CLI_PASSWORD=<password>
-   harper deploy \
-     project=<name> \
-     package=<package> \
-     target=<remote> \
-     restart=true \
-     replicated=true
+   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
    ```
 
-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.
+   - 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 \
-     project=<name> \
-     package=<package> \
-     auth_username=<username> \
-     auth_password=<password> \
-     target=<remote> \
-     restart=true \
-     replicated=true
+   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
 
-**Standard deploy after login:**
+**Deploy after logging in, and wait for a rolling restart:**
 
 ```bash
 harper login https://my-cluster.harperdbcloud.com
@@ -2399,57 +2473,370 @@ harper deploy \
   project=my-app \
   package="HarperFast/my-app" \
   target=https://my-cluster.harperdbcloud.com \
-  restart=true \
-  replicated=true
+  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
 ```
 
-**Deploy by reference with a tag:**
+**Roll back to the release a deploy replaced, node by node:**
 
 ```bash
-harper deploy ref=v1.2.0 restart=true replicated=true
+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
 ```
 
-**Deploy a private GitHub repo by reference:**
+**Stage a release now, and make it live in a maintenance window:**
 
 ```bash
-# Provision credential once (requires super_user)
+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
 
-# Deploy using stored credential
+# Every deploy
 harper deploy by_ref=true credential=true restart=true replicated=true
 ```
 
-**GitHub Actions — pull request deploy:**
+### 4.2 Deploying a Harper Application from GitHub Actions with OIDC
+
+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 login https://my-cluster.example.com:9925
+   harper deploy setup=true provider=github-actions project=my-app
+   ```
+
+   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 provider=github-actions project=my-app workflow=.github/workflows/deploy.yml
+   ```
+
+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.
+
+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:
+
+   ```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 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)"
+   ```
+
+   - `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 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"}'
+   ```
+
+   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
+   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
+
+##### Path A: Deploy a Tagged Release (`v1.2.3`) from the Repository
+
+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/"]
+}
+```
+
+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 ref=${{ github.event.pull_request.head.sha }} 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
 ```
 
-**CI/CD deploy using environment variables:**
+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
-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
+harper get_deployment deployment_id="$(jq -r .deployment_id deploy.json)" json=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
+```
+
+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 drop_oidc_trust id=github-actions-<project>
 ```
 
 #### Notes
 
-- 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.
-- 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.
+- `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.
 
@@ -2460,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
@@ -2468,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
@@ -2516,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:
 
-### 4.4 Serving Web Content
+   ```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.5 Serving Web Content
 
 Instructions for the agent to follow when serving web content from Harper.
 
@@ -2628,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.
 
@@ -2784,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.
+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.
 
-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.
+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.
 
-   ```yaml
-   loadEnv:
-     files: '.env'
-     override: true
-   ```
+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.
 
-5. **Load multiple files**: Pass an array of paths or a glob pattern to `files`. Files are loaded in the order specified.
-
-   ```yaml
-   loadEnv:
-     files:
-       - '.env'
-       - '.env.local'
-   ```
-
-   or with a glob:
-
-   ```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
 
@@ -2849,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'
 
@@ -2862,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.
 
@@ -3056,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