# Changelog 2026-07-09 -- OpenTofu module audit pass (DOCFIX-148)

No live infrastructure touched -- documentation/comment corrections only,
plus confirmatory research. Operator asked to pull documentation for
anything drafted without it and review all 9 modules built this session for
errors/assumptions, after DOCFIX-142/144/145/146/147 had already shipped.

## Item

### 1. DOCFIX-148 -- audited every flagged UNVERIFIED/inferred/assumed note
FILES: `opentofu/modules/opnsense-edge/{main,variables}.tf`,
`opentofu/modules/node-vm/main.tf`, `opentofu/modules/maas-vm-host/variables.tf`,
`scripts/opnsense-build-config-iso.sh`, `opentofu/README.md`.

METHOD: grepped the entire `opentofu/` tree for every "UNVERIFIED"/"NOT
confirmed"/"inference"/"assumed"/"not independently" marker left by prior
deliveries, then researched each one further (libvirt's own official XML
docs, a second independent source on the provider's volume-fetch mechanism,
FreeBSD/OPNsense interface-naming documentation, `genisoimage` reference
docs, MAAS provider zone/pool behavior) rather than re-stating the same
hedge unchanged.

**One genuine error found and fixed**, not just a hedge re-confirmed:
`opnsense-edge`'s comments claimed `devices.interfaces` list order
("index 0 = LAN") directly determines OPNsense's LAN/WAN role. Researching
FreeBSD/OPNsense's interface-assignment model showed this conflates two
separate things: list order plausibly controls which `vtnetN` device number
a NIC gets (libvirt's own PCI-addressing docs: auto-assigned addresses
"usually match" XML order for a simple topology), but OPNsense's actual
LAN/WAN designation is a SEPARATE, explicit mapping set inside `config.xml`
itself (or the interactive/API assignment step) -- "`vtnet0` = WAN" is a
convention some guides choose, not an enforced rule. `main.tf`'s comments
and both `lan_network_name`/`wan_network_name` variable descriptions
rewritten to state this correctly: the variables express intent for which
network should end up as which role, but whoever writes the still-undesigned
`config.xml` must independently confirm the real vtnetN<->network mapping on
a boot and set `<wan>`/`<lan>` accordingly. No `config.xml` has been written
yet in this repo, so this corrects documentation accuracy for a future
author, not current runtime behavior.

**Confidence upgraded (not resolved outright) on three other items:**
- `node-vm`'s `boot = { order = N }` shape: confirmed the provider
  code-generates its schema as a 1:1 mirror of libvirt's own domain XML
  (an architectural fact not visible in the resource doc pages alone), and
  confirmed libvirt's own docs show the native element is exactly
  `<boot order='N'/>` -- consistent with the established single-attribute
  mapping pattern already seen elsewhere in this schema. Still recommend a
  real `tofu providers schema -json` check before trusting it, but this is
  reasoned support now, not a bare guess.
- `create.content.url` accepting local filesystem paths: corroborated by a
  second, independent source describing the underlying fetch mechanism as
  supporting local paths alongside remote URLs.
- `genisoimage`/`xorriso` invocation flags (`-V`/`-J`/`-R`): confirmed as
  standard, correct usage for a plain cross-platform ISO9660 image --
  separated cleanly from the genuinely still-open question (whether
  OPNsense's Importer actually reads the result on a real boot), which
  remains unverified.

**Confirmed safe, previously assumed:** `maas_vm_host`'s `zone`/`pool` being
computed by MAAS when left unset -- validates the `default = null` design
choice in `modules/maas-vm-host` as a supported no-op.

**Deliberately NOT re-researched:** findings already backed by a primary,
authoritative source on the first pass (the OPNsense Configuration Importer
mechanism itself, the `maas_vm_host` vs. `maas_vm_host_machine` distinction,
the provider's attribute-vs-block syntax fix) -- re-verifying already-solid
findings on every audit would be its own kind of waste; the audit targeted
specifically the notes marked as gaps.

`opentofu/README.md` gained a new "Audit pass (2026-07-09)" section
documenting all of the above with reasoning, positioned as its own dated
entry alongside the existing OPNsense and MAAS/netem research sections
rather than silently editing history.

### 2. Documentation references added to the `openstack-cloud-ops` skill
FILE (new): `.claude/skills/openstack-cloud-ops/references/opentofu-provider-docs.md`.
FILES (modified): `.claude/skills/openstack-cloud-ops/SKILL.md` (new routing
entry), `opentofu/README.md` (cross-reference back to the skill file).

WHAT: operator asked for documentation links/access to be added to the skill
so future sessions can reference the direct sources rather than
rediscovering them. The new file indexes every provider/doc source used
building `opentofu/` (dmacvicar/libvirt, canonical/maas, OpenTofu's own
`local-exec`/`terraform_data` docs, OPNsense's docs/forum/GitHub issues) with
their exact URLs, confirmed versions, and default branches -- plus, more
valuably than the links alone, the FETCH METHODOLOGY that actually worked
this session: the Registry's own doc pages are JS-rendered and return empty
shells on a plain fetch (go to the provider's GitHub repo instead); GitHub
raw-file branch names vary and should be checked via the API's
`default_branch` field, not assumed; a general web search's own summary can
itself be wrong (encountered once); asking for "bare field names only" gets
past copyright-caution refusals that "reproduce this page" trips; real
example `.tf` files are consistently more reliable than doc-summarized prose
for syntax questions (the root cause of the DOCFIX-142 syntax bug this
whole delivery arc has referenced).

Deliberately does NOT duplicate the per-module findings themselves
(schema notes, what's confirmed vs. assumed per attribute) -- that stays in
`opentofu/README.md` as the single source of truth, cross-referenced from
both directions, so it can't drift into two disagreeing copies.

REVERT: `git rm .claude/skills/openstack-cloud-ops/references/opentofu-provider-docs.md`;
revert the two cross-reference edits if reverting fully.

REVERT: `git checkout HEAD~ -- opentofu/modules/opnsense-edge opentofu/modules/node-vm/main.tf opentofu/modules/maas-vm-host/variables.tf scripts/opnsense-build-config-iso.sh opentofu/README.md`
(re-arms the LAN/WAN documentation error -- not recommended).
