@homeflare/alchemy 0.11.0 → 0.12.0

package/docs/provision-baseline.md

@@ -0,0 +1,106 @@
+# Provisioning baseline — every cluster, every node
+
+Every `@homeflare/alchemy/proxmox` resource runs as a short-lived PVE token that OpenBao mints for
+a **provision user**. That user, and the access it holds, is the baseline a cluster needs before a
+stack can manage anything on it. This subpath ships it as one description with two readers:
+
+| export                      | what it is                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------- |
+| `PROVISION_PRIVILEGES`      | the provision role's privileges: 27, sorted, the exact set                                  |
+| `PROVISION_DEFAULTS`        | the generic names in the last table, each overridable                                       |
+| `provisionBaseline(names)`  | the resolved baseline both readers use; refuses names that are not PVE-shaped               |
+| `declareProvisionBaseline`  | the baseline as `Proxmox.Role`, `Proxmox.Group`, `Proxmox.User` and `Proxmox.Acl` resources |
+| `provisionBootstrap(names)` | the one-time root commands for a new cluster or node, as a `sh` script                      |
+
+## The chicken and the egg
+
+⛔ **The provision lane cannot create itself.** A plan needs a minted token, and a mint needs the
+provision user to exist, be in the mint group, and hold the role on `/`. On a new cluster none of
+that exists, so no plan can run, including the plan that would create it.
+
+So root makes it once, and the stack takes it over from there:
+
+1. **Bootstrap, as root, once per cluster.** Generate the script and run it on any one node:
+
+   ```sh
+   bun -e "import { provisionBootstrap } from '@homeflare/alchemy/proxmox';
+           process.stdout.write(provisionBootstrap())" | ssh root@node-a sh
+   ```
+
+   Read it first: it is plain text with no secret in it. It checks each object and changes only
+   what differs, naming each step (`role HfProvisioner: adding`, `user hf-read@pve: ok`). It
+   never creates a token and never sets a password.
+
+2. **Point OpenBao at the users.** The proxmox secrets engine mints for them through a
+   `Bao.ProxmoxRole` per lane (`mintUser: PROVISION_DEFAULTS.provisionUser`, and the read user).
+   The engine's own credential, a user allowed to manage tokens for members of the mint group, is
+   set up with the engine. It is not part of this baseline.
+
+3. **Declare the baseline in the stack, and adopt it once:**
+
+   ```ts
+   import * as Effect from 'effect/Effect';
+   import { declareProvisionBaseline } from '@homeflare/alchemy/proxmox';
+
+   export const access = Effect.gen(function* () {
+     return yield* declareProvisionBaseline('pve', target);
+   });
+   ```
+
+   The first deploy finds everything live with no state. Run it with `--adopt`, or pass
+   `{ adopt: true }`. Because the script made exactly what the declaration holds, the plan is a
+   clean adoption and the deploy writes nothing. From then on, a hand edit (a privilege added in
+   the UI, a user dropped from the group) shows up as a diff on the next plan.
+
+## Every cluster, every node
+
+- **A new cluster:** run the bootstrap on one node, then deploy.
+- **A node joining a cluster:** nothing to do. Users, groups, roles and ACLs live in
+  `/etc/pve/user.cfg`, which the cluster shares. Running the script there prints `ok` for every
+  step and writes nothing.
+- **A standalone node:** it is its own cluster. Bootstrap it.
+
+## Your own names
+
+Every name has a generic default, and a site passes its own to both readers:
+
+```ts
+const names = { role: 'Provisioner', mintGroup: 'mint', readUser: null };
+provisionBootstrap(names); // the script
+declareProvisionBaseline('pve', target, names); // the resources
+```
+
+- `readUser: null` gives a baseline with no read lane.
+- `readRole` must already exist (`PVEAuditor` is built in). The script stops before any write if
+  it does not.
+- A name that is not PVE-shaped, or that would need quoting in a shell, is refused by both
+  readers before either one runs.
+
+## What the baseline holds
+
+| object                           | detail                                                     |
+| -------------------------------- | ---------------------------------------------------------- |
+| role `HfProvisioner`             | exactly `PROVISION_PRIVILEGES`, nothing more, nothing less |
+| group `hf-mint`                  | the fence: OpenBao may mint only for its members           |
+| user `hf-provision@pve`          | in `hf-mint` only, enabled, no password, no expiry         |
+| user `hf-read@pve`               | the same, for the read lane                                |
+| `/`, `hf-provision@pve`, role    | `HfProvisioner`, propagated                                |
+| `/`, `hf-read@pve`, `PVEAuditor` | propagated                                                 |
+
+★ **One privilege list for every family.** It is the union of what each resource's reconcile
+needs. That includes managing this baseline itself (`Sys.Modify`, `Realm.AllocateUser`,
+`User.Modify`, `Group.Allocate`, `Permissions.Modify`), so declaring it can never narrow the lane
+out of its own repair. It does not include writes PVE keeps for `root@pam` (device passthrough,
+bind mounts). Those are refused at plan with the command to run instead.
+
+⚠️ **The role is the exact set.** Both the script and `Proxmox.Role` replace the privileges, never
+add to them. A privilege added by hand is removed on the next run or deploy. If you need more,
+declare your own role and grant.
+
+⛔ **Everything retains.** Dropping `declareProvisionBaseline` from a stack drops its state and
+leaves the role, users, group and grants in place. Deleting the provision user would revoke every
+lease at once, including the one the next plan needs.
+
+⚠️ **Adoption today.** `Proxmox.Role`, `Group`, `User` and `Acl` still read a live object with no
+state as their own (the `pveHandlers` limit in [ownership.md](./ownership.md)). The `adopt`
+option says what the stack means, so it keeps holding when those families follow the rule.

package/docs/proxmox-lxc-adopt.md

@@ -12,7 +12,7 @@ The adoption half of [proxmox-lxc.md](./proxmox-lxc.md). Two rules, both decided
    With adoption on, a declaration that differs from the live config in any key fails the plan:
 
 ```
-CT 100 on pve1: adopting it would change memory, net1. An adoption never changes a guest, so
+CT 900 on pve1: adopting it would change memory, net1. An adoption never changes a guest, so
 nothing is written. Declare what is live for these keys (the plan names keys, never values) and
 plan again; change them after the adoption, as an update.
 ```
@@ -26,7 +26,7 @@ plan again; change them after the adoption, as an update.
   ordinary `update`, and its plan warns with each key the deploy writes:
 
 ```
-Proxmox.Lxc pve1/100: live config differs from the declaration in memory -- a deploy writes these.
+Proxmox.Lxc pve1/900: live config differs from the declaration in memory -- a deploy writes these.
 ```
 
 - **The deploy asks again.** A key edited by hand between the plan and the deploy is refused at

package/docs/proxmox-lxc.md

@@ -16,7 +16,7 @@ export const guests = Effect.gen(function* () {
   const ct = yield* ProxmoxLxc('ct', {
     target,
     node: 'pve1',
-    vmid: 100,
+    vmid: 900,
     hostname: 'ct-example',
     cores: 4,
     memory: 8192,
@@ -24,8 +24,8 @@ export const guests = Effect.gen(function* () {
     onboot: 1,
     unprivileged: 1,
     features: 'nesting=1',
-    rootfs: 'local-zfs:subvol-100-disk-0,size=40G',
-    mp0: 'tank:subvol-100-disk-0,mp=/data,backup=0,size=200G',
+    rootfs: 'local-zfs:subvol-900-disk-0,size=40G',
+    mp0: 'tank:subvol-900-disk-0,mp=/data,backup=0,size=200G',
     net0: 'name=eth0,bridge=vmbr0,hwaddr=00:00:5E:00:53:01,ip=192.0.2.10/24,type=veth',
     dev0: '/dev/dri/renderD128,uid=0,gid=44,mode=0660',
   }).pipe(adopt(true));
@@ -129,7 +129,8 @@ guest that needs `/dev/net/tun` (a Mesh door) or `/dev/dri` is created in two st
 1. Declare the guest without the device, and deploy.
 2. Run the `pct set` on the node, then add `dev0` to the declaration.
 
-`nesting` on an unprivileged guest is allowed. It needs `VM.Allocate`, which `LXCProvisioner` has.
+`nesting` on an unprivileged guest is allowed. It needs `VM.Allocate`, which the
+[provisioning baseline](./provision-baseline.md)'s role has.
 
 ### Gaps
 

package/docs/proxmox.md

@@ -12,3 +12,9 @@ or creates one from a template.
   plan, named without its value ([proxmox-lxc-adopt.md](./proxmox-lxc-adopt.md)).
 - ⛔ **root@pam-only keys** (`devN`, bind mounts, features beyond `nesting`) are refused at plan,
   with the `pct set` to run instead. Guide: [proxmox-lxc.md](./proxmox-lxc.md).
+- ★ **One provisioning baseline for every cluster and node**: the privilege list, a helper that
+  declares it, and the one-time root commands that bootstrap it
+  ([provision-baseline.md](./provision-baseline.md)).
+- ★ **Measurements in the source name a reference cluster with placeholders**: `C1`, three nodes
+  `node-b`, `node-c` and `node-d` with Ceph on a Thunderbolt mesh, and documentation addresses
+  (RFC 5737). The shapes and counts are measured; the names and addresses are not the real ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/caddy/admin-guard.ts

@@ -20,7 +20,7 @@
  *     Refused unless the transport is at that default; declaring `admin <address>` is the fix.
  *   · a Host the new config does not allow: `origins` without it, or — with no `origins` — a Host
  *     outside Caddy's loopback defaults (`localhost`, `[::1]`, `127.0.0.1` at the listen port).
- *     Every later call answers 403 (admin.go allowedOrigins / checkHost; MEASURED on the mini's
+ *     Every later call answers 403 (admin.go allowedOrigins / checkHost; MEASURED on a Mac host's
  *     Caddy 2.11.4 — `host not allowed`). The transport also sends `Origin: http://<Host>`, which
  *     Caddy checks against the same list (originAllowed), so one check covers both.
  *   · `enforce_origin` over a unix socket: this transport, like Caddy's CLI (cmd/commandfuncs.go

package/src/caddy/local-admin.ts

@@ -12,7 +12,7 @@
  * ★ HOST AND ORIGIN, AS CADDY's OWN CLI SENDS THEM (cmd/commandfuncs.go AdminAPIRequest): over
  *   TCP, `Host` and `Origin: http://<host>`; over a socket, `Host: 127.0.0.1` and no Origin, because
  *   Caddy skips the Host check on unix listeners (admin.go allowedOrigins). MEASURED against the
- *   mini's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
+ *   a Mac host's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
  *   hence `hostHeader`.
  */
 import { request as httpRequest } from 'node:http';

package/src/cloudflare/client.ts

@@ -5,7 +5,7 @@
  * ⛔ THE SDK WAS ALREADY IN THE STORE AND DECLARED BY NOBODY. Measured 2026-09-15:
  *   `node_modules/.pnpm/cloudflare@4.5.0` exists as a transitive dependency of `alchemy`, and
  *   `pnpm ls cloudflare --depth 0` at the root and in every workspace package returns nothing.
- *   `house/local/scripts/vendor-sdk-ratchet.ts` row R2 says exactly that — "not declared anywhere
+ *   `<estate>/local/scripts/vendor-sdk-ratchet.ts` row R2 says exactly that — "not declared anywhere
  *   in the workspace yet … the row adds the dependency once, then converts the TS callers" — so
  *   this package is that row's first half, and the twenty ratcheted offences keep their rows.
  *

package/src/cloudflare/lock-rules.ts

@@ -1,7 +1,7 @@
 /**
  * The vocabulary of an R2 lock rule, and the comparison that decides whether to write one.
  *
- * ★ ITS OWN MODULE FOR THE REASON `house/litellm/src/equal.ts` IS ONE: the comparison is the
+ * ★ ITS OWN MODULE FOR THE REASON `<estate>/litellm/src/equal.ts` IS ONE: the comparison is the
  *   riskiest function in the provider and it deserves to be readable and testable without the
  *   lifecycle around it. An equality that returned true for everything would make every reconcile
  *   a no-op and the resource would silently never write anything — which looks exactly like a

package/src/forgejo/branch-protection-form.ts

@@ -1,7 +1,7 @@
 /**
  * Create/PATCH bodies for `Forgejo.BranchProtection` — extracted for the 250-line cap.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json` — create posts
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` — create posts
  *   `CreateBranchProtectionOption`; update sends `EditBranchProtectionOption` fields only.
  */
 import type { BranchProtectionProps } from './branch-protection.ts';

package/src/forgejo/branch-protection.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.BranchProtection` — one rule at `/repos/{owner}/{repo}/branch_protections/{name}`.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection;
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection;
  *   read/update/delete use the branch/rule name in the path segment `{name}`. Response carries
  *   `rule_name` (preferred) and deprecated `branch_name`.
  *

package/src/forgejo/client.ts

@@ -87,7 +87,7 @@ export const forgejo = <T>(
      *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`; there is no bare fetch in its
      *   Docker, Kubernetes or GitHub providers). It buys a typed error channel, interruption when
      *   a plan is cancelled, the runtime's tracing, and a client a test can replace without
-     *   monkey-patching a global. house/proxmox/src/resource.ts carries the same note.
+     *   monkey-patching a global. <estate>/proxmox/src/resource.ts carries the same note.
      */
     const client = yield* HttpClient.HttpClient;
     /**

package/src/forgejo/org-actions-secrets.ts

@@ -2,7 +2,7 @@
  * `Forgejo.OrgSecret` — org-level Actions secret metadata at `/orgs/{org}/actions/secrets/{name}`.
  *
  * ★ CHOICE: AUTHORED WITH WRITE-ONLY VALUE VIA ENV, NOT REFUSED. The OpenAPI in
- *   `house/mcp-servers/docs/api/upstream/forgejo.json` shows `Secret` returns only `name` and
+ *   `<estate>/mcp-servers/docs/api/upstream/forgejo.json` shows `Secret` returns only `name` and
  *   `created_at` — never the `data` field — so attributes stay metadata-only. Create/update is PUT
  *   with body `{ data }`, which does not fit POST/PATCH; this family uses the `upsert` seam on
  *   `ForgejoSpec` instead of hand-rolling provider handlers.

package/src/forgejo/org-label.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.OrgLabel` — one org-level issue label shared across every repository in the org.
  *
- * ★ RETIRES `house/nix/homeflare-config/hosts/macmini/forgejo/labels-reconcile.sh`, which
+ * ★ RETIRES the estate's hand-run `labels-reconcile.sh`, which
  *   converged the whole `labels.yaml` file in one shot. That script CREATED and PATCHED labels
  *   from the spec and REPORTED `EXTRA` labels present live but absent from the file — it never
  *   deleted them, because removing a label strips it from every issue that carries it.

package/src/forgejo/org-team.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.OrgTeam` — one organization team under `/orgs/{org}/teams`.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json` (Forgejo 16.x OpenAPI): create is
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` (Forgejo 16.x OpenAPI): create is
  *   `POST /orgs/{org}/teams`; read/update/delete use numeric id at `/teams/{id}` — not the name.
  *
  * ⚠️ PATCH AND DELETE USE `/teams/{id}` — same seam as org labels. `locate` lists by name;

package/src/forgejo/repo-webhook.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.RepoWebhook` — one repository webhook under `/repos/{owner}/{repo}/hooks`.
  *
- * ★ READ OFF `house/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection; read/update/delete
+ * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection; read/update/delete
  *   use numeric hook id at `/repos/{owner}/{repo}/hooks/{id}`. `locate` lists and matches on `name`.
  *
  * ⛔ NO WEBHOOK `secret` IN PROPS OR ATTRIBUTES. Optional HMAC material is env-only at write time

package/src/forgejo/repository.ts

@@ -1,7 +1,7 @@
 /**
  * `Forgejo.Repository` — an organization-owned git repository.
  *
- * ★ MEASURED 2026-09-13 against the live daemon (`GET /api/v1/repos/HomeFlare/homeflare-config`):
+ * ★ MEASURED 2026-09-13 against the live daemon (`GET /api/v1/repos/<org>/<repo>`):
  *   responses are flat JSON with `private`, `has_issues`, `default_branch`, etc. Create is
  *   `POST /orgs/{org}/repos`; read/update/delete use `/repos/{owner}/{repo}`.
  *
@@ -15,7 +15,7 @@ import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
 import { bool, text } from './values.ts';
 
 export interface RepositoryProps {
-  /** Organization login — the owner segment in `HomeFlare/homeflare-config`. */
+  /** Organization login — the owner segment in `<org>/<repo>`. */
   org: string;
   /** Repository name. Changing it is a replace, not an update. */
   name: string;

package/src/forgejo/resource.ts

@@ -28,7 +28,7 @@ import { ForgejoError, forgejo } from './client.ts';
 /**
  * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME — and it is NOT what the first draft said.
  *
- *   These resources declared `ChildProcessSpawner`, copied from house/proxmox, where it is there
+ *   These resources declared `ChildProcessSpawner`, copied from <estate>/proxmox, where it is there
  *   because a PVE credential is minted by shelling out to `bao`. Nothing in this package shells
  *   out: the token comes from `FORGEJO_TOKEN` in the environment. Declaring a service you never
  *   use is not harmless — it makes a stack provide a layer for nothing, and it hides the one
@@ -152,7 +152,7 @@ export const forgejoOperations = <Props extends object, Attributes>(
  * The five provider handlers for a spec'd Forgejo object, wired once.
  *
  * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER — same reasoning as pveHandlers in
- *   house/proxmox: wrapping `Provider.effect` here needs casts against Alchemy's `Props<R>`.
+ *   <estate>/proxmox: wrapping `Provider.effect` here needs casts against Alchemy's `Props<R>`.
  *
  * ⚠️ `list` answers empty — Forgejo index endpoints return the whole org; adoption stays explicit.
  */

package/src/forgejo/team-member.ts

@@ -3,7 +3,7 @@
  *
  * ★ WHY IT EXISTS: forgejo-provision, the service account the Forgejo engine mints as, belongs to the
  *   HomeFlare Owners team — Tim, 2026-09-14. Membership is what its tokens can reach; the role's
- *   scopes only cap it (house/openbao/src/forgejo-bootstrap.ts).
+ *   scopes only cap it (<estate>/openbao/src/forgejo-bootstrap.ts).
  *
  * ★ READ OFF THE LIVE 16.0.3 SWAGGER (127.0.0.1:3000/swagger.v1.json, 2026-09-14): GET, PUT and
  *   DELETE `/teams/{id}/members/{username}` answer 200, 204 and 204, and 404 when absent. The team

package/src/openbao/README.md

@@ -17,7 +17,7 @@ plus `FetchHttpClient.layer`.
 - ⛔ A rename or move onto a name or path that already exists fails the plan, before anything is
   written (every family but the mounts, whose moves are below). Move through a free name, in two
   deploys, or remove the target first.
-- ⛔ **Nothing is adopted without `--adopt`** (0.9.0), not even an object identical to the
+- ⛔ **Nothing is adopted without `--adopt`** (0.9.0, first published as 0.10.0), not even an object identical to the
   declaration: a live name with no state fails the plan, or the apply when a prop was an Output.
   Our own interrupted create still resumes when its row can prove it — not one killed while a
   prop was still an Output. [docs/ownership.md](../../docs/ownership.md). Change
@@ -105,10 +105,10 @@ export const machines = Effect.gen(function* () {
   });
   yield* BaoKubernetesRole('pod', {
     aliasNameSource: 'serviceaccount_name',
-    boundServiceAccountNames: ['litellm'],
+    boundServiceAccountNames: ['llm-gateway'],
     boundServiceAccountNamespaces: ['ai'],
-    name: 'ai-litellm',
-    tokenPolicies: ['ai-litellm'],
+    name: 'ai-gateway',
+    tokenPolicies: ['ai-gateway'],
   });
 });
 ```

package/src/openbao/auth-role.ts

@@ -7,7 +7,7 @@
  *
  * ★ `defaultRemovalPolicy: 'retain'` — deleting a role locks out every host that logs in with it:
  *   its secret_ids go with it (the ⚠️ on `delete` below). Opt in with
- *   `.pipe(RemovalPolicy.destroy())`; see resource.ts in house/proxmox.
+ *   `.pipe(RemovalPolicy.destroy())`; see resource.ts in <estate>/proxmox.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';

package/src/openbao/bao-http.test.ts

@@ -31,11 +31,11 @@ describe('baoRead', () => {
       () => reply,
       async (bao) => {
         const env = { BAO_ADDR: bao.address, BAO_NAMESPACE: 'homeflare', BAO_TOKEN: TOKEN };
-        const data = await run(env, baoRead('proxmox-tb4/roles/read'));
+        const data = await run(env, baoRead('proxmox-c1/roles/read'));
         assert.deepEqual(data, { mint_user: 'hf-read@pve', ttl: 3600 });
         const [seen] = bao.seen;
         assert.equal(seen?.method, 'GET');
-        assert.equal(seen?.path, '/v1/proxmox-tb4/roles/read');
+        assert.equal(seen?.path, '/v1/proxmox-c1/roles/read');
         assert.equal(seen?.headers.get('x-vault-namespace'), 'homeflare');
         assert.equal(seen?.headers.get('x-vault-token'), TOKEN);
         assert.equal(seen?.headers.get('x-vault-request'), 'true');

package/src/openbao/bao-http.ts

@@ -2,14 +2,14 @@
  * One call to OpenBao's HTTP API through Effect's `HttpClient` — the transport every Bao.* family
  * uses since it stopped shelling out to `bao`.
  *
- * ★ `HttpClient`, THE SAME PATTERN house/proxmox and house/forgejo USE AGAINST THEIR APIs, decided
+ * ★ `HttpClient`, THE SAME PATTERN <estate>/proxmox and <estate>/forgejo USE AGAINST THEIR APIs, decided
  *   2026-09-14. It buys a typed error channel, interruption when a plan is cancelled, the runtime's
  *   tracing, and a client a test can point at a fake server — and it needs no Alchemy session, so
  *   every call here works from all four operations. (`CommandExecutor.run` was tried on Bao.Policy
  *   first and blocked read/diff: Alchemy passes a session to reconcile/delete but NOT to read/diff,
  *   Provider.ts:258-289. The ChildProcessSpawner that fixed that is gone with the CLI.)
  * ⚠️ THE STACK MUST PROVIDE `FetchHttpClient.layer`. alchemy.run.ts does, the way
- *   house/proxmox/alchemy.run.ts does.
+ *   <estate>/proxmox/alchemy.run.ts does.
  */
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
@@ -34,7 +34,7 @@ export const BaoEnv = Context.Reference<BaoEnvironment>('homeflare/openbao/BaoEn
 /**
  * ⛔ AT MOST EIGHT EXCHANGES WITH OPENBAO AT ONCE — ACROSS EVERY Bao.* FAMILY, IN ONE PROCESS.
  *
- * 🔴 MEASURED 2026-09-14 10:41: A DEPLOY OF THIS STACK TOOK OPENBAO's API OFF THE MINI. Alchemy fans
+ * 🔴 MEASURED 2026-09-14 10:41: A DEPLOY OF THIS STACK TOOK OPENBAO's API OFF ITS HOST. Alchemy fans
  *   resources out with a hard-coded `concurrency: "unbounded"` (alchemy Plan.ts:476, Apply.ts:259,
  *   :263, :303 — no option reaches it), and 555 Bao.CloudflareRole resources each read, diff,
  *   reconcile and read back: well over a thousand requests at one loopback listener within seconds.
@@ -42,7 +42,7 @@ export const BaoEnv = Context.Reference<BaoEnvironment>('homeflare/openbao/BaoEn
  *     HTTP server (listening on 127.0.0.1:8200) exited with error: set tcp
  *     127.0.0.1:8200->127.0.0.1:57974: setsockopt: invalid argument
  *   and KEPT RUNNING with 8200 closed. launchd saw a live process and restarted nothing. Everything
- *   on the mini that talks to 127.0.0.1:8200 was cut off, starting with the agent's templates, until
+ *   on the vault host that talks to 127.0.0.1:8200 was cut off, starting with the agent's templates, until
  *   a manual restart.
  * ★ THE LISTENER DYING IS A GO-ON-DARWIN FAILURE, NOT OURS TO FIX. Traefik lost its entrypoints the
  *   same way on darwin/arm64 (traefik issue 8841). The BURST is ours. The adoption deploy an hour
@@ -70,7 +70,7 @@ const TIMEOUT = '60 seconds';
 /**
  * Mesh in front of a remote OpenBao drops connections under Alchemy's unbounded
  * fan-out. Status 0 is transport, not an OpenBao 4xx — retry twice. Measured
- * 2026-09-16 against api.v.homeflare.dev: a 585-role plan died mid-diff with
+ * 2026-09-16 against bao.example.internal: a 585-role plan died mid-diff with
  * `no response: (no errors given)` while the vault stayed unsealed.
  */
 const retryTransport = <A, R>(effect: Effect.Effect<A, BaoError, R>) =>
@@ -136,7 +136,7 @@ export const baoCall = (
     const address = resolveAddress(env);
     const client = yield* HttpClient.HttpClient;
     // ⚠️ The content type goes on `bodyText`, never in the header map: `bodyText` overwrites it.
-    //   house/proxmox/src/client.ts has the scar.
+    //   <estate>/proxmox/src/client.ts has the scar.
     const request = HttpClientRequest.make(method)(`${address.base}/v1/${path}`).pipe(
       HttpClientRequest.setHeaders(headersFor(address, env)),
       body === undefined

package/src/openbao/bao-status.test.ts

@@ -86,7 +86,7 @@ describe('settle', () => {
 
   // ⛔ A success body can hold a credential, so a malformed one is described and never quoted.
   it('fails an unparseable success body without quoting it', () => {
-    const error = errorOf(settle('read', 'GET', 'pbs-tb4/creds/read', 200, 'secret=abc123 {'));
+    const error = errorOf(settle('read', 'GET', 'pbs-c1/creds/read', 200, 'secret=abc123 {'));
     assert.ok(!error.message.includes('abc123'));
   });
 

package/src/openbao/bao-status.ts

@@ -121,7 +121,7 @@ export const settle = (
     if (errors === undefined) {
       // ⛔ DESCRIBED, NEVER QUOTED. A proxy or gateway error page can echo the request back, headers
       //   and all, so quoting it could carry X-Vault-Token into an error that Alchemy logs (grok,
-      //   2026-09-14). mint in house/proxmox/src/credentials.ts already did it this way.
+      //   2026-09-14). mint in <estate>/proxmox/src/credentials.ts already did it this way.
       return fail([`not an OpenBao error body (${String(text.length)} bytes)`]);
     }
     if (status === 404 && intent !== 'write') return { body: undefined };

package/src/openbao/cloudflare-group-scope.test.ts

@@ -10,7 +10,7 @@
  *   permission-groups`: `Logs Read` is listed twice, `6a315a56…` at `com.cloudflare.api.account`
  *   and `c4a30cd5…` at `com.cloudflare.api.account.zone`. The second is what the four live
  *   security roles carry on their ACCOUNT resource, and what
- *   house/nix/homeflare-config/scripts/cf-mint-analytics-tokens.py:80 pins as PG_LOGS_ZONE.
+ *   <estate>/nix/scripts/cf-mint-analytics-tokens.py:80 pins as PG_LOGS_ZONE.
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';

package/src/openbao/cloudflare-permission-groups.test.ts

@@ -143,7 +143,7 @@ describe('permissionGroupsFromEngine', () => {
   });
 
   /**
-   * ⛔ r2-backup-mini's ENTRY IS BUCKET-SCOPED (`bucket: homeflare-pg-mini`), and the two groups it
+   * ⛔ r2-backup-host's ENTRY IS BUCKET-SCOPED (`bucket: example-db-backup`), and the two groups it
    *   names are the only two the account lists at `com.cloudflare.edge.r2.bucket` — MEASURED
    *   2026-09-15: 2 of 399. A unique name still resolves whatever scope asks, which is why the
    *   account-scoped `Workers R2 Storage Read` here answers a bucket-scoped question too.

package/src/openbao/cloudflare-permission-groups.ts

@@ -103,7 +103,7 @@ const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
  * ⛔ A 403 IS A MISSING GRANT, AND IT SAYS SO. `BaoError` alone reports `GET /v1/<mount>/
  *   permission-groups -> 403: permission denied` — true, and it points nowhere: the path is
  *   deployed, the token is valid, and the one thing to change is a policy file. MEASURED 2026-09-15
- *   10:19 on the macmini-admin lane, where `bao write sys/capabilities-self` answered `[deny]` on
+ *   10:19 on the host's admin lane, where `bao write sys/capabilities-self` answered `[deny]` on
  *   this exact path. bao-status.ts argues that a failure must name what it is; this is that
  *   argument one level up.
  */
@@ -147,7 +147,7 @@ const engineGroups = (mount: string): Lookup =>
     if (data === undefined) {
       // ⚠️ 404 IS NOW A MOUNT-SHAPED ANSWER, NOT THE EXPECTED ONE. The path IS deployed
       //   estate-wide (measured 2026-09-15), so a 404 here means this mount is served by an older
-      //   plugin binary or BAO_ADDR is not the mini — never "no groups".
+      //   plugin binary or BAO_ADDR is not the vault host — never "no groups".
       const why = 'GET <mount>/permission-groups answered 404 — the endpoint is not deployed here';
       return Effect.fail(new CloudflareGroupsError(mount, [why]));
     }
@@ -231,7 +231,7 @@ export const permissionGroupsFromEngine = () =>
  *   undeclared live role carries IDs with no names to pair them with — and solves the account at
  *   once.
  * 🔴 WHAT RETIRED IT, 2026-09-15 10:13: `alchemy deploy` could not create
- *   `cloudflare-{<account>,testing}-platform/roles/r2-backup-mini` — `unknown group "Workers R2
+ *   `cloudflare-{<account>,testing}-platform/roles/r2-backup-host` — `unknown group "Workers R2
  *   Storage Bucket Item Write" — no live role on account <account> carries it; a NEW group needs
  *   the engine endpoint`. That is this source's documented blind spot arriving, not a bug in it.
  *

package/src/openbao/cloudflare-policy.ts

@@ -2,7 +2,7 @@
  * A Cloudflare policy document as the engine stores it — resolution from names, parsing from a
  * read, and the one comparison every Bao.CloudflareRole plan rests on.
  *
- * MEASURED from the engine source (house/platform/secrets/vault/plugin/cloudflare/path_roles.go)
+ * MEASURED from the engine source (<estate>/platform/secrets/vault/plugin/cloudflare/path_roles.go)
  * and the 2026-09-14 snapshot of all 586 live roles:
  *   • `policies` is a STRING field holding a JSON array (path_roles.go:67-72). Each entry is
  *     `{effect, resources: map[string]string, permission_groups: [{id}]}` (:25-33).

package/src/openbao/cloudflare-role-form.ts

@@ -2,7 +2,7 @@
  * Props, attributes and field comparison for Bao.CloudflareRole — the resource is
  * cloudflare-role.ts, the policy document rules are cloudflare-policy.ts.
  *
- * MEASURED from the engine (house/platform/secrets/vault/plugin/cloudflare/path_roles.go) and the
+ * MEASURED from the engine (<estate>/platform/secrets/vault/plugin/cloudflare/path_roles.go) and the
  * 2026-09-14 snapshot of all 586 live roles:
  *   • A role is name, description, policies, ttl and max_ttl AND NOTHING ELSE (path_roles.go:14-20
  *     stores those; :204-210 returns them). Every snapshot read carries exactly those five keys, so
@@ -79,7 +79,7 @@ export interface RoleDifference {
   readonly have: string;
 }
 
-/** `cloudflare-<account>-dns/roles/homeflare-dev-dns-read` — read, write and delete use it. */
+/** `cloudflare-<account>-dns/roles/example-dns-read` — read, write and delete use it. */
 export const rolePath = (mount: string, name: string) => `${mountPath(mount)}/roles/${name}`;
 
 const seconds = (value: unknown) =>

package/src/openbao/cloudflare-roles-expand.ts

@@ -44,7 +44,7 @@ export interface DeclaredPolicy {
    * ⛔ IT MOVES THE LOOKUP, NEVER THE RESOURCE. The entry still binds the groups to the resource
    *   above; only the id chosen for each name changes. That is the shape Cloudflare calls "all
    *   zones from an account" — the ACCOUNT resource carrying ZONE-scoped groups
-   *   (house/nix/homeflare-config/scripts/cf-mint-analytics-tokens.py:155-158, beside a working
+   *   (<estate>/nix/scripts/cf-mint-analytics-tokens.py:155-158, beside a working
    *   token). Without this field the resource is the only witness, and it says `account`.
    */
   readonly scope?: string;

package/src/openbao/digest.ts

@@ -8,7 +8,7 @@
  * The only form a policy body may be hashed or compared in.
  *
  * ⛔ OPENBAO STRIPS THE TRAILING NEWLINE AND THAT ALONE WAS A FOREVER-DIFF. MEASURED on the live
- *   server: the assembler emits each fragment followed by a newline, so `homeflare-llm` goes in as
+ *   server: the assembler emits each fragment followed by a newline, so `app-llm` goes in as
  *   41 lines and `bao policy read` hands back 40 — identical text, one `\n` apart, two different
  *   digests. Every plan therefore reported `update`, every deploy rewrote the same policy, and the
  *   stack could never settle. It was invisible until the stack planned for the first time today.

package/src/openbao/forgejo-bootstrap-parse.test.ts

@@ -29,11 +29,11 @@ describe('usernamesFrom', () => {
   test('reads the Username column of the measured table', () => {
     const table = [
       'ID   Username            Email                                   IsActive IsAdmin 2FA',
-      '1    tim                 tim@example.invalid                     true     true    false',
+      '1    alice               alice@example.invalid                   true     true    false',
       '7    forgejo-provision   forgejo-provision@noreply.example        true     false   false',
       '',
     ].join('\n');
-    expect(usernamesFrom(table)).toEqual(['tim', 'forgejo-provision']);
+    expect(usernamesFrom(table)).toEqual(['alice', 'forgejo-provision']);
   });
 
   test('refuses a table it does not recognise rather than reporting nobody', () => {
@@ -63,7 +63,7 @@ describe('readCreateOutput', () => {
   });
 
   test('reports not created when the success line names someone else or is missing', () => {
-    expect(readCreateOutput("New user 'tim' has been successfully created!", user).created).toBe(
+    expect(readCreateOutput("New user 'alice' has been successfully created!", user).created).toBe(
       false,
     );
     const noPassword = readCreateOutput(

package/src/openbao/forgejo-bootstrap-parse.ts

@@ -5,9 +5,9 @@
  *   read off the running 16.0.3 daemon or its source on 2026-09-14, not assumed.
  */
 
-/** Where the mini's Forgejo keeps its state (hosts/macmini/modules/forgejo.nix:235, app.ini:14). */
+/** Where the host's Forgejo keeps its state (its NixOS module and `app.ini`). */
 export const FORGEJO_WORK_PATH = '/opt/homeflare/forgejo';
-/** The file the launchd runner renders at every start (forgejo.nix:78). Readable by tim, who runs Forgejo. */
+/** The file the launchd runner renders at every start. Readable by the account that runs Forgejo. */
 export const FORGEJO_CONFIG = `${FORGEJO_WORK_PATH}/custom/conf/app.ini`;
 
 /**