@homeflare/alchemy 0.11.0 → 0.13.0

package/docs/adopted-deploys.md

@@ -38,6 +38,7 @@ API token on the cluster, just as it does for `alchemy plan`.
 | `Proxmox.BackupJob`            | `cluster/backup/{id}`                                           | read        | shared path — no write                                                                               |
 | `Proxmox.MetricServer`         | `cluster/metrics/server/{id}`                                   | read        | shared path — no write                                                                               |
 | `Proxmox.NotificationTarget` ² | `cluster/notifications/endpoints/{type}/{name}`                 | read        | shared path — no write                                                                               |
+| `Proxmox.NotificationMatcher`  | `cluster/notifications/matchers/{name}`                         | read        | shared path — no write                                                                               |
 | `Proxmox.HaResource`           | `cluster/ha/resources/{sid}`                                    | read        | shared path — no write                                                                               |
 | `Proxmox.HaRule`               | `cluster/ha/rules/{rule}`                                       | read        | shared path — no write                                                                               |
 | `Proxmox.SdnZone`              | `cluster/sdn/zones/{zone}`                                      | provision ¹ | shared path — no write                                                                               |
@@ -47,6 +48,8 @@ API token on the cluster, just as it does for `alchemy plan`.
 | `Pbs.PruneJob`                 | `config/prune/{id}`                                             | read (PBS)  | shared path — no write                                                                               |
 | `Pbs.SyncJob`                  | `config/sync/{id}`                                              | read (PBS)  | shared path — no write                                                                               |
 | `Pbs.VerifyJob`                | `config/verify/{id}`                                            | read (PBS)  | shared path — no write                                                                               |
+| `Pbs.NotificationMatcher`      | `config/notifications/matchers/{name}`                          | read (PBS)  | shared path — no write                                                                               |
+| `Pbs.NotificationTarget` ⁵     | `config/notifications/endpoints/{type}/{name}`                  | read (PBS)  | own: GET, PUT only for a stale group, GET — no write                                                 |
 | `Proxmox.Acl`                  | `access/acl` (whole list, filtered)                             | provision ¹ | shared path, then its own `bound` check — no write                                                   |
 | `Pbs.Datastore`                | `config/datastore/{name}`                                       | read (PBS)  | own: GET, path/backend guards, PUT skipped on `matches`, settle GET — no write                       |
 | `Proxmox.SdnApply`             | 5 × `cluster/sdn/*?pending=1` + fabrics `?pending` / `?running` | read        | own: counts staged objects; zero returns at once — **no `PUT /cluster/sdn`**                         |
@@ -65,13 +68,18 @@ no-write row applies. Pinned by `src/proxmox/lxc-adopt.test.ts` ("deploys with n
 declared ratio that differs from the live one is never written on a no-op adoption and never
 reported as a diff.
 
+⁵ Its own `diff` and `reconcile`, because a secret's value is not in the live object: the plan
+compares a seal kept in the previous state ([pbs-notifications.md](./pbs-notifications.md)). An
+adopted target has no seal, so its secret values are presence-only and adoption writes nothing.
+Pinned by `src/proxmox/pbs-notification-target-state.test.ts`.
+
 ## Before the fix: `Proxmox.CephPool`
 
 `reconcile` read the pool and, whenever it existed, PUT the declared `size`, `min_size`,
 `pg_autoscale_mode`, `crush_rule` (and any declared hints) to `nodes/{node}/ceph/pool/{name}`.
 That PUT forks a `cephsetpool` worker under the provision token. PVE's `set_pool` skips each
 setting whose value is unchanged (Tools.pm:293-300), so a matching pool was not re-tuned. It was
-still a provision-lease write and a task on the node every time the pool was adopted. TB4's task
+still a provision-lease write and a task on the node every time the pool was adopted. C1's task
 list shows six such tasks (2026-09-13 and 2026-09-20), one per declared pool per deploy.
 
 ## How it is pinned

package/docs/ownership.md

@@ -4,7 +4,8 @@ A live object this stack holds **no state for** is never taken over silently. Th
 `Bao.*` family, `HostFile`, `LaunchdJob`, `CaddyConfig` and `ProxmoxLxc`, and it holds even when the
 live object is **identical** to the declaration: identical is not ours. Another stack, a person or an old
 script put it there, and once state claims it, a delete under `RemovalPolicy.destroy()` removes it
-from its real owner. (Decided 2026-09-21; the Bao families adopted silently until 0.9.0.)
+from its real owner. (Decided 2026-09-21; the Bao families adopted silently until 0.9.0. 0.9.0 was
+never published, so 0.10.0 is the first release with the rule.)
 
 To take an object over, say so:
 
@@ -92,6 +93,30 @@ read, a resume reads as a fresh create and asks for `--adopt`. `alchemy deploy`
 session both share one. An orphan's interrupted create (no longer declared) cannot be compared with
 a declaration, so Apply leaves its object in place with a note instead of deleting it.
 
+## After a wiped store or `state delete`, it needs `--adopt`
+
+Alchemy's documented repair for a bad record is `alchemy state delete`, then `alchemy deploy`,
+escalating to `--adopt` only on `OwnedBySomeoneElse`
+([inspecting state](https://alchemy.run/cli/inspecting-state#recover-from-bad-state)). For the
+families above that escalation always comes (decided 2026-09-21): an object whose row is gone is
+`Unowned`, so the deploy needs `--adopt`, or `adopt(true)` on its declaration. `MeshNode`
+([mesh-node.md](./mesh-node.md)) and `R2BucketLock` (`src/cloudflare/r2-bucket-lock.ts`) need it
+too. A `CaddyConfig` running the declared config re-imports without it, and so does every family
+whose `read` never answers `Unowned`: the `pveHandlers` resources (Limits), the `forgejoHandlers`
+resources and the Talos resources. Read the takeover first with `hf-adopt-verify`
+([adopt-verify.md](./adopt-verify.md)).
+
+★ This departs from Alchemy's docs, not from its code. The docs say a provider with no ownership
+marker answers plain attributes, so its objects re-import silently (`AdoptPolicy.ts`,
+[adopting resources](https://alchemy.run/cli/adopting-resources),
+[provider](https://alchemy.run/infrastructure-as-code/provider#read)). Many of Alchemy's own
+marker-less providers answer `Unowned` to a read with no state instead, as the kit's families do
+(beta.79: `Cloudflare/Snippets/Snippet.ts`, `Cloudflare/Tunnel/WarpConnector.ts`,
+`Cloudflare/Zone/Hold.ts`). After a wiped store those need `--adopt` too.
+
+⚠️ **That page's `alchemy state delete myapp/pr-42` fails.** A stage or a whole stack is a
+directory, and deleting one needs `-r` (beta.79 `State/Tree.ts`). A single row does not.
+
 ## Limits
 
 - ⚠️ **A check, then a write: not a lock.** Two resources that declare the same name in **one**

package/docs/pbs-alertmanager-body.md

@@ -0,0 +1,73 @@
+# A PBS webhook body that posts an Alertmanager alert
+
+`alertmanagerAlertBody()` ([alertmanager-body.ts](../src/proxmox/alertmanager-body.ts)) is the
+body of a PBS webhook target that posts one alert to Alertmanager's `POST /api/v2/alerts`.
+Declaring the target and the matcher that routes to it: [pbs-notifications.md](./pbs-notifications.md).
+
+With the default options it returns exactly this text:
+
+```text
+[
+  {
+    "labels": {
+      {{#if fields.type}}"job_type": {{ json fields.type }},{{/if}}
+      {{#if fields.job-id}}"job_id": {{ json fields.job-id }},{{/if}}
+      {{#if fields.datastore}}"datastore": {{ json fields.datastore }},{{/if}}
+      {{#if fields.hostname}}"hostname": {{ json fields.hostname }},{{/if}}
+      "severity": {{ json severity }},
+      "alertname": "PbsNotification",
+      "source": "pbs"
+    },
+    "annotations": {
+      "summary": {{ json title }},
+      "description": {{ json message }},
+      "timestamp": "{{ timestamp }}"
+    }
+  }
+]
+```
+
+The fence is `text` on purpose. As a `handlebars` fence the formatter reflowed it into
+something the function does not return.
+
+Options: `alertname`, `source` and an optional `generatorURL`. Braces and backslashes are
+refused in all three. `generatorURL` must also be an absolute `http` or `https` URL, because
+Alertmanager validates it as a URI and rejects the whole post if it is not one.
+
+## Why it is valid JSON for every PBS notification
+
+Each point is from the proxmox-notify, proxmox-backup and Alertmanager source, read 2026-09-22.
+
+- **The webhook renderer has no escaping** (`register_escape_fn(no_escape)`). Every value that
+  comes from the notification goes through `json`, which is `serde_json::to_string`. It writes
+  a complete, quoted JSON string with quotes, backslashes and control characters escaped. A task
+  log with a quote, a tab or a newline stays valid JSON.
+- **`escape` on a missing field fails the whole render**, and the notification is lost.
+  `json` on a missing field writes `null`, which is valid JSON but not a label value. So every
+  `fields.*` label sits inside `{{#if}}` and ends with its own comma, and the constant labels
+  close the object. The UI's **Test** button sends a notification with no fields at all.
+- **Every field value is a string.** proxmox-notify turns each metadata field into a JSON string
+  before rendering. `severity` serialises as `info`, `notice`, `warning`, `error` or `unknown`,
+  and `timestamp` is an integer (epoch seconds). Nothing else in the data is rendered.
+- **The helpers are `json`, `escape` and `url-encode`, and nothing else.** The mail templates'
+  `timestamp` and `duration` helpers are not registered for webhooks, so `timestamp` is sent as
+  epoch seconds in an annotation.
+- **Alertmanager takes an array** (`postableAlerts`). `labels` is required and must not be empty.
+  Every label and annotation value must be a string. It drops empty labels.
+
+`tests/alertmanager-body.test.ts` renders the template with handlebars.js set up the way
+proxmox-notify sets up its renderer. It covers the field set of every event type in PBS's
+`src/server/notifications/mod.rs`, the Test notification, forwarded system mail, and hostile
+strings (quotes, backslashes, control characters, `{{`, U+2028). Each result must parse as an
+Alertmanager v2 alert array. A scratch build of handlebars-rust 5.1.2, the major version
+proxmox-notify pins, rendered the same cases to valid JSON. The first real notification is
+still the check that counts: press **Test** on the target, then read what Alertmanager received.
+
+## What it does not do
+
+- **With no `endsAt`, Alertmanager resolves the alert itself** after `resolve_timeout` (5 min by
+  default), and PBS never sends a resolve. Treat a "resolved" notification as a timeout, not a
+  recovery.
+- **`severity` uses PBS's names.** Route on `severity="error"`, or relabel in Alertmanager.
+- **Alertmanager deduplicates by label set.** Two failures of the same job within
+  `resolve_timeout` are one alert, not two.

package/docs/pbs-notifications.md

@@ -0,0 +1,163 @@
+# PBS and PVE notifications — targets, matchers, and an Alertmanager webhook
+
+`@homeflare/alchemy/proxmox` declares both halves of the Proxmox notification system:
+
+| family                        | what it is                                          | source                                                                    |
+| ----------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- |
+| `Pbs.NotificationTarget`      | where PBS sends: `webhook`, `smtp`, `sendmail`      | [pbs-notification-target.ts](../src/proxmox/pbs-notification-target.ts)   |
+| `Pbs.NotificationMatcher`     | which PBS notifications go to which targets         | [pbs-notification-matcher.ts](../src/proxmox/pbs-notification-matcher.ts) |
+| `Proxmox.NotificationMatcher` | the same on a PVE cluster                           | [notification-matcher.ts](../src/proxmox/notification-matcher.ts)         |
+| `Proxmox.NotificationTarget`  | PVE targets (existing; declares no secret)          | [notification-target.ts](../src/proxmox/notification-target.ts)           |
+| `alertmanagerAlertBody()`     | a webhook body that posts one Alertmanager v2 alert | [pbs-alertmanager-body.md](./pbs-alertmanager-body.md)                    |
+
+A target that no matcher names receives nothing. Declare both.
+
+## Paging on a failed verify, sync, prune or garbage collection
+
+```ts
+import * as Effect from 'effect/Effect';
+import {
+  PbsNotificationMatcher,
+  PbsNotificationTarget,
+  alertmanagerAlertBody,
+} from '@homeflare/alchemy/proxmox';
+
+const pbs = {
+  api: 'https://pbs.example.com:8007/api2/json',
+  mount: 'pbs-mount',
+  scheme: 'pbs',
+} as const;
+
+export const notifications = Effect.gen(function* () {
+  const hook = yield* PbsNotificationTarget('alertmanager', {
+    target: pbs,
+    type: 'webhook',
+    name: 'alertmanager',
+    method: 'post',
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+    header: {
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer {{ secrets.token }}', // template text, not the token
+    },
+    secret: { token: { fromEnv: 'PBS_ALERTMANAGER_TOKEN' } }, // the token, by variable name
+    body: alertmanagerAlertBody(),
+  });
+  yield* PbsNotificationMatcher('page-on-failure', {
+    target: pbs,
+    name: 'page-on-failure',
+    targets: [hook.name], // the Output, not a string: it orders create and delete
+    'match-severity': ['error'],
+    'match-field': ['exact:type=gc,prune,sync,verify'],
+  });
+});
+```
+
+Drop the `Authorization` header and the `secret` when Alertmanager takes unauthenticated posts
+on a trusted network. The provider layer is `PbsNotificationTargetProvider()` and
+`PbsNotificationMatcherProvider()`. `targets: [hook.name]` matters: PBS refuses a matcher that
+names a missing target, and refuses to delete a target a matcher still names. The Output gives
+Alchemy that ordering; a bare string does not (`pbs-notifications-stack.test.ts`).
+
+⛔ **A datastore in `legacy-sendmail` mode never reaches a matcher.** PBS mails its `notify-user`
+directly. `notification-system` is the default, but a datastore created before PBS 3.2 can say
+otherwise. Check with `proxmox-backup-manager datastore show <name>`.
+
+⚠️ **A verification job's event `type` is `verify`**, not `verification`. PBS's own event table
+says `verification`, and the source (`send_verify_status`) sets `verify`. The other types are
+`gc`, `prune`, `sync`, `tape-backup`, `tape-load`, `package-updates`, `acme`, `thresholds` and
+`system-mail`. Garbage collection has no `job-id`.
+
+⚠️ **`match-severity: ['warning', 'error']` under the default `mode: 'all'` matches nothing.**
+Each item is combined with `mode`. The severities inside one item are OR-ed, so write
+`['warning,error']`.
+
+## Write-only values: `{ fromEnv }`
+
+Alchemy stores props and attributes unencrypted, and a `Redacted` value is tagged, not
+encrypted. A secret prop would be a secret in the state database. So `secret`, the smtp
+`password` and any header value that is a credential are declared as `{ fromEnv: 'NAME' }`.
+The deploying process reads the variable at call time.
+
+| what            | in state                                       | how a plan compares it                                                           |
+| --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| secret values   | names (PBS returns names only), and a **seal** | seal of what this provider last wrote, checked against the env value             |
+| smtp password   | the seal only (PBS returns nothing)            | the same seal                                                                    |
+| header values   | names, and a scrypt digest of the live pairs   | digest of the declared values (env-resolved) against the digest of the live ones |
+| everything else | the value                                      | by value, like every family here                                                 |
+
+The seal is `scrypt:<salt>:<digest>`, with a random salt per write. It proves "unchanged" and
+holds nothing a reader could send to PBS. A guessable secret stays guessable, so use a random
+token.
+
+- **A plan without the variables is presence-only.** Names are compared and values are
+  `unknown`. `unknown` plans `noop`, never an invented update.
+- **A write carries only the stale groups.** A PUT without `secret` or `header` leaves those on
+  the server as they are, so a changed comment deploys without the secrets.
+- **A write that needs a missing variable fails by name**, before any request is sent.
+- **Adoption is free.** A webhook adopted with secrets has no seal. Its values stay unverified
+  (presence-only) until the first write that carries them: a create, a changed secret name, or
+  a value rotated after that first write. A value the server already holds is never replaced by
+  adoption alone. To write yours, rename the secret once, together with its `{{ secrets.* }}`
+  references.
+- **Rotation.** Change the variable's value and plan: the seal no longer matches, and the deploy
+  PUTs the secret group alone.
+
+⛔ **A literal credential in a plain prop is refused.** A plain prop is stored as written, so an
+`Authorization`, `Proxy-Authorization` or `Cookie` header, a header or URL query parameter
+named like `token`, `key`, `secret`, `password` or `signature`, or a password in the URL's
+userinfo must be `{ fromEnv }` or read `{{ secrets.<name> }}`. The plan fails and names the
+field, never the value.
+
+⚠️ **What the guard cannot see.** A token in a URL path (Slack-style webhooks), in `body` or in
+`comment` is still a plain prop. Put it in `secret` and reference it from the template. The
+check runs at plan only while every prop is resolved. If a prop is an unresolved Output, Alchemy
+records the props before `reconcile` refuses them.
+
+⚠️ **Prefer `secret` over a `{ fromEnv }` header for a credential.** PBS returns header values
+to anyone with `Sys.Audit`, and prints a header's value unmasked when it fails to render. It
+masks only `secret` values.
+
+## The body template
+
+`alertmanagerAlertBody()` has its own page, with the exact text it returns and why it is valid
+JSON for every notification PBS sends: [pbs-alertmanager-body.md](./pbs-alertmanager-body.md).
+
+## Adopting the built-in `default-matcher`
+
+A matcher is compared as its whole rule: `match-*`, `mode`, `invert-match` and `disable`,
+declared or not. Only `comment` is left alone when undeclared. Adopting a built-in means
+declaring what it holds. Measured 2026-09-22:
+
+```ts
+// PVE 9.2.11: everything to mail-to-root
+ProxmoxNotificationMatcher('default-matcher', {
+  target: cluster,
+  name: 'default-matcher',
+  targets: ['mail-to-root'],
+});
+// PBS 4.2: everything except successful prune jobs
+PbsNotificationMatcher('default-matcher', {
+  target: pbs,
+  name: 'default-matcher',
+  targets: ['mail-to-root'],
+  'invert-match': true,
+  'match-field': ['exact:type=prune'],
+  'match-severity': ['info'],
+});
+```
+
+Both plan `noop` and deploy with no write (`notification-matcher.test.ts`). ⛔ **Deleting a
+built-in reverts it to the shipped rule**, and the server reports success. The attributes show
+`origin` so you can see which kind you have.
+
+## Privileges
+
+| server | read                                                            | write                                        |
+| ------ | --------------------------------------------------------------- | -------------------------------------------- |
+| PBS    | `Sys.Audit` on `/system/notifications`                          | `Sys.Modify` on `/system/notifications`      |
+| PVE    | `Mapping.Audit` or `Mapping.Modify` on `/mapping/notifications` | `Mapping.Modify` on `/mapping/notifications` |
+
+⚠️ A missing read privilege looks like "absent". The plan says `create` and the server answers
+that the object already exists. Grant the read before changing anything else. On PVE,
+`Mapping.Use` is not enough: it opens the matcher list, not the per-matcher read this package
+makes (`get_matcher` in pve-manager's `Notifications.pm`).

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,12 @@ 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)).
+- ★ **Notifications that page**: PBS webhook, smtp and sendmail targets with write-only secrets
+  (`{ fromEnv }`, never in state), PBS and PVE matchers, and a webhook body that posts an
+  Alertmanager v2 alert ([pbs-notifications.md](./pbs-notifications.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.13.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;