@homeflare/alchemy 0.35.0 → 0.37.0

package/dist/proxmox/storage-wire.d.ts

@@ -1,3 +1,10 @@
+/**
+ * `Proxmox.Storage`'s READ side: how a live item becomes attributes, the read itself, and
+ * `matches`. Split out of storage.ts (2026-09-24, the distilled migration); the write side is
+ * storage-form.ts (that file's own header has the reasoning) — both stay under the 250-line cap,
+ * the api-token.ts/api-token-form.ts seam.
+ */
+import * as storage from '@distilled.cloud/proxmox/storage';
 import * as Effect from 'effect/Effect';
 import type { StorageProps } from './storage.ts';
 import { UNREADABLE, type Unreadable } from './unreadable-read.ts';
@@ -33,7 +40,7 @@ export declare const same: <T>(declared: T | undefined, live: T) => boolean;
  *   `readUser`/`readGroup` do, so a brand-new declaration can still be created; `readStorageOrFail`
  *   (used by `diff`) does not.
  */
-export declare const readStorageOrFail: (props: StorageProps) => Effect.Effect<typeof UNREADABLE | StorageAttributes, import("@distilled.cloud/caddy").BadGateway | import("@distilled.cloud/caddy").BadRequest | import("@distilled.cloud/caddy").ConfigError | Error | import("@distilled.cloud/caddy").GatewayTimeout | import("effect/unstable/http/HttpClientError").HttpClientError | import("@distilled.cloud/caddy").InternalServerError | import("@distilled.cloud/proxmox/Errors").ParameterVerificationFailed | import("@distilled.cloud/proxmox/Errors").ProxmoxParseError | import("./distilled-pve.ts").PveClusterExhausted | import("@distilled.cloud/caddy").ServiceUnavailable | import("effect/Cause").TimeoutError | import("@distilled.cloud/caddy").TooManyRequests | import("@distilled.cloud/caddy").Unauthorized | import("@distilled.cloud/proxmox/Errors").UnknownProxmoxError, import("effect/unstable/http/HttpClient").HttpClient>;
+export declare const readStorageOrFail: (props: StorageProps) => Effect.Effect<typeof UNREADABLE | StorageAttributes, import("@distilled.cloud/caddy").BadGateway | import("@distilled.cloud/caddy").BadRequest | import("@distilled.cloud/caddy").ConfigError | Error | import("@distilled.cloud/caddy").GatewayTimeout | import("effect/unstable/http/HttpClientError").HttpClientError | import("@distilled.cloud/caddy").InternalServerError | import("@distilled.cloud/proxmox/Errors").ParameterVerificationFailed | import("@distilled.cloud/proxmox/Errors").ProxmoxParseError | import("./distilled-pve.ts").PveClusterExhausted | import("@distilled.cloud/caddy").ServiceUnavailable | storage.StorageNotFound | import("effect/Cause").TimeoutError | import("@distilled.cloud/caddy").TooManyRequests | import("@distilled.cloud/caddy").Unauthorized | import("@distilled.cloud/proxmox/Errors").UnknownProxmoxError, import("effect/unstable/http/HttpClient").HttpClient>;
 /**
  * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT —
  *   user.ts's `readUser` has the full reasoning. Safe here because a wrongful fold costs at most a

package/dist/proxmox/storage-wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/storage-wire.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAGrF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAmBD,eAAO,MAAM,QAAQ,aAAc,MAAM,GAAG,SAAS,QAAQ,MAAM,YACN,CAAC;AAE9D,eAAO,MAAM,IAAI,GAAI,CAAC,YAAY,CAAC,GAAG,SAAS,QAAQ,CAAC,YACX,CAAC;AAwB9C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,UAAW,YAAY,m2BAGyC,CAAC;AAE/F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,UAAW,YAAY,kIACuB,CAAC;AAEvE,gGAAgG;AAChG,eAAO,MAAM,cAAc,SAAU,iBAAiB,GAAG,UAAU,GAAG,SAAS,kCACvC,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,OAAO,eAAgB,iBAAiB,SAAS,YAAY,YAOjC,CAAC"}
+{"version":3,"file":"storage-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/storage-wire.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,OAAO,MAAM,kCAAkC,CAAC;AAC5D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAGrF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAmBD,eAAO,MAAM,QAAQ,aAAc,MAAM,GAAG,SAAS,QAAQ,MAAM,YACN,CAAC;AAE9D,eAAO,MAAM,IAAI,GAAI,CAAC,YAAY,CAAC,GAAG,SAAS,QAAQ,CAAC,YACX,CAAC;AAwB9C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,UAAW,YAAY,63BAGyC,CAAC;AAE/F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,UAAW,YAAY,kIACuB,CAAC;AAEvE,gGAAgG;AAChG,eAAO,MAAM,cAAc,SAAU,iBAAiB,GAAG,UAAU,GAAG,SAAS,kCACvC,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,OAAO,eAAgB,iBAAiB,SAAS,YAAY,YAOjC,CAAC"}

package/dist/proxmox/user-wire.d.ts

@@ -29,7 +29,7 @@ export declare const matches: (attributes: UserAttributes, props: UserProps) =>
  *   `PveClusterExhausted`, then silently folded to "absent" by the old `orElseSucceed`, forcing a
  *   false `update` on every account.
  */
-export declare const readUserOrFail: (props: UserProps) => Effect.Effect<typeof UNREADABLE | UserAttributes, import("@distilled.cloud/caddy").BadGateway | import("@distilled.cloud/caddy").BadRequest | import("@distilled.cloud/caddy").ConfigError | Error | import("@distilled.cloud/caddy").GatewayTimeout | import("effect/unstable/http/HttpClientError").HttpClientError | import("@distilled.cloud/caddy").InternalServerError | import("@distilled.cloud/proxmox/Errors").ParameterVerificationFailed | import("@distilled.cloud/proxmox/Errors").ProxmoxParseError | import("./distilled-pve.ts").PveClusterExhausted | import("@distilled.cloud/caddy").ServiceUnavailable | import("effect/Cause").TimeoutError | import("@distilled.cloud/caddy").TooManyRequests | import("@distilled.cloud/caddy").Unauthorized | import("@distilled.cloud/proxmox/Errors").UnknownProxmoxError, import("effect/unstable/http/HttpClient").HttpClient>;
+export declare const readUserOrFail: (props: UserProps) => Effect.Effect<typeof UNREADABLE | UserAttributes, import("@distilled.cloud/caddy").BadGateway | import("@distilled.cloud/caddy").BadRequest | import("@distilled.cloud/caddy").ConfigError | Error | import("@distilled.cloud/caddy").GatewayTimeout | import("effect/unstable/http/HttpClientError").HttpClientError | import("@distilled.cloud/caddy").InternalServerError | import("@distilled.cloud/proxmox/Errors").ParameterVerificationFailed | import("@distilled.cloud/proxmox/Errors").ProxmoxParseError | import("./distilled-pve.ts").PveClusterExhausted | import("@distilled.cloud/caddy").ServiceUnavailable | import("effect/Cause").TimeoutError | import("@distilled.cloud/caddy").TooManyRequests | import("@distilled.cloud/caddy").Unauthorized | import("@distilled.cloud/proxmox/Errors").UnknownProxmoxError | access.UserNotFound, import("effect/unstable/http/HttpClient").HttpClient>;
 /**
  * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT. A
  *   missing user is a thrown 500 (user.ts's own header), so `reconcile`'s create branch NEEDS

package/dist/proxmox/user-wire.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/user-wire.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,iCAAiC,CAAC;AAC1D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAGrF,eAAO,MAAM,WAAW,2BAA2B,CAAC;AACpD,eAAO,MAAM,WAAW,mCAAmC,CAAC;AA2D5D,eAAO,MAAM,UAAU,UAAW,SAAS,KAAG,MAAM,CAAC,uBAGnD,CAAC;AAEH,eAAO,MAAM,UAAU,UAAW,SAAS,KAAG,MAAM,CAAC,oBAGnD,CAAC;AAoBH;;;GAGG;AACH,eAAO,MAAM,OAAO,eAAgB,cAAc,SAAS,SAAS,YAOF,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,UAAW,SAAS,g2BAG+C,CAAC;AAE/F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,UAAW,SAAS,+HAC0B,CAAC;AAEpE,gGAAgG;AAChG,eAAO,MAAM,cAAc,SAAU,cAAc,GAAG,UAAU,GAAG,SAAS,+BACpC,CAAC"}
+{"version":3,"file":"user-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/user-wire.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,iCAAiC,CAAC;AAC1D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAGrF,eAAO,MAAM,WAAW,2BAA2B,CAAC;AACpD,eAAO,MAAM,WAAW,mCAAmC,CAAC;AA2D5D,eAAO,MAAM,UAAU,UAAW,SAAS,KAAG,MAAM,CAAC,uBAGnD,CAAC;AAEH,eAAO,MAAM,UAAU,UAAW,SAAS,KAAG,MAAM,CAAC,oBAGnD,CAAC;AAoBH;;;GAGG;AACH,eAAO,MAAM,OAAO,eAAgB,cAAc,SAAS,SAAS,YAOF,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,UAAW,SAAS,s3BAG+C,CAAC;AAE/F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,UAAW,SAAS,+HAC0B,CAAC;AAEpE,gGAAgG;AAChG,eAAO,MAAM,cAAc,SAAU,cAAc,GAAG,UAAU,GAAG,SAAS,+BACpC,CAAC"}

package/docs/argocd-kubernetes.md

@@ -0,0 +1,100 @@
+# Argo CD `Application`/`AppProject` — via upstream's `Kubernetes` family, no new code
+
+Companion to [argocd.md](./argocd.md#the-rest-vs-crd-split-the-actual-design-decision). `Application`
+and `AppProject` are Kubernetes CRDs (`argoproj.io/v1alpha1`), not Argo CD REST-only objects — the
+upstream-correct owner is Alchemy's own `Kubernetes.Manifest`
+(`alchemy/Kubernetes`, v2.0.0-beta.79), which this kit does not wrap, re-implement, or need to:
+decision 49 ("Kubernetes uses UPSTREAM Alchemy's existing Kubernetes family... don't build a
+second one"). This page is documentation only — **no code in this kit declares an `Application` or
+`AppProject`**; it shows how a stack does, once a cluster exists.
+
+## Why not an `Argocd.Application` REST resource?
+
+Argo CD's `ApplicationService` REST API is real and full-featured (`Create`/`Get`/`Update`/
+`Patch`/`Delete`/`List`/`Sync`/`Rollback`/…), but underneath it the object it manages **is** the
+`Application` CRD — the same object `kubectl get applications.argoproj.io -n argocd` lists, with
+its own versioned OpenAPI schema, validated by the Kubernetes API server itself, not by Argo CD's
+application logic. A second, house-maintained REST wrapper around that would duplicate exactly the
+generic capability `Kubernetes.Manifest` already provides — apply any object, CRDs included, via
+server-side apply — for no benefit over declaring the CRD directly. Argo CD's own docs recommend
+exactly this: `kubectl`/GitOps management of `Application`/`AppProject` manifests is the primary
+documented workflow, not a detour around the REST API.
+
+## Declaring an `AppProject`
+
+```ts
+import * as Kubernetes from 'alchemy/Kubernetes';
+import * as Effect from 'effect/Effect';
+
+const project = Effect.gen(function* () {
+  return yield* Kubernetes.Manifest('HomeflareProject', {
+    cluster, // a Kubernetes.KubeConfig(...) or a managed cluster resource
+    manifest: {
+      apiVersion: 'argoproj.io/v1alpha1',
+      kind: 'AppProject',
+      metadata: { name: 'homeflare', namespace: 'argocd' },
+      spec: {
+        description: 'HomeFlare estate applications',
+        sourceRepos: ['https://forgejo.homeflare.dev/homeflare/*'],
+        destinations: [{ namespace: '*', server: 'https://kubernetes.default.svc' }],
+        clusterResourceWhitelist: [{ group: '*', kind: '*' }],
+      },
+    },
+  });
+});
+```
+
+## Declaring an `Application`
+
+```ts
+const app = Effect.gen(function* () {
+  return yield* Kubernetes.Manifest('HomeflareKitApp', {
+    cluster,
+    manifest: {
+      apiVersion: 'argoproj.io/v1alpha1',
+      kind: 'Application',
+      metadata: { name: 'homeflare-kit', namespace: 'argocd' },
+      spec: {
+        project: 'homeflare',
+        source: {
+          repoURL: 'https://forgejo.homeflare.dev/homeflare/kit.git',
+          targetRevision: 'main',
+          path: 'deploy/manifests',
+        },
+        destination: { server: 'https://kubernetes.default.svc', namespace: 'homeflare-kit' },
+        syncPolicy: { automated: { prune: true, selfHeal: true } },
+      },
+    },
+  });
+});
+```
+
+`Kubernetes.Manifest` resolves unknown kinds through the cluster's own API discovery endpoint
+(`Manifest.ts:31-32,89-93`), so `Application`/`AppProject` need no house registration — the CRD
+just has to already exist on the cluster (Argo CD's own install manifest creates it).
+
+## Ordering: the CRD before the object
+
+`Application`/`AppProject` are CRD-backed, so the `argoproj.io` `CustomResourceDefinition`s must
+exist before a `Kubernetes.Manifest` for either can apply — normally true the moment Argo CD
+itself is installed (its own install manifest, or `Kubernetes.HelmChart` installing the
+`argo-cd` chart, both ship the CRDs). A stack that installs Argo CD and declares Applications in
+the same deploy should thread the install as a dependency (an `Output` the Application's `cluster`
+or an explicit ordering prop depends on) so Plan waits on it — an `Output` referenced in props is a
+real dependency edge Alchemy's own Plan/Apply order on (v2.0.0-beta.79), the general rule this
+follows.
+
+## Registering the Talos-on-PVE cluster itself with Argo CD
+
+Argo CD's own control-plane cluster (where Argo CD runs) never needs registering — it is implicit
+as `https://kubernetes.default.svc`. A **separate** cluster Argo CD deploys onto (or, if Argo CD
+itself runs off-cluster) uses `Argocd.Cluster` from this kit ([argocd.md](./argocd.md)) — that
+registration genuinely is Argo CD's own non-CRD storage (a labeled `Secret`), covered by the REST
+family, not this page.
+
+## Installing Argo CD itself
+
+Out of scope for this change (no cluster exists to install onto), but the answer is also "no new
+code": `Kubernetes.HelmChart` (`alchemy/Kubernetes`) installs the upstream `argo-cd` Helm chart
+the same way any other chart installs, and `Kubernetes.Manifest` covers a plain-manifest install
+if the chart is not wanted. Neither needs anything from this kit.

package/docs/argocd.md

@@ -0,0 +1,139 @@
+# Argo CD — `@homeflare/alchemy/argocd`
+
+Built 2026-09-24, ahead of need — Tim: "we are using talos on pve once we get things settled ...
+i thought we are using argocd, i wanted it on the radar" and "even if we don't use it yet but we
+know we will." **No Talos-on-PVE cluster and no Argo CD instance exist on the estate yet.** Every
+test in this family runs against `fake-argocd.ts`; nothing here has touched a real server.
+
+## Is `@distilled.cloud/argocd` real, and does it match the kit's pins?
+
+✅ **MEASURED**, `npm view @distilled.cloud/argocd`, 2026-09-24: published, `latest` =
+**1.0.0-rc.12**, `peerDependencies.effect` = `>=4.0.0-rc.115`, `dependencies["@distilled.cloud/
+core"]` = `1.0.0-rc.12` — exactly the kit's own pins (`packages/alchemy/package.json`'s `effect`
+and every other `@distilled.cloud/*` peer). Added as a direct peer dependency, the same shape as
+`@distilled.cloud/forgejo`/`discord`/`cloudflare`/`google-workspace` — **no interim package**
+([docs/distilled-interim.md](./distilled-interim.md) applies only when the real package is
+unpublished; it is not, here).
+
+## Does upstream Alchemy already ship (or build) ArgoCD? (decision 49)
+
+✅ **MEASURED, no**: `grep -ril "argocd"` across `alchemy-run/alchemy` v2.0.0-beta.79 matches
+exactly two files, both AWS EKS "add-on capability" JSDoc examples (`src/AWS/EKS/
+DescribeCapability.ts:20`, `ListCapabilities.ts` — `describeCapability({ capabilityName: "argocd"
+})`, an EKS add-on name, unrelated to a provider). No `src/Argocd/` directory, no changeset, no
+CHANGELOG entry. So decision 49 ("upstream wins... don't build a second one") does not apply here
+— there is nothing upstream to duplicate.
+
+## What upstream's `Kubernetes` family already ships (measured)
+
+`packages/alchemy/src/Kubernetes/` (v2.0.0-beta.79): `Connection.ts`, `ClusterAdapter.ts`,
+`BuiltinAdapters.ts`, `Deployment.ts`, `HelmChart.ts`, `Job.ts`, `Manifest.ts`, `Providers.ts`.
+`Kubernetes.Manifest` (`Manifest.ts:34-284`) applies **any literal Kubernetes object — built-in
+kinds and CRDs alike** via server-side apply, with a worked "Custom resource (CRD)" example in its
+own doc comment (`Manifest.ts:116-127`). This is the upstream-correct owner for `Application` and
+`AppProject` — see [argocd-kubernetes.md](./argocd-kubernetes.md) for why and how, with examples.
+`HelmChart.ts` is how the house will install Argo CD itself later (its own Helm chart) — no new
+code needed there either.
+
+## The REST-vs-CRD split (the actual design decision)
+
+Measured against Argo CD's declarative-setup documentation and the generated operation list in
+`@distilled.cloud/argocd`'s `services/argocd.ts` (106 operations, distilled homeflare/base):
+
+| Object        | Backing store                                                                                                                                          | Owner                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `Application` | `argoproj.io/v1alpha1` CRD, its own OpenAPI schema, listable with plain `kubectl`                                                                      | **`Kubernetes.Manifest`** — [argocd-kubernetes.md](./argocd-kubernetes.md) |
+| `AppProject`  | `argoproj.io/v1alpha1` CRD, same as above                                                                                                              | **`Kubernetes.Manifest`**                                                  |
+| Repository    | a `Secret` labeled `argocd.argoproj.io/secret-type: repository` — no CRD of its own; Argo CD's own storage format, not a published Kubernetes API type | **`Argocd.Repository`** (this family)                                      |
+| RepoCreds     | a `Secret` labeled `…secret-type: repo-creds` — same reasoning                                                                                         | **`Argocd.RepoCreds`**                                                     |
+| Cluster       | a `Secret` labeled `…secret-type: cluster` — same reasoning                                                                                            | **`Argocd.Cluster`**                                                       |
+
+The line is not "REST API exists" (all seven have full REST CRUD — `ApplicationServiceService`,
+`ProjectService`, `RepositoryService`, `RepoCredsService`, `ClusterService`) — it is **whether the
+object is a real, versioned Kubernetes API type**. `Application`/`AppProject` are; Repository/
+RepoCreds/Cluster are Argo CD's own encoding smuggled into a generic `Secret`, which
+`Kubernetes.Manifest` could technically apply too, but only by hand-reconstructing Argo CD's
+private labeling convention — exactly the vendor-specific knowledge a REST SDK exists to own.
+
+## What this family builds
+
+Three resources on `@distilled.cloud/argocd/argocd`, the peer-dependency pattern
+`packages/alchemy/src/forgejo` already uses:
+
+- **`Argocd.Repository`** (`repository.ts`) — `/api/v1/repositories`.
+- **`Argocd.RepoCreds`** (`repo-creds.ts`) — `/api/v1/repocreds`, a URL-prefix credential
+  template. No single-item `Get` operation exists (measured against the operation list) —
+  `fetchLive` lists and finds, the same shape `forgejo/org-actions-secrets.ts` and
+  `discord/guild-application-command.ts` use for the same reason.
+- **`Argocd.Cluster`** (`cluster.ts`) — `/api/v1/clusters`. Only bearer-token and static
+  TLS-client-cert auth are modeled; `awsAuthConfig` (EKS IAM) and `execProviderConfig` (an exec
+  plugin) are unbuilt — neither applies to a Talos cluster.
+
+All three share one engine (`resource.ts`, `argocdOperations`/`argocdHandlers`), a near-verbatim
+copy of `forgejo/resource.ts` — both SDKs are plain bearer-REST with a real typed `NotFound`, so
+the same read/diff/reconcile/destroy shape applies unchanged.
+
+## The SDK gap that _isn't_ there (measured, and why it matters)
+
+🔴 Unlike Discord (`docs/discord.md#sdk-gaps`), Argo CD's generated error TYPE is **not** narrowed
+to `DEFAULT_ERROR_STATUSES`. Measured directly, `packages/argocd/src/protocol.ts` (distilled
+homeflare/base):
+
+```ts
+export type ArgocdOpError =
+  | InstanceType<(typeof API_ERRORS)[number]> // the FULL 12-class list, incl. NotFound/Forbidden/Conflict
+  | UnknownArgocdError
+  | ConfigError
+  | HttpClientError.HttpClientError;
+```
+
+`API_ERRORS` (not `DEFAULT_ERRORS`) is the full `HTTP_STATUS_MAP` set. And no operation carries a
+`patches/` file (`git ls-tree` on `packages/argocd/` shows none, unlike forgejo's `patches/
+organization/orgDelete.json` exemplar) — every op's own declared `errors: [...]` array is just
+`[UnknownArgocdError]`. That looked, at first read, like the same gap Discord has. It is not:
+`core/protocol-rest.ts#decode` (lines ~320-370) checks the operation's own typed matchers first,
+then **unconditionally** falls back to `HTTP_STATUS_MAP[status]` — a 404 maps to `NotFound`
+regardless of whether the operation declared it. `UnknownArgocdError` is reached only for a status
+outside that map. **So `catchTag('NotFound', ...)` works correctly today, with no distilled patch
+needed** — confirmed by `repository.test.ts`/`repo-creds.test.ts`/`cluster.test.ts` running the
+REAL protocol against a fake 404/401/403, not a hand-rolled status check.
+
+## Secrets never in state
+
+Every secret-shaped field (`password`, `sshPrivateKey`, `bearerToken`, `tlsClientCertKey` /
+`tlsClientKeyData`) is a prop typed `FromEnv` (`{ fromEnv: 'ENV_VAR_NAME' }`,
+`../secrets/write-only.ts`) — never a literal value. `git-credentials.ts` (Repository/RepoCreds)
+and `cluster.ts`'s own resolver read the named variable from the deploying process's own
+environment **at call time**, refuse with a typed domain error
+(`ArgocdSecretEnvUnsetError`/`ArgocdClusterSecretEnvUnsetError`) if it is unset, and send the
+value on the wire — never into a prop, an attribute, or Alchemy's state store.
+
+⚠️ **No drift detection on secret fields, on purpose** — the same simplification
+`forgejo/org-actions-secrets.ts` makes: Argo CD's `Get`/`List` never returns a password, private
+key or bearer token back, so there is nothing to diff against. `matches` compares only the fields
+the API does return; a changed credential is written once on create and never rotated
+automatically. Rotate by destroy-then-create, or a manual call outside Alchemy. A seal-based check
+(`../secrets/write-only.ts#seal`, as `proxmox/pbs-notification-target-lifecycle.ts` uses) is
+possible later if this becomes a real problem.
+
+## Reconcile is one upsert call, always
+
+Every `Create*` operation this family calls takes `upsert: true` as a query parameter (measured:
+`CreateRepositoryServiceRepositoryRequest`, `CreateRepoCredsServiceRepositoryCredentialsRequest`,
+`CreateClusterServiceRequest`, all `.pipe(T.Query())`) — a true create-or-converge in one request.
+`resource.ts#reconcile` therefore has no separate `Update*` path: it reads, and calls `upsert`
+only when the declared props and the live object disagree on a plain field (S10 — converged means
+zero writes).
+
+## `exactOptionalPropertyTypes`, and `present()`
+
+The kit's `tsconfig.base.json` turns this on, and every generated Argo CD request type declares
+optional fields the strict way. `resource.ts#present()` strips undefined-valued keys into
+genuinely-absent keys before any create/upsert call — one shared helper instead of
+`forgejo/repository.ts#editForm`'s per-field conditional spread repeated three times.
+
+## Ownership: silent, like forgejo — not `Unowned` like discord/netbox
+
+No `adopt(true)`/`Unowned` wrapping. A live object found on a cold read (no persisted state) is
+treated as ours, mirroring `forgejo/resource.ts`'s own choice rather than `discord/resource.ts`'s
+`Unowned` marker. Documented, not accidental — the same tradeoff forgejo already ships with.

package/docs/credentials.md

@@ -65,3 +65,12 @@ this one variable. `Authorization: Bearer <value>` is still built by the package
 `GoogleWorkspaceKeyRef`/`describeKeyRef` (this subpath's own `credentials.ts`) are a typed,
 key-free REFERENCE to where that service-account key lives, for a stack file to keep alongside its
 declarations — full setup: [google-workspace.md](./google-workspace.md).
+
+The Argo CD subpath (new 2026-09-24, `@distilled.cloud/argocd`, built ahead of any live instance)
+resolves credentials the same way, through the SDK's own `CredentialsFromEnv` layer, which reads
+`ARGOCD_TOKEN` (required) and `ARGOCD_SERVER` (optional instance origin, default
+`https://localhost:8080`) — the package's own names, unchanged. `Authorization: Bearer <value>` is
+built by the package's protocol layer. The repository/cluster CREDENTIALS this subpath's three
+resources declare (a repo's password/SSH key, a cluster's bearer token/TLS key) are a separate,
+per-object concern from the instance's own API token above — write-only `FromEnv` references, never
+a prop or attribute either: see [argocd.md](./argocd.md#secrets-never-in-state).

package/docs/grafana-alerting.md

@@ -7,8 +7,9 @@ place). Ships in three stacked PRs, in the order this file's own history records
    PR 250.
 2. **`Grafana.AlertRuleGroup`** — [grafana-alerting-rules.md](./grafana-alerting-rules.md), a
    separate stacked PR (its own diff off `main`, not this one) once this file's doc budget filled.
-3. Next: `Grafana.NotificationPolicy` — the singleton policy tree, last on purpose (it references
-   contact points, mute timings and templates by name).
+3. **`Grafana.NotificationPolicy`** — [grafana-notification-policy.md](./grafana-notification-policy.md),
+   the singleton policy tree, last on purpose (it references contact points, mute timings and
+   templates by name).
 
 All three ship on the same `@distilled.cloud/grafana@0.2.0` operations
 [grafana.md](./grafana.md#the-sdk-gap--history-and-what-shipped-on-top-of-the-fix) already

package/docs/grafana-notification-policy.md

@@ -0,0 +1,127 @@
+# `Grafana.NotificationPolicy` — `@homeflare/alchemy/grafana`
+
+Third and last of the stacked PRs bringing Grafana alerting provisioning under Alchemy
+([grafana-alerting.md](./grafana-alerting.md): `Grafana.ContactPoint`/`Grafana.MuteTiming`/
+`Grafana.MessageTemplate`; [grafana-alerting-rules.md](./grafana-alerting-rules.md):
+`Grafana.AlertRuleGroup`). Branched fresh off `main` after that PR merged. No live call was made
+writing this PR.
+
+## A singleton — adopt and update only
+
+`GET`/`PUT /v1/provisioning/policies` always address the one tree an instance has; there is no path
+parameter. MEASURED: `RouteGetPolicyTreeError` is `Forbidden | GrafanaOpError` — no `NotFound` case
+at all, so `fetchLive` never returns `undefined`. `reconcile`'s `before === undefined` branch
+(`resource.ts`) is therefore dead code for this resource: there is no create in the sense every
+other resource in this family has, and `spec.create` exists only because `GrafanaSpec.create` is a
+required field on the shared type — implemented as the same `PUT` `update` sends, defensively,
+never actually reached.
+
+## Two gates before `routeResetPolicyTree` ever runs
+
+`destroy` never calls `routeResetPolicyTree` unless `allowReset: true` is explicitly declared — a
+gate independent of Alchemy's own removal policy:
+
+1. **`defaultRemovalPolicy: 'retain'`** — the same convention every multi-object-cascade resource
+   in this family uses (`Grafana.Folder`, `Grafana.AlertRuleGroup`, every `Bao.*`). Alchemy's own
+   engine never calls this resource's `delete` handler at all unless a stack opts in with
+   `.pipe(RemovalPolicy.destroy())`.
+2. **`allowReset` (a prop, not a stack-level policy)** — even a stack that HAS opted into destroy
+   at the Alchemy level still needs this resource's own explicit `allowReset: true` before
+   `destroy` will actually reset. Without it, `destroy` logs a warning and returns — retained.
+
+Two gates, not one, because `routeResetPolicyTree` is uniquely destructive among everything this
+family calls: it wipes every declared route, receiver reference and matcher back to Grafana's own
+bare default, for the WHOLE instance, not one object. A test
+(`notification-policy-refusals.test.ts`) proves `destroy` sends no `DELETE` without `allowReset`,
+and a foreign-provenance tree still refuses `destroy` even WITH `allowReset: true`.
+
+## The tree is opaque `Record<string, unknown>`
+
+Same reasoning as `mute-timing.ts`'s `timeIntervals`: Grafana's `Matchers`/`ObjectMatchers`/
+`MatchRegexps` (matcher expression shapes) are complex nested union/array types this family does
+not attempt to model field-by-field. This family's own measured passthrough behavior
+(`mute-timing.ts`'s file header) means an opaque pass-through round-trips correctly regardless.
+
+## Route order is significant
+
+Same as `Grafana.AlertRuleGroup`'s rules: `subset-match.ts`'s array comparison is
+position-significant, and Alertmanager itself routes an alert to the FIRST matching route in array
+order — reordering routes is a genuine routing change, proven by a test that declares the same two
+routes reversed and asserts a mismatch.
+
+## Foreign-provenance refusal
+
+Unchanged from kit PR 250/254, including the missing-means-foreign fix: `Route.provenance` is
+optional on the wire, and `undefined` is never folded into `""`. `create` is never at risk — it is
+unreachable (above).
+
+## Grafana-injected defaults — tolerated the `declaredContentMatches` way
+
+`matches()` runs the (`provenance`-stripped) declared and live trees through `subset-match.ts`'s
+tolerant-subset comparison — the same mechanism `Grafana.Dashboard`'s panel-`datasource`
+auto-decoration and `Grafana.ContactPoint`'s settings defaults already rely on: a live tree may
+carry additional fields, at any depth, the declaration never mentioned (a default
+`group_wait`/`group_interval`/`repeat_interval`/`group_by: []` Grafana injects when the declaration
+omits them is the plausible case) without failing the match. ⚠️ Not measured against a live
+instance — no live policy tree exists in this house to read — the documented, conservative default
+every unmeasured value shape in this family takes.
+
+## Dropped-route warning — accepted, never silent
+
+Same fix kit PR 254 made for `Grafana.AlertRuleGroup`, applied here: a whole-tree `PUT` REPLACES
+every route, so a nested route added out-of-band is removed with no error and no distinct `Diff`
+action to report it under. `notification-policy-drop-warning.ts`'s `warnOnDroppedRoutes` logs every
+dropped route by receiver and dotted-index path, called from both a local reimplementation of
+`diff` and from `update` itself — mirrors `alert-rule-group-drop-warning.ts` exactly, including
+being a LOCAL reimplementation of `resource.ts`'s generic `diff` rather than a wrap of it (no seam
+in the generic version for this side effect without fetching live twice).
+
+⚠️ **Identity is structural, not a stable key** — Grafana's policy routes have no id/uid.
+`FlatRoute.key` (`notification-policy-model.ts`) is the chain of ancestor own-fields from the root
+down to a node, `\0`-joined: two nodes are "the same" only under the identical lineage of parents,
+which makes an identical route under a DIFFERENT parent correctly distinct while staying
+order-insensitive among siblings (a shared parent contributes the same key to every child
+regardless of index) — reordering the same routes logs nothing, only genuine removal does.
+
+⛔ **Fixed after an adversarial review of this PR: the first version's identity collided across the
+WHOLE TREE, not just among siblings.** A plain `Set` of every node's own-fields JSON meant a
+duplicate route added anywhere (e.g. a second `severity=warning -> slack` alongside an
+already-declared one) matched the existing `Set` entry and went unwarned, even though the `PUT`
+still drops it — worse than the "siblings only" limitation the original comment claimed. Every key
+is now counted as a MULTISET (declared count vs. live count) rather than checked for membership: a
+key is "dropped" only for the amount its live count exceeds its declared count, so N identical live
+occurrences under the same parent are dropped only past however many the declaration itself
+repeats — proven by four tests: a duplicate added live warns; a plain sibling reorder doesn't; an
+identical route under a different, undeclared parent still warns (distinct lineage); and two
+declared duplicates against two live duplicates warns nothing (counts match).
+
+## Example
+
+```ts
+import { GrafanaNotificationPolicy, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class Policy extends GrafanaNotificationPolicy('estate-policy', {
+  route: {
+    receiver: 'default-receiver',
+    group_by: ['alertname'],
+    routes: [
+      { receiver: 'pagerduty', matchers: ['severity=critical'] },
+      { receiver: 'slack', matchers: ['severity=warning'] },
+    ],
+  },
+}) {}
+```
+
+## Tests
+
+`notification-policy.test.ts` (fetchLive/reconcile/order), `notification-policy-model.test.ts`
+(pure `normalizeRoute`/`flattenRoutes`), `notification-policy-refusals.test.ts` (provenance +
+reset-gate) and `notification-policy-drop-warning.test.ts` — split four ways to stay under the
+house's 250-line file cap, sharing fixtures from `notification-policy-fixtures.ts`. Prove: a GET
+never carries a body; reconcile never sends a create-shaped write; a foreign-provenance tree
+(explicit `"file"` or MISSING) refuses update while an explicit `""` is writable; `destroy` never
+resets without `allowReset: true`, and still refuses a foreign tree even with it; reordering routes
+shows `update`; a live route the declaration doesn't mention is named in a logged warning from both
+`diff` and `update`, while a plain reorder logs nothing; and — the multiset fix — a duplicate route
+added live warns while an identical declared/live duplicate pair doesn't, and an identical route
+under a different, undeclared parent is still correctly reported as dropped.

package/docs/grafana.md

@@ -122,15 +122,19 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 // …then provide `grafanaProviders({ baseUrl, tokenEnv })` alongside the stack's other providers.
 ```
 
+## Family status
+
+Every alerting-provisioning object this family set out to cover now ships:
+
+- **`Grafana.Folder` and `Grafana.Dashboard`** — see
+  [grafana-folder-dashboard.md](./grafana-folder-dashboard.md).
+- **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate`** — see
+  [grafana-alerting.md](./grafana-alerting.md).
+- **`Grafana.AlertRuleGroup`** — see [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+- **`Grafana.NotificationPolicy`** — the singleton policy tree, last on purpose (it references the
+  others by name) — see [grafana-notification-policy.md](./grafana-notification-policy.md).
+
 ## Not covered
 
-- **`Grafana.Folder` and `Grafana.Dashboard` ship** — see
-  [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
-- **`Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate` ship** — see
-  [grafana-alerting.md](./grafana-alerting.md), not repeated here.
-- **`Grafana.AlertRuleGroup` ships** — see [grafana-alerting-rules.md](./grafana-alerting-rules.md),
-  not repeated here.
-- **`Grafana.NotificationPolicy`** — the last stacked follow-up PR, the singleton policy tree, on
-  the same operations; not blocked on anything.
 - **`read` never answers `Unowned`** — the same open gap forgejo's and netbox's own families
   still carry (see upstream-conformance.md); a maintainer decision on the ownership-check shape.

package/docs/litellm.md

@@ -33,6 +33,23 @@ another `PROXY_ADMIN` key: `update_config_general_settings`, the function every
 through, is `PROXY_ADMIN` only. Never a prop — see [docs/credentials.md](./credentials.md) for the
 house rule.
 
+`CredentialsFromEnv` ends in `Effect.orDie` on a missing/misspelled env var — matching distilled's
+own convention (73 of 80 `packages/*/src/credentials.ts` end this way at `homeflare/base`, 78 of 80
+at `origin/main`), not the house's own S20/S24 numbering. A worktree commit briefly changed this to
+a typed `ConfigError` (`LitellmOpError` already declares one, and `makeRestProtocol`'s `encode` step
+does thread a real credentials failure into the operation's own error channel — the plumbing for a
+typed refusal is genuinely there); Tim's answer to Q6 (2026-09-24 walk-down, decision 49 "upstream
+wins") reverted it, because that divergence was the house going stricter than distilled's own
+convention on a point distilled is not silent on, and decision 49 says match exactly, not stricter.
+
+★ **HELD upstream proposal, not raised.** If distilled's own convention changes — typed
+`ConfigError` in place of `orDie` on a missing credential — this package (and the other 72) would
+be one line each to update: `Credentials`'s `Context.Service` value type gains `ConfigError`, and
+the layer drops its trailing `Effect.orDie` in favor of the `Effect.mapError` it already has to
+build the error. LiteLLM would make a reasonable pilot, since its protocol layer already declares
+and threads `ConfigError`. Nobody has proposed this to `alchemy-run/distilled`; it stays here as an
+idea for Tim to raise, or not, later.
+
 ## Refusals
 
 This resource refuses a plan rather than writing something it cannot safely undo:

package/docs/peers.md

@@ -78,3 +78,10 @@ upstream, the alias's target changes (or the entry becomes a normal peer, matchi
 `HttpClient` client the same way `/netbox` did) is the same shape**: aliased onto
 `@homeflare/distilled-litellm@0.2.0` as a plain `dependencies` entry, not a peer — nothing to
 add here, nothing for `peers.test.ts` to check.
+
+⚠️ **`@distilled.cloud/argocd` (added 2026-09-24, `/argocd`, built ahead of a Talos-on-PVE
+cluster that does not exist yet) is required for the same reason `@distilled.cloud/forgejo` and
+`/discord` are: a plain dependency of this package, not something a hoisting installer can hide
+from a strict one.** Pinned to `1.0.0-rc.12` — measured (`npm view @distilled.cloud/argocd`,
+2026-09-24) as genuinely published at that version, matching every other pin on this page; no
+interim alias was needed (see [distilled-interim.md](./distilled-interim.md) for when one is).

package/docs/unifi.md

@@ -91,3 +91,48 @@ trigger but a future write path must respect — whole-object `PUT`, ordering en
 replace the whole list, `removeDevice` unadopting and factory-resetting hardware — are recorded
 in the distilled package's own `README.md` and in the estate's `docs/unifi-api-notes.md`
 (outside this repo).
+
+## Spec-version check against the live-measured console (2026-09-24)
+
+`homeflare-network`'s `src/unifi/imported.ts` was generated 2026-09-24 against a live console
+self-reporting **10.6.97** (`GET /v1/info`, recorded in that file's own header) — two minor
+versions past this SDK's 10.4.57 pin. Checked whether any of the 11 imported networks or 14
+imported firewall zones could decode differently on a newer controller than this SDK's
+10.4.57-pinned types expect: diffed a 10.6.97 copy of Ubiquiti's OpenAPI document (a third-party
+mirror, used only as a diffing aid — never as this SDK's spec of record; see the distilled
+package's own `docs/spec-version-provenance.md`) against the pinned 10.4.57 document. Zero
+operations added or removed anywhere in the API; every full raw operation object (parameters,
+request body, responses, `$ref`s included) for every `Networks`-tagged operation and every
+`*FirewallZone*` operation is identical, byte for byte, not just its named schemas (11 operations
+on each side, same set — a named-schema diff alone would miss an inline, untagged parameter
+changing shape, so this checks the operations directly).
+
+**14 of the document's 379/380 component schemas do differ somewhere** — the switch-stack/LAG
+family (`Switching` tag, matching Ubiquiti's own 10.6 release notes on LAG support), the generic
+`filter`-query-syntax family (`FilterExpression`/`CompoundFilterExpression`/`NotFilterExpression`/
+`PropertyFilterExpression`), and one mDNS enum addition (`SHELLY`, `UniFi Devices` tag) — but
+**none of the 14 is reachable from a Networks or FirewallZone operation, even transitively**:
+resolved every `$ref` reachable from each of the 11 operations' full parameter/body/response
+trees, recursively, in both versions, and none of the 14 changed schema names appears in either
+closure. Full breakdown of the 14 (which changed vs. added/removed, and why the reachability check
+had to go beyond the direct operation-object diff above) is in the distilled package's own
+`docs/spec-version-provenance.md`, not this repo.
+
+**Answer: none of the imported rows would change shape against 10.6.97.** This does not
+generalize past 10.6.97, and it says nothing about any tag besides Networks/FirewallZones —
+re-check before importing or declaring against `Clients`, `WiFi Broadcasts`, `ACL Rules`, or any
+other tag.
+
+## 2026-09-24 doctrine walkdown
+
+Read directly against `origin/main`'s `src/unifi/{resource,network,network-form,firewall-zone,
+firewall-zone-form,policy}.ts`: `fetchLive` in `network.ts`/`firewall-zone.ts` folds only
+`catchTag('NotFound', …)`, never a blanket catch. `destroy` always refuses via the typed
+`UnifiWriteRefused` regardless of live state — correct here, not a departure from delete's usual
+idempotency rule: this family will never issue a real DELETE by policy, so idempotency of a
+delete it cannot perform is moot. No `Effect.orDie`/`Effect.die` anywhere in the family.
+`sortedSet` normalizes every measured unordered array (`dhcpGuarding.trustedDhcpServerIpAddresses`,
+`ipv6Configuration`'s two override lists, `firewall-zone-form.ts`'s `networkIds`) before it is
+attributed, declared or compared. Both declaration renderers and both `matches` use
+`value == null` / `deepEqual(..., { stripNullish: true })` consistently, per `network-form.ts`'s
+own header. No departure found — nothing in this family needed changing.

package/docs/upstream-conformance.md

@@ -289,7 +289,7 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
       timings or templates configured either (consistent with the alerting-provisioning gap having
       been real, not merely unexploited).
 
-    ✅ **`Grafana.AlertRuleGroup` shipped** (this PR, second of three, branched fresh off `main`
+    ✅ **`Grafana.AlertRuleGroup` shipped** (kit PR 254, second of three, branched fresh off `main`
     after PR 250 merged): group, not per-rule, is the unit — `PUT .../rule-groups/{Group}` owns
     evaluation `interval` and the full ordered `rules[]` together, which per-rule operations
     cannot express (no `interval` field, no reordering). Rule order is significant, proven by a
@@ -297,11 +297,25 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     the group type itself carries none) reuses `alerting-provenance.ts` unchanged, including the
     missing-means-foreign fix from PR 250's review. A declared group whose folder does not exist
     refuses as a typed `BadRequest` (`RoutePutAlertRuleGroupError` has no `NotFound` case) rather
-    than being auto-created — this resource never calls `Grafana.Folder`'s create path. Full
-    detail: [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+    than being auto-created — this resource never calls `Grafana.Folder`'s create path. A whole-group
+    write silently dropping a live rule not in the declaration (found by that PR's own adversarial
+    review) is now warned about loudly rather than silent, never a refusal. Full detail:
+    [grafana-alerting-rules.md](./grafana-alerting-rules.md).
 
-    **Still open, not this PR's scope:** `Grafana.NotificationPolicy` — the last stacked PR, the
-    singleton policy tree, no longer blocked on the SDK.
+    ✅ **`Grafana.NotificationPolicy` shipped** (this PR, third and last of the stacked PRs,
+    branched fresh off `main` after PR 254 merged): a SINGLETON — `fetchLive` never returns
+    `undefined` (`RouteGetPolicyTreeError` has no `NotFound` case), so this resource has no create
+    or delete in the sense every sibling resource does, only adopt-and-update. `destroy` never
+    calls `routeResetPolicyTree` without an explicit `allowReset: true` prop, a gate independent of
+    (and in addition to) `defaultRemovalPolicy: 'retain'` — two gates, since resetting wipes the
+    WHOLE instance's routing back to Grafana's bare default, not one object. The tree is opaque
+    `Record<string, unknown>` (same reasoning as `mute-timing.ts`'s `timeIntervals` — Grafana's
+    matcher-expression types are complex unions this family does not hand-model), compared via
+    `subset-match.ts` for Grafana-injected-default tolerance, with route order significant. The
+    same dropped-item warning kit PR 254 introduced for rule groups is mirrored here for dropped
+    routes. Full detail: [grafana-notification-policy.md](./grafana-notification-policy.md).
+
+    This completes the alerting-provisioning family this project set out to cover.
     - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
       (H1), and credentials come from an explicit env var NAME at call time rather than an
       `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the