@homeflare/alchemy 0.29.1 → 0.31.0

package/docs/google-workspace.md

@@ -0,0 +1,105 @@
+# Google Workspace — `@homeflare/alchemy/google-workspace`
+
+Four Admin SDK Directory objects: `Group`, `GroupMember`, `DomainAlias`, `OrgUnit`. Built on
+`@distilled.cloud/google-workspace@1.0.0-rc.12`'s `admin_directory_v1` service (S23) — every call
+is one of its typed operations, every error a `catchTag`.
+
+## Credential setup Tim needs
+
+⛔ **The distilled SDK takes one thing: an already-minted OAuth2 bearer access token.** Its
+`Credentials` service (`@distilled.cloud/google-workspace/Credentials`) has no service-account
+JSON shape and no domain-wide-delegation (DWD) JWT exchange — read at the installed package,
+2026-09-24: "API-compatible port of the distilled gcp credentials module … no ADC, no
+service-account signing, no refresh flow". Minting the token is entirely outside the SDK.
+
+★ **So this follows the house's existing pattern (H8), unchanged.** A Bun wrapper — the same
+shape the kit's Proxmox subpath already uses for its own OpenBao-sourced token — mints a
+short-lived token and exports it into the DEPLOY PROCESS's environment only:
+
+| variable              | holds                                                                |
+| --------------------- | -------------------------------------------------------------------- |
+| `GOOGLE_ACCESS_TOKEN` | a short-lived OAuth2 bearer token, delegated to a Workspace admin    |
+| `GOOGLE_PROJECT_ID`   | optional — only if a future resource needs to scope to a GCP project |
+
+This package does not write that wrapper. `credentials.ts` exports `GoogleWorkspaceKeyRef` — a
+typed REFERENCE (an OpenBao path, the delegated admin, the scopes) a stack file can keep next to
+its declarations for review, and `describeKeyRef()` to render it as one line of text. Neither
+holds, reads or accepts anything shaped like a key (`credentials.test.ts` asserts the refusal).
+
+### What Tim has to set up, once
+
+1. **A service account** in a Google Cloud project linked to the Workspace account, with
+   **domain-wide delegation** enabled in the Admin console (Security → API controls →
+   Domain-wide delegation) for the service account's client ID.
+2. **The least OAuth scopes the four resources need** — grant exactly these, nothing broader:
+
+   | resource               | scope                                                     |
+   | ---------------------- | --------------------------------------------------------- |
+   | `Group`, `GroupMember` | `https://www.googleapis.com/auth/admin.directory.group`   |
+   | `DomainAlias`          | `https://www.googleapis.com/auth/admin.directory.domain`  |
+   | `OrgUnit`              | `https://www.googleapis.com/auth/admin.directory.orgunit` |
+
+   `admin.directory.group` covers group **and** member CRUD — Google does not split them further
+   without also losing group create/update. A credential that only ever manages membership (never
+   creates or edits a group) can narrow to `admin.directory.group.member` instead.
+
+3. **The service account's key** goes in OpenBao, never on disk in this repo or anywhere a stack
+   file can reach: `kv/google-workspace/service-accounts/<name>`, matching the mount/catalog
+   pattern in `~/.claude/AGENTS.md`'s Cloudflare-credential section (same "mint, never reuse"
+   posture, different vendor).
+4. **The wrapper** reads that key from OpenBao, performs the DWD JWT-bearer exchange
+   (`https://oauth2.googleapis.com/token`, `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`,
+   `sub` = the delegated admin) for a token scoped to exactly the table above, and exports it as
+   `GOOGLE_ACCESS_TOKEN` before `alchemy.run.ts` runs — never printed, never logged, never written
+   to a file. This is the one piece this PR does not build; see
+   [upstream-conformance.md](./upstream-conformance.md) for why (S23: distilled owns the SDK
+   surface, the house owns minting, and the two should not be re-blended into a second hand-rolled
+   auth flow).
+
+### Read-only credential, for the census handoff
+
+The handoff script at `scratchpad/handoffs/23-workspace-census.sh` only lists — it never writes.
+Mint it a SEPARATE, narrower credential: `admin.directory.group.readonly`,
+`admin.directory.domain.readonly`, `admin.directory.orgunit.readonly`. Do not reuse the write
+credential above for a read-only script.
+
+## Adopt is the default posture
+
+`reconcile` fetches by key (email, alias name, or org unit path) before it writes — no NetBox-style
+list-then-disambiguate, because every object here has a stable key a human would type. An
+instance that already has "Schenanigans - Admin" or "Schenanigans - Google" (the groups the
+estate's Cloudflare Access policies already name — `docs/zero-trust-access-applications.md` in
+homeflare-landscape) is BOUND, never duplicated, and `attributes` always maps the FULL live row —
+the exact-as-live half of `adopt(true)`.
+
+## Users are out of scope
+
+`GoogleWorkspace.User` is not built. `insertUsers`/`patchUsers` accept a `password` field on the
+wire — one keystroke from becoming a prop, and Alchemy persists props unencrypted. No stack in
+this estate declares a Workspace user today (measured 2026-09-24). `GroupMember.email` references
+a user without ever creating, reading or storing one.
+
+## Removal is `retain` for everything but membership
+
+`Group`, `DomainAlias` and `OrgUnit` default to `retain` — each governs something else (Access
+policies, mail routing, service visibility) that outlives the declaration removing it.
+`GroupMember` does not: adding someone back to a group is cheap and reversible, so it uses the
+engine default (`destroy`).
+
+## SDK gaps, measured 2026-09-24
+
+- **`admin_directory_v1` lives under `unstable/`, not the SDK's preferred `services/` tree**
+  (`@distilled.cloud/google-workspace/unstable/admin_directory_v1`). The package's own `index.ts`
+  says "non-preferred versions" — this is the only Directory API version distilled generates, so
+  "non-preferred" describes distilled's own service catalog, not a deprecated Google API. Nothing
+  about the operations this family calls looked incomplete or wrong; flagged here per S23/S33 so a
+  future upgrade that moves it to `services/` is a one-line import change, not a surprise.
+- **No per-operation typed error beyond the shared `NotFound | Forbidden | BadRequest | Conflict`
+  set.** A cycle in group membership, an unverified domain on `insertDomainAliases`, or a
+  reparent-with-children refusal on `deleteOrgunits` all surface as `BadRequest` with a message,
+  not a resource-specific tag. S21 says a missing tag is fixed in the SDK, never worked around in
+  the resource — none of these three cases are worked around here; they propagate as `BadRequest`
+  same as any other 400.
+- **No `updateGroupsAliases`/`patchGroupsAliases`.** Group aliases are add/list/delete only,
+  matching `DomainAlias`'s own no-update shape — not modelled as a fifth resource in this PR
+  (out of scope: the task named domain aliases, not group aliases).

package/docs/grafana.md

@@ -0,0 +1,102 @@
+# Grafana — `@homeflare/alchemy/grafana`
+
+`Grafana.Datasource` declares one Grafana data source, keyed by `uid`. Every call goes through
+`@distilled.cloud/grafana@1.0.0-rc.12`'s typed operations, `catchTag('NotFound', ...)` in place of
+any status check. Built 2026-09-24 against the live target `teslamate-grafana.service` on CT100 —
+measured version **13.1.3** (`teslamate/grafana:4.2.0`), listening on `127.0.0.1:3100`, served
+publicly at `tesla.homeflare.dev/dash/`.
+
+## The SDK gap — why only `Datasource` ships
+
+Measured 2026-09-24 against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball (its
+`lib/services/grafana.d.ts`, 4,938 lines): the package has **no create/read/update/delete
+operations for folders, dashboards, alert rules or contact points**. It covers datasources in
+full (`addDataSource`, `getDataSourceByUID`, `updateDataSourceByUID`, `deleteDataSourceByUID`,
+`getDataSources`), plus org/user/team/role/report/annotation/library-element/public-dashboard/
+snapshot management — but:
+
+- **Folders:** only `updateFolderPermissions` exists. No `createFolder`, `getFolder` or
+  `deleteFolder` — Grafana's `/api/folders` and `/api/folders/{uid}` routes are entirely absent.
+- **Dashboards:** only snapshot and public-dashboard routes exist (`createDashboardSnapshot`,
+  `getPublicDashboard`, …). No `POST /api/dashboards/db`, no `GET /api/dashboards/uid/{uid}`, no
+  `DELETE /api/dashboards/uid/{uid}` — the plain dashboard CRUD route family is absent.
+- **Alert rules:** only `routeGetAlertRuleExport`/`routeGetAlertRuleGroupExport`/
+  `routeGetAlertRulesExport` exist — export (read-only) endpoints under `/api/v1/provisioning/`.
+  No create/update/delete for `/api/v1/provisioning/alert-rules{,/{uid}}`.
+- **Contact points:** only `routeGetContactpointsExport` exists, same story — no
+  `/api/v1/provisioning/contact-points{,/{uid}}` CRUD.
+
+This is recorded in [`docs/upstream-conformance.md`](./upstream-conformance.md) rather than worked
+around. Per S23, the fix is a distilled PR (regenerate against a spec that includes these routes,
+or patch them in per S22), not a hand-rolled `HttpClient` client in this package for the missing
+pieces alone — that would put half a family through the SDK and half through a second, parallel
+client, exactly what S23 exists to prevent.
+
+`teslamate-grafana` itself is consistent with this gap being real, not merely unexploited: its one
+datasource is API-manageable and already exists; its dashboards ship baked into the
+`teslamate/grafana` image and are provisioned by the container, not by any API call; it has no
+folders, alert rules or contact points configured at all (measured over ssh, read-only, 2026-09-24).
+
+## Credentials
+
+A `GrafanaTarget` — an instance origin plus a token env var NAME, never a literal value (S25):
+
+```ts
+import { grafanaProviders } from '@homeflare/alchemy/grafana';
+
+const teslamateGrafana = grafanaProviders({
+  baseUrl: 'https://tesla.homeflare.dev/dash',
+  tokenEnv: 'TESLAMATE_GRAFANA_TOKEN',
+});
+```
+
+`tokenEnv` is read fresh from `process.env` inside each operation's own effect (S24) — a layer
+built once still re-reads the environment on every request. This house wrapper exists because,
+unlike Forgejo (one instance for this estate), Grafana is not: `grafana.homeflare.dev` and
+`teslamate-grafana` are two instances with two different tokens, and the unit file for the latter
+says explicitly it uses "Own Access SaaS OIDC client, never grafana.homeflare.dev's" — one global
+`GRAFANA_TOKEN`/`GRAFANA_URL` pair (the SDK's own `CredentialsFromEnv`) cannot address both. A
+stack declaring resources against both instances calls `grafanaProviders` twice, once per target;
+the `Grafana.Datasource` resource type itself is one global registration shared by both calls.
+
+A datasource's `secureJsonData` (e.g. its password) follows the same rule: `secureJsonDataRefs`
+takes a map of field name to env var NAME, resolved the same way, never returned in `attributes` —
+Grafana's own read API agrees, since `DataSource.secureJsonFields` on a GET is a map of booleans
+(is-it-set), never the value.
+
+## Adopt semantics
+
+`reconcile` observes before it writes (S9/S10): a `uid` the target instance already has is bound,
+and when the declaration already matches what's live, nothing is sent — no create, no update.
+Declaring exactly what's live changes nothing. This is why `uid` is a **required** prop rather than
+generated: `getDataSourceByUID`/`updateDataSourceByUID`/`deleteDataSourceByUID` are all UID-keyed,
+and `getDataSources` (list) takes no filter, so locating an object this resource didn't create
+would mean listing the whole org and matching by name — the same ambiguity
+`netbox/resource.ts`'s `soleMatch` exists to catch. Requiring `uid` up front (Grafana accepts a
+caller-chosen one on create) sidesteps it: every operation keys on the one field the API itself is
+keyed on.
+
+## Example
+
+```ts
+import { GrafanaDatasource, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource', {
+  uid: '<the live uid — see the census handoff>',
+  name: 'TeslaMate',
+  type: 'postgres',
+  access: 'proxy',
+  isDefault: true,
+}) {}
+```
+
+```ts
+// …then provide `grafanaProviders({ baseUrl, tokenEnv })` alongside the stack's other providers.
+```
+
+## Not covered
+
+- **Folders, dashboards, alert rules, contact points.** Blocked on the SDK gap above — a
+  maintainer decision on whether to patch distilled or wait for upstream to add the routes.
+- **`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/peers.md

@@ -54,6 +54,15 @@ enforces it. `@effect/sql-pg` is optional on `alchemy`'s own manifest (its modul
 does not reach `SQL/Postgres` unless a stack imports it); here it stays a plain peer like
 every other one.
 
+⚠️ **`@distilled.cloud/grafana` (added 2026-09-24, kit PR 222, ahead of `/grafana`) is
+required for the same reason `@distilled.cloud/forgejo` is: a plain dependency of this
+package, not something a hoisting installer can hide from a strict one.** Pinned to
+`1.0.0-rc.12`, the same distilled release line as every other pin on this page. Unlike
+Forgejo, this family is credential-parameterized per instance (`grafanaCredentials`/
+`grafanaProviders` take a `GrafanaTarget`, not a fixed env-var pair) — see
+[grafana.md](./grafana.md) for why one instance was never going to be enough for this
+estate. The peer itself does not change for that: it is still one package, one pin.
+
 ★ **`@distilled.cloud/netbox` (added 2026-09-23, moving `/netbox` off a hand-rolled
 `HttpClient` client the same way `/forgejo` did) is NOT on this install line, and that is
 deliberate — see [distilled-interim.md](./distilled-interim.md).** The real

package/docs/upstream-conformance.md

@@ -224,6 +224,45 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     the house's glyph rationale into `//` comments.
 13. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
     fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
+14. **`discord/*` is new (2026-09-24, task-authorized, kit PR TBD) and built directly on
+    `@distilled.cloud/discord` — no hand-rolled `client.ts` ever existed to retire.**
+    `Discord.ApplicationCommand` and `Discord.GuildApplicationCommand` call the SDK's
+    typed operations, `catchTag`'d through the shared `DiscordOpError` union (S21), with no
+    status sniffing anywhere in `resource.ts`. It follows upstream's `Snippet.ts` reference
+    exactly for a marker-less API (S7, S8): a cold `read` returns `Unowned(attrs)`, and both
+    convenience constructors pipe `adopt(true)` (H5) — a stricter posture than `netbox/*`'s
+    documented H1 gap, not a repeat of it. Rate-limit handling is the SDK's own default
+    `Retry` policy (bounded: `Schedule.recurs(8)`, S26) — this family adds nothing on top.
+    Full detail, the live Halibut census and its ownership-handover sequence, and every SDK
+    gap: [`discord.md`](./discord.md). ⛔ **Diverges on S24/S25 the same way every distilled
+    family in this ledger does:** credentials are read at call time through the SDK's own
+    `CredentialsFromEnv`, not a house `alchemy/Auth` provider — unchanged from `netbox/*`
+    and `litellm/*`'s entries above. **Gap, not yet fixed:** no vendor constraint table
+    (unlike NetBox/Paperless); `options` passed through opaquely rather than modeled from
+    the schema (`docs/discord.md#sdk-gaps`).
+
+15. **`grafana/*` (added 2026-09-24) ships only `Datasource` — a real SDK gap, not scope-trimming.**
+    Measured against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball's
+    `lib/services/grafana.d.ts` (4,938 lines): the package has no create/read/update/delete
+    operations for folders (only `updateFolderPermissions` exists), plain dashboards (only
+    snapshot/public-dashboard routes exist — no `POST /dashboards/db`, no
+    `GET/DELETE /dashboards/uid/{uid}`), alert rules or contact points (both have only a
+    `routeGet*Export` read-only route under `/v1/provisioning/`, no create/update/delete). S1
+    found no upstream `Alchemy` family for any of these either. Full detail:
+    [grafana.md](./grafana.md#the-sdk-gap--why-only-datasource-ships). **Decision:** maintainer,
+    on whether the kit patches distilled (S22) or waits for upstream to add the routes — S23
+    forbids a hand-rolled `HttpClient` client for the missing pieces alone, half a family through
+    the SDK and half through a second client.
+    - ⛔ **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
+      SDK's `CredentialsFromEnv`, because more than one Grafana instance exists on this estate
+      (grafana.md's own Credentials section).
+    - Measured, read-only, on `teslamate-grafana.service` (CT100, `teslamate/grafana:4.2.0`,
+      Grafana 13.1.3): one datasource (file-provisioned, not API-managed — a live example this
+      family COULD adopt), dashboards baked into the image (not API-managed either way), and no
+      folders, alert rules or contact points configured — consistent with the gap being real
+      rather than merely unexploited. No stack yet imports `@homeflare/alchemy/grafana`.
 
 ## Conforms
 
@@ -263,6 +302,20 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
   an Output. That fix also belongs in the engine upstream.
 - **`verify/*`** (`hf-adopt-verify`) runs Alchemy's own planner. It exists because beta.79
   labels every cold adoption as an update (H6).
+- **`google-workspace/*`** (new 2026-09-24, `Group`, `GroupMember`, `DomainAlias`, `OrgUnit`)
+  is built directly on `@distilled.cloud/google-workspace@1.0.0-rc.12`'s typed
+  `unstable/admin_directory_v1` operations from the first commit — no hand-rolled client ever
+  existed for it to migrate off (S23), so there is no `client.ts` deletion to record. Every
+  `fetchLive` is get-by-key with its own `catchTag('NotFound', …)`, the same split forgejo's and
+  netbox's engines use (resource.ts). Get-by-key rather than NetBox's list-then-disambiguate,
+  since Directory addresses every object this family models by a stable key. ⛔ **Diverges on
+  credentials, same shape as the rest of this ledger (S24):** `GOOGLE_ACCESS_TOKEN` is read at
+  call time through the SDK's own `CredentialsFromEnv` — but here the SDK provides no way to
+  MINT that token at all (no service-account/DWD support), so a Bun wrapper outside this
+  package (H8, unwritten by this PR) is load-bearing in a way NetBox's/Forgejo's simple
+  API-token env vars are not. SDK gaps (the `unstable/` service tree, no per-operation error
+  beyond the shared 4xx set, no group-alias update) and the full credential/scope setup:
+  [google-workspace.md](./google-workspace.md).
 
 ## The Bun line
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.29.1",
+  "version": "0.31.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",
@@ -84,10 +84,22 @@
       "types": "./dist/litellm/index.d.ts",
       "default": "./dist/litellm/index.js"
     },
+    "./google-workspace": {
+      "types": "./dist/google-workspace/index.d.ts",
+      "default": "./dist/google-workspace/index.js"
+    },
+    "./grafana": {
+      "types": "./dist/grafana/index.d.ts",
+      "default": "./dist/grafana/index.js"
+    },
     "./verify": {
       "types": "./dist/verify/index.d.ts",
       "default": "./dist/verify/index.js"
     },
+    "./discord": {
+      "types": "./dist/discord/index.d.ts",
+      "default": "./dist/discord/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/caddy/config-format-warning.test.ts

@@ -0,0 +1,91 @@
+/**
+ * The "Caddyfile is not formatted" warning gets its OWN clear line, at both PLAN time
+ * (config-reconcile.ts's diffConfig) and DEPLOY time (config.ts's CaddyConfigProvider reconcile)
+ * — format-warnings.ts's split, wired into both. Captured with a Logger, the house pattern for
+ * asserting on `Effect.logWarning` (proxmox/lxc-harness.ts's `collect`).
+ *
+ * format-warnings.test.ts already covers the split itself in isolation; this file is the proof
+ * that plan and deploy actually call it, so a Caddyfile nobody ran through `caddy fmt` gets the
+ * fix line — not silence, and not just the adapter's own warning buried among others.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Logger from 'effect/Logger';
+import { caddyAdminLayer } from './admin.ts';
+import { CaddyConfig, CaddyConfigProvider } from './config.ts';
+import { diffConfig } from './config-reconcile.ts';
+import { type FakeCaddy, fakeDefaultCaddy } from './fake-caddy.ts';
+
+const SITE = 'app.example.com reverse_proxy 127.0.0.1:8080';
+const UNFORMATTED = `${SITE}\t`; // fake-caddy.ts: a TAB anywhere is its "not formatted" trigger
+const ids = { fqn: 'stack/caddy', id: 'caddy', instanceId: 'i-1' };
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+const setup = () => {
+  const made = fakeDefaultCaddy();
+  fake = made.caddy;
+  return made;
+};
+
+/** Runs `effect` and returns its result plus every `Effect.logWarning` line it emitted. */
+const withWarnings = async <A>(effect: Effect.Effect<A, unknown, never>) => {
+  const warnings: string[] = [];
+  const collect = Logger.make((options) => {
+    if (options.logLevel === 'Warn') warnings.push(String(options.message));
+  });
+  const value = await Effect.runPromise(effect.pipe(Effect.provide(Logger.layer([collect]))));
+  return { value, warnings };
+};
+
+describe('the formatting warning is surfaced distinctly', () => {
+  test('plan: diffConfig logs the fix line for an unformatted Caddyfile', async () => {
+    const { admin } = setup();
+    const output = { configSha256: 'stub', endpoint: admin.endpoint };
+    const { value, warnings } = await withWarnings(
+      diffConfig({ caddyfile: UNFORMATTED }, output).pipe(Effect.provide(caddyAdminLayer(admin))),
+    );
+    expect(value).toEqual({ action: 'update' });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('caddy fmt');
+    expect(warnings[0]).toContain(admin.endpoint);
+  });
+
+  test('plan: a formatted Caddyfile logs nothing', async () => {
+    const { admin } = setup();
+    const output = { configSha256: 'stub', endpoint: admin.endpoint };
+    const { warnings } = await withWarnings(
+      diffConfig({ caddyfile: SITE }, output).pipe(Effect.provide(caddyAdminLayer(admin))),
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  test('deploy: the real CaddyConfigProvider logs the fix line, not the raw adapter text', async () => {
+    const { admin } = setup();
+    const program = Effect.gen(function* () {
+      const provider = yield* CaddyConfig.Provider;
+      return yield* provider.reconcile({
+        ...ids,
+        bindings: [] as never,
+        news: { caddyfile: UNFORMATTED },
+        olds: undefined,
+        output: undefined as never,
+        session: undefined as never,
+      });
+    }).pipe(
+      Effect.provide(CaddyConfigProvider().pipe(Layer.provideMerge(caddyAdminLayer(admin)))),
+      // reconcile with no state needs an adopt decision; a fresh Caddy has nothing to adopt.
+      Effect.provideService(AdoptPolicy, true),
+    );
+    const { warnings } = await withWarnings(program as Effect.Effect<unknown, unknown, never>);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('caddy fmt');
+    expect(warnings.some((w) => w.includes('Caddyfile input is not formatted'))).toBe(false);
+  });
+});

package/src/caddy/config-reconcile.ts

@@ -14,6 +14,7 @@ import { messageOf, refuse, short, wrapOperation } from './config-errors.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 import { claimable, desiredConfig, readLive } from './config-lifecycle.ts';
 import { configDigest } from './digest.ts';
+import { formattingFixLine, splitFormattingWarning } from './format-warnings.ts';
 
 /**
  * ★ NEVER `replace`. Nothing in the props names a different object: a new Caddyfile is a reload of
@@ -27,6 +28,11 @@ export const diffConfig = (
   Effect.gen(function* () {
     const { endpoint } = yield* CaddyAdminService;
     const want = yield* desiredConfig(news);
+    // ★ SURFACED AT PLAN TIME, NOT JUST DEPLOY TIME. `want.warnings` otherwise goes nowhere here —
+    //   only the formatting warning gets its own clear line; the rest keep logging at reconcile
+    //   (config.ts), same as before this change.
+    const { formatting } = splitFormattingWarning(want.warnings);
+    if (formatting.length > 0) yield* Effect.logWarning(formattingFixLine(endpoint));
     const live = yield* readLive();
     const converged =
       want.digest === live.configSha256 &&

package/src/caddy/config.ts

@@ -35,6 +35,7 @@ import { isUnreachable } from './caddy-http-client.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 import { probeLive, readLive } from './config-lifecycle.ts';
 import { diffConfig, reconcileConfig } from './config-reconcile.ts';
+import { formattingFixLine, splitFormattingWarning } from './format-warnings.ts';
 
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 
@@ -136,7 +137,13 @@ export const CaddyConfigProvider = () =>
             const takeOver = sameCaddy || (yield* adoptEnabled(fqn));
             const stored = output === undefined ? {} : { stored: output.configSha256 };
             const applied = yield* reconcileConfig(news, { takeOver, ...stored });
-            for (const warning of applied.warnings) {
+            // ★ THE FORMATTING WARNING GETS ITS OWN LINE, NAMING THE FIX — separate from the rest,
+            //   which keep logging exactly as before (format-warnings.ts).
+            const { formatting, rest } = splitFormattingWarning(applied.warnings);
+            if (formatting.length > 0) {
+              yield* Effect.logWarning(formattingFixLine(admin.endpoint));
+            }
+            for (const warning of rest) {
               yield* Effect.logWarning(`Caddy.Config at ${admin.endpoint}: ${warning}`);
             }
             return applied.attributes;

package/src/caddy/format-warnings.test.ts

@@ -0,0 +1,50 @@
+/**
+ * splitFormattingWarning() / formattingFixLine() — pure, so no fake Caddy is needed: the
+ * behavior that matters is which warning(s) get pulled out and what the fix line says.
+ */
+import { describe, expect, test } from 'bun:test';
+import { formattingFixLine, splitFormattingWarning } from './format-warnings.ts';
+
+const FORMATTING = 'Caddyfile:1: Caddyfile input is not formatted';
+const OTHER = 'Caddyfile:3: unrecognized directive: reverse_proxyy';
+
+describe('splitFormattingWarning', () => {
+  test('pulls the formatting warning out, leaving the rest untouched', () => {
+    expect(splitFormattingWarning([OTHER, FORMATTING])).toEqual({
+      formatting: [FORMATTING],
+      rest: [OTHER],
+    });
+  });
+
+  test('formatting is empty, and rest unchanged, when there is no formatting warning', () => {
+    expect(splitFormattingWarning([OTHER])).toEqual({ formatting: [], rest: [OTHER] });
+  });
+
+  test('an empty list splits into no formatting warning and no rest', () => {
+    expect(splitFormattingWarning([])).toEqual({ formatting: [], rest: [] });
+  });
+
+  test('matches by substring, so a differing file:line still counts as the formatting warning', () => {
+    const elsewhere = '/etc/Caddyfile:42: Caddyfile input is not formatted';
+    expect(splitFormattingWarning([elsewhere])).toEqual({ formatting: [elsewhere], rest: [] });
+  });
+
+  test('TWO formatting warnings (e.g. an unformatted import) both survive — neither is dropped', () => {
+    // ⛔ Regression: a `.find()` here would keep only the first AND (via `.filter()`) strip the
+    //   second out of `rest` too — silently discarding it from both branches at once.
+    const second = '/etc/Caddyfile.d/site.caddy:1: Caddyfile input is not formatted';
+    expect(splitFormattingWarning([FORMATTING, OTHER, second])).toEqual({
+      formatting: [FORMATTING, second],
+      rest: [OTHER],
+    });
+  });
+});
+
+describe('formattingFixLine', () => {
+  test('names the endpoint and both fixes, never just the adapter’s own warning text', () => {
+    const line = formattingFixLine('http://127.0.0.1:2019');
+    expect(line).toContain('http://127.0.0.1:2019');
+    expect(line).toContain('caddy fmt');
+    expect(line).toContain('formatCaddyfile()');
+  });
+});

package/src/caddy/format-warnings.ts

@@ -0,0 +1,39 @@
+/**
+ * Pulls Caddy's adapter "Caddyfile input is not formatted" warning(s) out of a warnings list, so
+ * config.ts's reconcile (deploy) and config-reconcile.ts's diffConfig (plan) can show it as one
+ * clear, actionable line instead of burying it among the rest.
+ *
+ * ★ THIS IS THE COMMON CASE, NOT AN EDGE ONE. admin-calls.ts's module doc: the Caddyfile adapter
+ *   warns on EVERY unformatted input (adapter.go FormattingDifference) — every declared Caddyfile
+ *   that was not run through `caddy fmt` (or format.ts's formatCaddyfile()) carries this warning
+ *   on every plan and every deploy, indistinguishable from the rest unless split out.
+ */
+
+/** The exact adapter message (caddyserver/caddy v2.11.4, adapter.go FormattingDifference). */
+const NOT_FORMATTED = 'Caddyfile input is not formatted';
+
+export type SplitWarnings = {
+  /**
+   * Every warning THAT IS the formatting one — usually one, but an `import`ed file can add
+   * another with its own file:line, and this keeps every one of them (never just the first): a
+   * `.find()` here would silently drop the rest, not merely leave them uncounted.
+   */
+  readonly formatting: readonly string[];
+  /** Every other warning, in order, formatting removed. */
+  readonly rest: readonly string[];
+};
+
+/** Separates the formatting warning(s) (by substring, matching admin-calls.ts's `describe()`). */
+export const splitFormattingWarning = (warnings: readonly string[]): SplitWarnings => ({
+  formatting: warnings.filter((warning) => warning.includes(NOT_FORMATTED)),
+  rest: warnings.filter((warning) => !warning.includes(NOT_FORMATTED)),
+});
+
+/**
+ * One clear line naming the fix — never just the adapter's own warning text, and never repeated
+ * per formatting warning: however many `formatting` holds, this is logged once (config.ts,
+ * config-reconcile.ts), since restating the same fix N times is its own noise.
+ */
+export const formattingFixLine = (endpoint: string): string =>
+  `Caddy.Config at ${endpoint}: Caddyfile is not formatted — run \`caddy fmt\` on it, or format ` +
+  "it with this package's formatCaddyfile() before declaring it, to silence this warning.";