@homeflare/alchemy 0.31.1 → 0.32.0

package/docs/grafana.md

@@ -8,32 +8,61 @@ publicly at `tesla.homeflare.dev/dash/`.
 
 ## The SDK gap — why only `Datasource` ships
 
+✅ **SDK-level gap fixed 2026-09-24** (`@distilled.cloud/grafana`, aliased onto
+`@homeflare/distilled-grafana` — 0.1.0 pre-release, 0.2.0 once its `minor` changeset publishes it;
+see [docs/distilled-interim.md](./distilled-interim.md)).
+The gap below is otherwise unchanged and left as evidence of what was measured and why; only its
+status line moved. **Still true today:** only `Grafana.Datasource` ships as a house _resource_ —
+`Grafana.Folder`, `Grafana.Dashboard`, `Grafana.AlertRule` and friends are follow-up work on top of
+the now-available SDK operations, not part of this fix.
+
 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
+`lib/services/grafana.d.ts`, 4,938 lines): the package had **no create/read/update/delete
+operations for folders, dashboards, alert rules or contact points**. It covered 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`,
+- **Folders:** only `updateFolderPermissions` existed. No `createFolder`, `getFolder` or
+  `deleteFolder` — Grafana's `/api/folders` and `/api/folders/{uid}` routes were entirely absent.
+- **Dashboards:** only snapshot and public-dashboard routes existed (`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.
+  `DELETE /api/dashboards/uid/{uid}` — the plain dashboard CRUD route family was absent.
 - **Alert rules:** only `routeGetAlertRuleExport`/`routeGetAlertRuleGroupExport`/
-  `routeGetAlertRulesExport` exist — export (read-only) endpoints under `/api/v1/provisioning/`.
+  `routeGetAlertRulesExport` existed — 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
+- **Contact points:** only `routeGetContactpointsExport` existed, same story — no
   `/api/v1/provisioning/contact-points{,/{uid}}` CRUD.
 
-This is recorded in [`docs/upstream-conformance.md`](./upstream-conformance.md) rather than worked
+**Root cause, measured (not the spec lacking the paths):** Grafana's own OpenAPI document has
+every one of the routes above — the converter dropped them. `skipDeprecated: true` (the distilled
+converter's v0 default) skips any operation the spec marks `deprecated: true`, and Grafana marks
+its entire classic folder/dashboard/alerting-provisioning WRITE surface deprecated, each
+operation's `description` pointing at a `/apis/<group>.grafana.app/v1/...` Kubernetes-apiserver
+route that is a separate API server with its own OpenAPI document — absent from this spec
+entirely, and not what this family's `Grafana.Datasource` (or any planned `Grafana.Folder`/
+`Grafana.Dashboard`/etc.) targets. The fix patches `deprecated` back to `false` on exactly the 32
+operations this gap named (leaving the other 32 deprecated operations — playlists, org/user
+preferences, datasources-by-name, licensing, reports, dashboard stars/tags/versions — excluded, as
+before): see the distilled clone's `packages/grafana/scripts/convert.ts` header and
+`patches/*.patch.json` for the exact list and reasoning, and
+`packages/distilled-grafana/README.md` in this kit for the copied result. `Grafana.Datasource`'s
+own operations (`addDataSource`/`getDataSourceByUID`/`updateDataSourceByUID`/
+`deleteDataSourceByUID`) were never deprecated and are untouched — same props, same attributes,
+same generated code, confirmed by diffing the distilled clone's regenerated output against its
+prior commit operation-by-operation.
+
+This was 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
+or patch them in per S22) — not a hand-rolled `HttpClient` client in this package for the missing
+pieces alone, which would put half a family through the SDK and half through a second, parallel
+client, exactly what S23 exists to prevent. It shipped as a kit interim package
+(`@homeflare/distilled-grafana`), the same S22 route `@homeflare/distilled-netbox` established,
+because `alchemy-run/distilled` is upstream and this house never pushes to it (decision 42) — see
+docs/distilled-interim.md.
+
+`teslamate-grafana` itself is consistent with this gap having been 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).
 
@@ -96,7 +125,8 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 
 ## 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.
+- **Folders, dashboards, alert rules, contact points, notification policies, mute timings.** The
+  SDK-level blocker is fixed (above); no house `Resource` calls these operations yet — follow-up
+  work, 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/opnsense.md

@@ -0,0 +1,146 @@
+# OPNsense — `@homeflare/alchemy/opnsense`
+
+Declares `Opnsense.Firewall.Alias`, `.Category` and `.Group` against
+`@distilled.cloud/opnsense` (aliased onto `@homeflare/distilled-opnsense@0.2.0` —
+[`distilled-interim.md`](./distilled-interim.md)). Built 2026-09-24. **READ-ONLY BY
+DESIGN** — see "The policy" below before reading anything else here. This is the
+estate's **edge firewall**: nothing in this family's code, or in building it,
+contacted the live box, and nothing about it may reconfigure one. (The vendor
+version pin below WAS confirmed against the live box once, read-only, during
+review — see "Vendor version" below; that probe used neither this family's
+code nor this SDK's generated client.)
+
+## Vendor version — measured 2026-09-24
+
+`@homeflare/distilled-opnsense`'s own README carries its generation pin:
+`opnsense/core`/`opnsense/plugins` tag `26.7.2`. That pin used to be an
+**inference** from a captured package list, never measured live (SSH to the
+edge is forbidden by house policy — a failed probe gets the caller's IP
+CrowdSec-banned). This PR's review measured it instead (Probe 14, 2026-09-24),
+live and read-only, over the HTTPS API only — no SSH:
+
+- `firmware-info` returned `200` with `product_version=26.7.2_2`.
+- `alias-search` returned `200` (keys: `current`, `rowCount`, `rows`, `total`).
+
+So the pin is now **measured**, not inferred: the live edge runs `26.7.2_2`,
+one patch ahead of the `26.7.2` tag the model/controller shape was generated
+from — the same series the "patch releases rarely change shape" reasoning
+already relied on, now confirmed rather than assumed. `alias-search`'s 200
+also confirms the live box's Firewall Alias API answers in the shape this SDK
+expects, even though this family reads through `get()`, not `search*` (below).
+
+## Resource set, and why these three
+
+The SDK covers 8 controllers / 83 operations (Firewall Alias/Category/Group/Filter,
+Routing Gateways, and the `os-frr` plugin's Quagga/BGP). This first import pass
+picks the three whose SDK module exports BOTH a `get()` (the whole model, keyed by
+uuid) and a `search<Item>` operation (a paginated list, OPNsense's own POST-shaped
+read) — genuine "list and get" configuration objects, not runtime state:
+
+- **Built**: `firewall_alias`, `firewall_category`, `firewall_group` (interface
+  groups, not permission groups).
+- **Skipped, and why**:
+  - `firewall_filter` (rules) and `routing_settings` (gateways) export `get()` but
+    no `search*` — no distinct list operation, so they miss this pass's own bar.
+    Rules are also the most consequential, highest-churn object in the model;
+    deferred to its own pass rather than folded in here.
+  - `quagga_general` is a global settings singleton, not a collection of items —
+    no uuid, nothing to adopt "by id".
+  - `quagga_bgp` mixes several item types (aspath, communitylist, neighbor,
+    peergroup, prefixlist, redistribution, routemap) with no `search*` for any of
+    them — deferred as a unit rather than picking one sub-type arbitrarily.
+  - `quagga_service` is pure runtime control (start/stop/restart/status) — the
+    task's own "not runtime state" exclusion, textbook case.
+
+## Why `get()`, never `getItem`/`searchItem`, for the three that shipped
+
+`get()` returns the WHOLE model tree in one GET —
+`{ alias: { aliases: { alias: { <uuid>: AliasItem, ... } } } }` for Alias, and the
+equivalent nesting for Category/Group (see each resource file's header for the
+exact path). Finding one item by uuid is then an object-key lookup, never an
+ambiguous request.
+
+That sidesteps two real gaps MEASURED in this early SDK, not a stylistic choice:
+
+1. **`firewall_alias` has no per-item get at all** — only `get` (whole model) and
+   `searchAlias` (paginated) exist.
+2. **`firewall_category`/`firewall_group` DO export `getCategory`/`getGroup`**,
+   but their generated request schema carries no `uuid` path parameter at all
+   (`GetCategoryRequest`/`GetGroupRequest` are both `S.Struct({})` against a `uri`
+   with no `{uuid}` placeholder) — a generation gap in this SDK, not a design
+   choice. Filed as an SDK gap below rather than worked around with a raw path.
+
+`searchAlias`/`searchCategory`/`searchGroup` were also passed over for `list()`
+building (they stay unused) because their generated request schema exposes no
+typed limit/offset/searchPhrase at all — a large object set could silently
+page-truncate through a naive use of them, where `get()` has no pagination to
+fall short of.
+
+## The policy: reconcile and delete always refuse
+
+Tim, 2026-09-24: UniFi and OPNsense are read-only for now. `policy.ts`'s
+`OpnsenseWriteRefused` is the ONLY error `reconcile`/`delete` can raise on any of
+the three resources — neither handler imports an `add`/`set`/`del`/`toggle`
+operation from the SDK. `reconcile` still observes with one `get()` first, so the
+refusal can say whether it would have created or updated; `delete` observes
+nothing and refuses unconditionally. `write-refusal.test.ts` proves it with a fake
+HTTP client that fails the test itself on any non-GET request, exercised through
+the exact `handlers` object each resource's `Provider` wraps — not a lower-level
+seam a real provider bypasses.
+
+Lifting this is a kit change (edit `policy.ts`, write the create/update/delete
+bodies these resources do not have), never a prop. There is no `allowWrite` flag.
+
+## Adopt is `adopt(true)`, not silent (S7, S8, H1)
+
+None of Alias, Category or Group carries an ownership marker OPNsense itself
+understands. Following upstream's `Snippet.ts` reference for a marker-less API
+(the same posture `../discord` documents, not NetBox's silent-adopt gap): a cold
+read (no persisted `output`) that finds a live object at the declared uuid
+returns `Unowned(attrs)`, so declaring it fails `OwnedBySomeoneElse` **unless**
+`adopt(true)` is set. Each resource's convenience constructor
+(`firewallAlias`/`firewallCategory`/`firewallGroup`) pipes `adopt(true)` on by
+default (H5).
+
+## The declaration renderer
+
+`aliasPropsFromLive`/`categoryPropsFromLive`/`groupPropsFromLive` (the barrel's
+names for each resource file's `propsFromLive`, itself the same function as
+`attributesOf` — see each `*-form.ts`'s header) are pure: given the uuid `get()`'s
+map key names and the item decoded at that key, they return exactly the props a
+declaration needs so `matches` reports noop against it. A future import script
+iterates `Object.entries(map)` from one `get()` call and calls the matching
+renderer once per row to generate an `alchemy.run.ts` row — no such script ships
+in this change.
+
+## Credentials
+
+`OPNSENSE_URL` / `OPNSENSE_API_KEY` / `OPNSENSE_API_SECRET`, read **at call time**
+via `@distilled.cloud/opnsense/Credentials`'s own `CredentialsFromEnv` (Basic
+auth, the vendor's own scheme), re-exported from `credentials.ts` rather than
+re-implemented. No OpenBao mint yet (H8's target is unreleased); a deploy process
+exports the three variables itself today. This package never reads, logs or
+mints them.
+
+The only key that exists today is a **ROOT API key** — not scoped to Firewall
+Alias/Category/Group, or to read-only. That is one more reason "The policy"
+above refuses every write unconditionally rather than trusting a props-level
+flag: any write path this key could reach would carry root's full blast
+radius on the estate's edge firewall, not just these three object types.
+
+## SDK gaps
+
+- 🔴 **`getCategory`/`getGroup`'s missing `uuid` path parameter** (above) — a
+  distilled generation gap, not exercised by this family, worth fixing upstream
+  in the distilled clone before a later pass tries to use either operation.
+- **No vendor constraint table**, unlike NetBox/Paperless — this pass did not
+  walk `vendor-schema` for OPNsense's field limits (e.g. `CategoryItem.color`'s
+  `/^[0-9a-fA-F]{6}$/` pattern); a malformed declaration would only be caught if
+  writes were ever lifted, not at plan time.
+- **`password`/`username`/`authtype`/`expire`** (the URL-fetch alias credential
+  fields) and **`path_expression`** (`urljson`-only) are left off `AliasProps`
+  entirely — S25 for the first four, narrow scope for the fifth. See
+  `alias-form.ts`'s header.
+- **No live lifecycle test** (H12): tests run against `fake-opnsense.ts`, a
+  loopback fake, not the real edge. This task had no credentials and was told
+  not to look for any.

package/docs/provider-standard.md

@@ -124,7 +124,7 @@ The files currently on the wrong side of the line are listed in
 | `caddy`             | Caddy 2.11.4                           | source comments only ⚠️           |
 | `forgejo`           | Forgejo 16.0.3                         | source comments only ⚠️           |
 | `talos`             | Talos v1.13 docs (never measured live) | source comments only ⚠️           |
-| `launchd` / `linux` | macOS 27 / systemd 257                 | source comments only ⚠️           |
+| `launchd` / `linux` | macOS 27 / systemd 257 / Podman 5.4.2  | source comments only ⚠️           |
 
 ⚠️ These rows record a version only in prose, so no test catches a drift. `schemas/manifest.json`
 also repeats the PVE, PBS and UniFi entries, which means there are two manifests for one

package/docs/quadlet-container.md

@@ -0,0 +1,132 @@
+# `Podman.Container` — `@homeflare/alchemy/linux`
+
+Status: active
+Verified: 2026-09-24
+
+One Podman [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
+`.container` file, declared, plus the systemd unit Podman's own generator
+turns it into — the container half of [linux-host.md](./linux-host.md)'s
+`Systemd.Unit` family, over the same `HostRunner` seam.
+
+★ **Why not `Docker.Container`.** Upstream Alchemy's resource was measured and
+rejected for three reasons: no host-network prop (every container CT100 runs
+uses `--network host`), `environment` puts `Redacted` secrets in Alchemy state,
+and systemd already supervises the containers this stack declares. Quadlet
+sidesteps all three: `Network=host` is a real value, `Environment=` is refused
+if it looks like a secret (below), and the GENERATED unit is what systemd
+supervises — this resource only ever declares the `.container` file that
+produces it.
+
+## Keys checked against the doc, not invented
+
+Every `[Container]` key below is checked against `podman-systemd.unit(5)`,
+**Podman 5.4** (`containers/podman` tag `v5.4.0`,
+`docs/source/markdown/podman-systemd.unit.5.md`, read 2026-09-24) — CT100 runs
+Podman 5.4.2 (`podman --version`, measured over `ssh ct100`, read-only,
+2026-09-24). `[Container]` is typed, unlike `Systemd.Unit`'s freeform
+`sections`, because Quadlet's own schema — unlike bare `systemd.unit(5)` — IS
+one vendor's documented, versioned surface. Adding a key later means checking
+it against the same doc and adding a field; there is no raw `[Container]`
+escape hatch, on purpose (see secrets, below).
+
+```ts
+PodmanContainer('grafana-primary', {
+  name: 'grafana-primary',
+  container: {
+    containerName: 'grafana-primary',
+    environmentFile: ['/etc/grafana-primary/env'],
+    image: 'docker.io/grafana/grafana:12.2.1',
+    network: 'host',
+    volume: ['grafana-primary-data:/var/lib/grafana'],
+  },
+  install: { wantedBy: ['multi-user.target'] },
+  service: { restart: 'always', restartSec: '5s' },
+});
+```
+
+Supported `[Container]` keys: `Image`, `ContainerName`, `Network` (supports
+`'host'`), `Volume` (repeatable), `EnvironmentFile` (repeatable), `Environment`
+(repeatable `KEY=VALUE`, never a secret), `PublishPort` (repeatable, refused
+together with `network: 'host'`), `Exec`, `User`, `AutoUpdate`
+(`'registry' | 'local'`), `PodmanArgs` (repeatable). `[Unit]`
+(`Description`/`Documentation` typed, everything else verbatim lines — same
+approach `Systemd.Unit` uses for the whole file, because these three sections
+stay systemd's own directive set even inside a `.container` file), `[Service]`
+(`Restart`/`RestartSec` typed, everything else verbatim), and `[Install]`
+(`WantedBy`/`RequiredBy`/`Alias` — the only three keys Quadlet honours for a
+`.container` file; NOT `Also`, which plain `systemd.unit(5)` allows).
+
+## Secrets: `EnvironmentFile=`, never `Environment=`
+
+⛔ **A secret belongs in a host path an out-of-band renderer maintains**
+(openbao-agent), named in `container.environmentFile` — never in
+`container.environment`, which is rendered into a 0644 file and stored
+unencrypted in Alchemy state, the same two reasons `Systemd.Unit`'s `content`
+is never secret.
+
+⚠️ **The refusal is best-effort, not a scanner** — `container-secrets.ts`. It
+refuses an `Environment=` key whose NAME says what it holds (`SECRET`,
+`TOKEN`, `PASSWORD`, `API_KEY`, …) and a handful of value shapes real vendor
+tokens take (`Bearer `, `ghp_`, `AKIA`, a JWT's `eyJ`, …). It cannot prove a
+value is safe, only refuse the obvious mistake — `container-secrets.test.ts`
+proves the refusal fires before any write, and that the renderer itself has no
+independent filter (validation is the only backstop, which is why every write
+path calls it first).
+
+## Lifecycle — where it differs from `Systemd.Unit`
+
+Order is **write, `daemon-reload`, VERIFY the generator, then start or restart
+the generated `<name>.service` only for a real change** — see
+`container-lifecycle.ts` and `container-generator.ts` for the full reasoning,
+each doc-cited. In brief:
+
+- ⛔ **The generated unit is never `systemctl enable`d.** MEASURED on CT100,
+  2026-09-24: `caddy.container` declares `[Install] WantedBy=multi-user.target`
+  and nothing ever ran `systemctl enable caddy`; `systemctl is-enabled
+caddy.service` prints `generated`, and
+  `/run/systemd/generator/multi-user.target.wants/caddy.service` is a symlink
+  the GENERATOR put there — doc-confirmed (`podman-systemd.unit(5)`): a
+  generated unit is transient, and `systemctl enable` "does not work" on one;
+  Quadlet applies `[Install]` itself, at every `daemon-reload`. So there is no
+  `enabled` prop: declaring `install.wantedBy` **is** the enablement.
+- ⛔ **A generator failure is a typed `QuadletGeneratorError`, never "absent".**
+  `systemd.generator(7)` (tag `v257`): `daemon-reload` deletes ALL generator
+  output and reruns every generator from the files on disk NOW. So a
+  `.container` file Quadlet refuses has no generated unit at all — even one
+  that generated fine a moment ago. An UPDATE that fails verification
+  therefore restores the LAST-KNOWN-GOOD file and reloads again, rather than
+  leaving the bad file for the next deploy to retry (`Systemd.Unit`'s own
+  choice, unit-lifecycle.ts): here "the next deploy" might be a reboot, and by
+  then the container this resource already promised running has no unit at
+  all. A CREATE that fails removes the file it wrote, same as `Systemd.Unit`.
+- ⚠️ **The one open question.** Whether an ALREADY-ACTIVE unit's `LoadState`
+  stays `loaded` through a failed regeneration (systemd need not
+  garbage-collect a referenced unit) was not measured — doing so needs writing
+  a broken file to a live host, which read-only access forbids. If it does,
+  `LoadState`/`SourcePath` alone would not catch a failed update to a
+  container that was already running; the restore-last-known-good step does
+  not depend on catching it, since it always leaves the host at a file known
+  to generate.
+- `SourcePath` (added to `systemctl.ts`'s `SHOW_PROPERTIES`, additive for
+  `Systemd.Unit`) ties the generated unit back to the `.container` file —
+  MEASURED on CT100: `SourcePath=/etc/containers/systemd/caddy.container`. A
+  mismatch means a same-named file earlier in Quadlet's search path is
+  generating the unit instead of ours — a takeover, not a success.
+- Directory allowlist is Quadlet's OWN rootful search path (doc, "Podman Unit
+  Search Path"): `/run/containers/systemd`, `/etc/containers/systemd`,
+  `/usr/share/containers/systemd` — CT100's `caddy.container` lives in the
+  middle one.
+- Adopt, restart-on-change, delete (stop, remove the file, reload — no
+  `disable`, since it was never enabled through systemctl) and the rename
+  (delete-first replace) contract are otherwise identical to `Systemd.Unit`'s
+  — see [linux-host.md](./linux-host.md).
+
+## The CT100 fixture
+
+`container-fixture.test.ts` renders the same directives as CT100's live
+`caddy.container` (read read-only over `ssh ct100`, 2026-09-24) and checks
+every line matches. Not byte-for-byte: CT100's file interleaves long prose
+comments between directives, and a typed `[Container]` has nowhere to attach
+"this comment goes between these two keys" — the same limit `Systemd.Unit`'s
+`renderUnit` has for the identical reason. The test proves directive parity;
+the file explains why byte parity is not the right bar for a typed resource.

package/docs/unifi.md

@@ -0,0 +1,93 @@
+# UniFi Network — `@homeflare/alchemy/unifi`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** `Unifi.Network` and `Unifi.FirewallZone` read and
+adopt; neither has a create, an update body or a working delete. `reconcile`/`delete` both fail
+with a typed `UnifiWriteRefused` naming the policy rather than calling any SDK write operation.
+Lifting the rule is a kit change — a PR that adds a write path, reviewed as one — not a flag a
+stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
+
+## What's declared, and why these two first
+
+`Unifi.Network` (`getNetworkDetails`/`getNetworksOverviewPage`) and `Unifi.FirewallZone`
+(`getFirewallZone`/`getFirewallZones`) — both list+get pairs over genuine, stable configuration,
+not runtime state (a connected client, a device statistic, a hotspot voucher, a switch stack).
+`Site` was the SDK README's other first suggestion; it has no `getSite`, only the list operation,
+so it fails this house's own "both a list and a get" bar for a first import. `FirewallPolicy` is
+also a list+get config object, but its `source`/`destination`/`ipProtocolScope` fields carry
+several of the vendor's converter-flattened discriminator variants each, and its ordering
+endpoint replaces the whole rule list — modelling that correctly is a bigger, separate PR.
+
+## Credentials
+
+Two environment variables, read **at call time**, never props — the SDK's own
+`CredentialsFromEnv` (`@distilled.cloud/unifi-network/Credentials`):
+
+| variable                     | holds                                               |
+| ---------------------------- | --------------------------------------------------- |
+| `UNIFI_NETWORK_API_KEY`      | an Integrations → API Key from the console's own UI |
+| `UNIFI_NETWORK_API_BASE_URL` | the console's integration API root — see below      |
+
+⛔ **Neither has a default**, and neither is ever logged, committed or persisted in state.
+
+⛔ **No console identifier, endpoint host or other live value ever appears in code, tests,
+fixtures, commits or a PR.** The base URL shape depends on how the console is reached: a cloud
+connector's is `https://api.ui.com/v1/connector/consoles/<consoleId>/proxy/network/integration`
+(`<consoleId>` is an account identifier); a local console is reached directly,
+`<endpoint>/proxy/network/integration`, where `<endpoint>` is a hostname behind a TLS certificate
+the caller trusts. Treat any UniFi base URL as sensitive; this package's tests use only the RFC
+2606 placeholder `https://unifi.example.com`.
+
+The estate's own credential lives in OpenBao at `kv/infra/unifi/api` — fields `api_key`,
+`connector_id`, `console`, `endpoint`, `site`, `transport` (`transport=local`: this console is
+reached directly, not through the cloud connector). A separate `kv/infra/unifi/site-manager`
+token is the _cloud_ Site Manager API credential, a different door (below) this family never
+reads.
+
+✅ **Auth was measured live, read-only, on 2026-09-24.** The OpenAPI document declares no
+`securitySchemes` at all — `X-API-KEY` comes from Ubiquiti's own Integration API guide, not the
+machine-readable spec (`@distilled.cloud/unifi-network/src/credentials.ts`'s own header) — but a
+hand-run, read-only probe confirmed it works against the estate's local console: `X-API-KEY`
+returns HTTP 200 on both `GET /v1/info` (key: `applicationVersion`) and `GET /v1/sites` (keys:
+`count`, `data`, `limit`, `offset`, `totalCount`). The _same_ key against the `api.ui.com` cloud
+connector returns 401 — the wrong door for a key minted on a local console, not evidence the
+cloud shape rejects `X-API-KEY` outright; `kv/infra/unifi/site-manager` is the separate cloud
+credential, untouched by this family. Only reads were probed, by hand, outside this package's own
+test suite — nothing in this PR's code exercises the vendor API live, and a write path would still
+need its own verification.
+
+## Adopt is the default posture, and it never writes
+
+`adopt(true)` is piped onto every resource by its convenience constructor (`network(...)`,
+`firewallZone(...)`) — H5. A cold read of a live match answers `Unowned(attrs)` (H1, the
+`Cloudflare/Snippets/Snippet.ts` reference every marker-less family here follows: UniFi Network
+objects carry no tag or metadata field this stack could stamp), and `adopt(true)` turns that into
+a silent bind instead of an `OwnedBySomeoneElse` refusal — the deploy never needs `--adopt`.
+
+⚠️ **A forced post-adoption reconcile still runs once (H6), and it still makes no write.**
+Beta.79 forces one `reconcile` call after every cold adoption whether or not `diff` said noop.
+`resource.ts`'s `reconcile` handles this the same way `discord/resource.ts` does: it reads the
+live object again and only refuses when it is missing (would need a create) or drifted (would
+need a write); an exact match returns the live attributes and calls nothing.
+
+## `list` answers `[]`
+
+`GET /v1/sites/{siteId}/networks` answers every network on the site. Adoption stays explicit —
+the same reasoning `Proxmox.User`'s and NetBox's own `list` give.
+
+## The declaration renderer
+
+`declareNetwork(live, siteId)` and `declareFirewallZone(live, siteId)` are pure functions: given
+one `getNetworkDetails`/`getFirewallZone` response, they return the `Props` a declaration needs
+so its plan is a no-op. A later import script reads every object on a site and writes one
+`network('<id>', declareNetwork(live, siteId))` row per result into `alchemy.run.ts` — nothing
+here performs that write; these two functions are what the script would call.
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57** (OpenAPI 3.1.0, 44 paths), via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.2.0`
+(`docs/distilled-interim.md`). Traps in the underlying API that this read-only family cannot
+trigger but a future write path must respect — whole-object `PUT`, ordering endpoints that
+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).

package/docs/upstream-conformance.md

@@ -249,10 +249,20 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     `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.
+    [grafana.md](./grafana.md#the-sdk-gap--why-only-datasource-ships).
+
+    ✅ **S22 fixed 2026-09-24** (branch `claude2/distilled-grafana`): root cause measured to be
+    `skipDeprecated: true` dropping 64 operations Grafana's own spec marks `deprecated: true` in
+    favor of a separate, undocumented-here Kubernetes-apiserver route — not a spec omission. RFC-6902
+    patches un-deprecate exactly the 32 operations this finding named (folders, dashboards,
+    alerting-provisioning writes); the other 32 stay excluded. Shipped as
+    `@homeflare/distilled-grafana` (0.1.0 pre-release, 0.2.0 once this PR's `minor` changeset
+    releases it), aliased onto `@distilled.cloud/grafana` the same S22 route
+    `@homeflare/distilled-netbox` established. `Grafana.Datasource`'s props/attributes/generated code
+    are unchanged (diffed operation-by-operation against the prior commit). **Still open, and not
+    this PR's scope:** no `Grafana.Folder`/`Dashboard`/`AlertRule`/`ContactPoint`/
+    `NotificationPolicy`/`MuteTiming` resource calls the newly-available operations yet — follow-up
+    PRs, no longer blocked on the SDK.
     - ⛔ **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.31.1",
+  "version": "0.32.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",
@@ -100,6 +100,14 @@
       "types": "./dist/discord/index.d.ts",
       "default": "./dist/discord/index.js"
     },
+    "./unifi": {
+      "types": "./dist/unifi/index.d.ts",
+      "default": "./dist/unifi/index.js"
+    },
+    "./opnsense": {
+      "types": "./dist/opnsense/index.d.ts",
+      "default": "./dist/opnsense/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -107,18 +115,20 @@
   },
   "dependencies": {
     "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.2",
+    "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@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-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.0",
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
     "@distilled.cloud/discord": "1.0.0-rc.12",
     "@distilled.cloud/forgejo": "1.0.0-rc.12",
     "@distilled.cloud/google-workspace": "1.0.0-rc.12",
-    "@distilled.cloud/grafana": "1.0.0-rc.12",
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/sql-pg": "4.0.0-rc.115",
     "alchemy": "2.0.0-beta.79",

package/src/grafana/index.ts

@@ -5,11 +5,12 @@
  *   the symbols a real stack consumes; the rest of the files (resource.ts's engine, fake-grafana.ts)
  *   are internals a provider needs but a consumer should not depend on.
  *
- * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana@1.0.0-rc.12` has no folder,
- *   dashboard, alert-rule or contact-point CRUD operations — see docs/grafana.md and
- *   docs/upstream-conformance.md for the measured gap. Adding those resources now would mean
- *   hand-rolling an `HttpClient` client for them, which S23 forbids for a vendor distilled
- *   already covers in part; the right fix is upstream, in distilled, not a house workaround here.
+ * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana` (aliased onto
+ *   `@homeflare/distilled-grafana` — see docs/distilled-interim.md) now HAS folder, dashboard and
+ *   alerting-provisioning CRUD operations — the SDK-level gap docs/grafana.md and
+ *   docs/upstream-conformance.md recorded is fixed. Building `Grafana.Folder`, `Grafana.Dashboard`,
+ *   `Grafana.AlertRule` etc. on top of them is follow-up work this PR deliberately does not do —
+ *   see docs/grafana.md for what changed and what is still open.
  */
 export {
   type DatasourceAttributes,