@homeflare/alchemy 0.36.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.36.0",
+  "version": "0.37.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",
@@ -28,6 +28,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./argocd": {
+      "types": "./dist/argocd/index.d.ts",
+      "default": "./dist/argocd/index.js"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare/index.d.ts",
       "default": "./dist/cloudflare/index.js"
@@ -120,11 +124,12 @@
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
-    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0",
-    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0",
+    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.0",
+    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.0",
     "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {
+    "@distilled.cloud/argocd": "1.0.0-rc.12",
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
     "@distilled.cloud/discord": "1.0.0-rc.12",
     "@distilled.cloud/forgejo": "1.0.0-rc.12",

package/src/argocd/cluster.test.ts

@@ -0,0 +1,120 @@
+/**
+ * `Argocd.Cluster`'s `spec` against a fake Argo CD — the same three doctrine-required shapes as
+ * `repository.test.ts`, plus the nested `config.tlsClientConfig` credential path.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeArgocd, fakeArgocdLayer, fakeFailure } from './fake-argocd.ts';
+import { argocdOperations } from './resource.ts';
+import { spec } from './cluster.ts';
+
+const SERVER = 'https://talos.example.com:6443';
+const ENV_VAR = 'ARGOCD_CLUSTER_TALOS_BEARER_TOKEN';
+
+const liveCluster = (overrides: Record<string, unknown> = {}) =>
+  Response.json({ name: 'talos', server: SERVER, ...overrides });
+
+describe('Argocd.Cluster spec.fetchLive', () => {
+  test('a live cluster decodes into attributes, including nested tls config', async () => {
+    const fake = fakeArgocd((method) =>
+      method === 'GET'
+        ? liveCluster({
+            config: { tlsClientConfig: { insecure: false, serverName: 'talos.internal' } },
+          })
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(live?.server).toBe(SERVER);
+    expect(live?.config?.tlsClientConfig?.serverName).toBe('talos.internal');
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'cluster not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 403 propagates — not folded to absent', async () => {
+    const fake = fakeArgocd(() => fakeFailure(403, 'forbidden'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('Argocd.Cluster destroy — idempotent (S11)', () => {
+  test('deleting an already-absent cluster makes no DELETE call', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'cluster not found'));
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ server: SERVER })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.every((call) => call.method !== 'DELETE')).toBe(true);
+  });
+
+  test('the DELETE call itself returning 404 (a race with an external removal) still succeeds', async () => {
+    // ⚠️ fetchLive's pre-check finds the cluster live, but something else deregisters it before
+    //   this call's own DELETE lands — matching upstream's Hetzner/Certificate.ts `deleteById`.
+    const fake = fakeArgocd((method) =>
+      method === 'GET' ? liveCluster() : fakeFailure(404, 'cluster not found'),
+    );
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ server: SERVER })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.filter((call) => call.method === 'DELETE')).toHaveLength(1);
+  });
+});
+
+describe('Argocd.Cluster spec.upsert — write-only bearer token', () => {
+  beforeEach(() => {
+    delete process.env[ENV_VAR];
+  });
+  afterEach(() => {
+    delete process.env[ENV_VAR];
+  });
+
+  test('refuses with a typed domain error when the declared env var is unset', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'unused'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec
+          .upsert({ credentials: { bearerToken: { fromEnv: ENV_VAR } }, server: SERVER })
+          .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('ArgocdClusterSecretEnvUnsetError');
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('resolves the bearer token into config, never the FromEnv reference itself', async () => {
+    process.env[ENV_VAR] = 'kube-bearer-abc123';
+    const fake = fakeArgocd((method) =>
+      method === 'POST' ? Response.json({ server: SERVER }) : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(
+      spec
+        .upsert({
+          credentials: { bearerToken: { fromEnv: ENV_VAR } },
+          namespaces: ['argocd', 'apps'],
+          server: SERVER,
+        })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    const [create] = fake.seen.filter((call) => call.method === 'POST');
+    expect(create?.path).toContain('upsert=true');
+    const body = create?.body as { config?: { bearerToken?: string }; namespaces?: string[] };
+    expect(body.config?.bearerToken).toBe('kube-bearer-abc123');
+    expect(body.namespaces).toEqual(['argocd', 'apps']);
+    expect(JSON.stringify(body)).not.toContain('fromEnv');
+  });
+});