sync: managed NetBox sandbox + relationship coverage for demo tutorial

[lancamat1]

Problem

The NetBox→Infrahub tutorial (#140) and example config run against the public demo.netbox.dev. Two compounding problems make the "first sync" unreliable and misleading:

1. The public demo is volatile and dirty. It resets nightly and anyone can edit it. During review the IP-address count swung from 180 to 1 within a single day, it contained duplicate IPs (172.16.0.2/24 in VRF Alpha) that abort diff, and sites lacking the location hierarchy the schema expects. The happy path breaks on data we don't control.
2. Even when it loads, key relationships are absent — partly missing source data, partly mappings/adapter that can't express them. From a clean end-to-end run (25 sites, 48 devices, 1,119 interfaces, 90 prefixes, 180 IPs):
   • 0/1,119 interfaces have IPs; 0/180 IPs have an interface (IP↔interface not synced)
   • 0/48 devices have a primary IP (source has none — 0/73)
   • 0/29 circuits have terminations/connections
   • VLANs collapsed 24→4; 6/7 VLAN groups empty (schema human_friendly_id, tracked separately)

Net effect: the tutorial's "verify the imported data" step shows sites and devices but a topology with no IP/interface/circuit relationships — this undersells Infrahub and contradicts the tutorial's promise.

Proposed solution

A. A managed, immutable public NetBox sandbox (e.g. a netbox-chart Helm deployment) seeded from a version-controlled dataset that is (a) stable/read-only, (b) clean (no duplicate IPs, resolvable site hierarchy), and (c) deliberately exercises the showcased relationships: interface-assigned IPs, device primary IPs, circuit terminations, VLAN-group membership. The tutorial and example config target this instead of demo.netbox.dev.

B. Relationship mapping coverage so those relationships actually sync:

• IP↔interface via NetBox's polymorphic assigned_object (the config currently maps a non-existent interface.ip_addresses field → silent no-op)
• circuit terminations/cables (circuit→site/interface)
• interface untagged/tagged VLANs (re-enable after the VLAN human_friendly_id fix)

Several of these need adapter support for NetBox generic foreign keys (assigned_object, scope) — the config already punts on scope for the same reason.

C. Make silent collapses visible: warn/report when the created-object count does not match what persists (destination human_friendly_id coarser than the sync identifier), so losses like VLAN 24→4 aren't silent.

Alternatives considered

• Keep using demo.netbox.dev — rejected; volatile, dirty, uncontrolled; already the top source of tutorial breakage.
• Ship a static fixture/snapshot — fine for CI, but gives no browsable NetBox UI for the tutorial's token/source steps and doesn't exercise the live adapter.
• Just document the gaps — the existing "public demo data" warning manages expectations rather than fixing the experience.

Use case

A new user follows the getting-started tutorial end to end against the sandbox, syncs into a branch, and in "verify" sees a coherent slice of infrastructure — sites with racks/devices, interfaces with IPs, circuits with terminations, VLAN groups with VLANs — then opens a proposed change. Reproducible for every user, stable across infrahub-sync releases.

Additional context

• Tutorial PR: New Netbox to Infrahub data sync tutorial #140
• Schema-side fixes (VLAN/Rack/Device human_friendly_id, VRF→IP-namespace) are tracked separately on the schema-library repo.
• Ties into the in-flight self-hosted NetBox demo (netbox-chart) and the planned AI schema+mapping skill for per-user customizations (location hierarchy, roles) — this issue is the always-works baseline both build on.
• Evidence (clean run, 2026-07-13): interface→ip_addresses 0/1119, IP→interface 0/180, device primary_ip 0/48 (0/73 in source), circuit endpoints 0/29, IpamVLAN 24 created→4 persisted, 6/7 VLAN groups empty.