docs: regenerate stale reference pages and add optional use case metadata

.gitignore

@@ -7,3 +7,4 @@ __pycache__
 # uv
 .venv/
 .python-version
+.claude/settings.local.json

docs/_templates/schema_reference.j2

@@ -77,6 +77,24 @@ title: {{ schema.name }}
 {% if schema.attribution -%}
 - **Attribution:** {{ schema.attribution }}
 {% endif %}
+{% if schema.use_cases or schema.not_covered %}
+
+## Use cases
+{% if schema.use_cases %}
+
+This extension covers:
+{% for item in schema.use_cases %}
+- {{ item }}
+{% endfor -%}
+{% endif -%}
+{% if schema.not_covered %}
+
+Out of scope, and what to reach for instead:
+{% for item in schema.not_covered %}
+- {{ item }}
+{% endfor -%}
+{% endif -%}
+{% endif %}
 {% if schema.nodes %}
 
 ## Nodes

docs/docs/reference/cluster.mdx

@@ -119,17 +119,17 @@ generics:
     label: Nodes
     kind: Component
     cardinality: many
-    identifier: worker_in_cluster
     optional: true
+    identifier: worker_in_cluster
     order_weight: 1500
 extensions:
   nodes:
   - kind: ComputeGenericUnit
     relationships:
     - name: worker_in_cluster
       peer: ClusterGenericComputeUnitNodes
-      kind: Generic
       label: Worker in cluster
+      kind: Generic
       cardinality: one
       optional: true
       identifier: worker_in_cluster

docs/docs/reference/compute.mdx

@@ -130,8 +130,8 @@ nodes:
   description: A virtual machine hosted on a server or a cluster.
   label: Virtual Machine
   icon: carbon:virtual-machine
-  menu_placement: ComputeGenericUnit
   include_in_menu: true
+  menu_placement: ComputeGenericUnit
   inherit_from:
   - ComputeGenericUnit
   - DcimGenericDevice

docs/docs/reference/dcim.mdx

@@ -287,8 +287,8 @@ generics:
   - name: name
     kind: Text
     unique: true
-    allow_override: any
     optional: false
+    allow_override: any
     order_weight: 1000
   - name: position
     kind: Number
@@ -598,8 +598,8 @@ nodes:
     peer: OrganizationManufacturer
     kind: Attribute
     cardinality: one
-    identifier: manufacturer__platform
     optional: true
+    identifier: manufacturer__platform
     order_weight: 1300
 - name: Device
   namespace: Dcim
@@ -693,8 +693,8 @@ nodes:
     peer: InterfaceHasSubInterface
     kind: Attribute
     cardinality: one
-    identifier: sub__interface
     optional: true
+    identifier: sub__interface
     description: Parent interface to which this sub-interface belongs
     order_weight: 1600
 

docs/docs/reference/device_module.mdx

@@ -153,13 +153,13 @@ generics:
     kind: Text
     unique: true
     read_only: true
-    optional: false
-    allow_override: any
     computed_attribute:
       kind: Jinja2
       jinja2_template: '{{ module_bay__computed_name__value }}'
+    optional: false
     description: Name computed from the module bay; concrete module kinds may refine
       it.
+    allow_override: any
     order_weight: 1000
   - name: serial_number
     kind: Text
@@ -285,9 +285,9 @@ nodes:
     order_weight: 1000
   - name: position
     kind: Number
-    optional: true
     parameters:
       min_value: 1
+    optional: true
     description: Numeric position of the bay within the device (e.g. slot 1, 2, 3).
     order_weight: 1050
   - name: description
@@ -296,10 +296,6 @@ nodes:
     order_weight: 1100
   - name: role
     kind: Dropdown
-    optional: true
-    description: The role of the module bay, indicating the type of module it is intended
-      to receive.
-    order_weight: 1300
     choices:
     - name: supervisor
       label: Supervisor
@@ -317,6 +313,10 @@ nodes:
       label: Fan
       description: Bay intended for a fan module.
       color: '#D2B4DE'
+    optional: true
+    description: The role of the module bay, indicating the type of module it is intended
+      to receive.
+    order_weight: 1300
   relationships:
   - name: device
     peer: DcimPhysicalDevice

docs/docs/reference/ipam.mdx

@@ -89,14 +89,14 @@ version: '1.0'
 generics:
 - name: VLANGroupScope
   namespace: Ipam
-  label: VLAN Group Scope
   description: Mixin for objects that can scope a VLAN group (e.g. Region, Site).
     The reverse relationship is added by extensions/vlan.
+  label: VLAN Group Scope
   include_in_menu: false
 - name: PrefixScope
   namespace: Ipam
-  label: Prefix Scope
   description: Mixin for objects that can scope IP prefixes (e.g. Region, Site).
+  label: Prefix Scope
   include_in_menu: false
   relationships:
   - name: prefixes

docs/docs/reference/lag.mdx

@@ -95,8 +95,8 @@ generics:
     label: Member(s)
     kind: Attribute
     cardinality: many
-    identifier: interface__bundle
     optional: true
+    identifier: interface__bundle
     description: Physical Interfaces that are members of this aggregate
     order_weight: 1800
 nodes:
@@ -149,9 +149,9 @@ nodes:
     label: Member(s)
     kind: Attribute
     cardinality: many
+    optional: true
     identifier: interface__bundle
     common_parent: device
-    optional: true
     description: Physical Interfaces that are members of this aggregate
     order_weight: 1800
 extensions:

docs/docs/reference/peering_ixp.mdx

@@ -254,17 +254,17 @@ nodes:
     label: IPv6 Address
     kind: Attribute
     cardinality: one
-    identifier: ixpconn__ipv6_address
     optional: true
+    identifier: ixpconn__ipv6_address
     description: IPv6 address assigned to the connection
     order_weight: 1400
   - name: ipv4_address
     peer: IpamIPAddress
     label: IPv4 Address
     kind: Attribute
     cardinality: one
-    identifier: ixpconn__ipv4_address
     optional: true
+    identifier: ixpconn__ipv4_address
     description: IPv4 address assigned to the connection
     order_weight: 1375
   - name: internet_exchange_point
@@ -288,8 +288,8 @@ nodes:
     kind: Component
     cardinality: many
     optional: true
-    on_delete: no-action
     identifier: ixpconn__bgpsessions
+    on_delete: no-action
     description: BGP sessions established over this IXP connection
     order_weight: 1550
   - name: tags

docs/docs/reference/physical_disk.mdx

@@ -73,8 +73,8 @@ generics:
   - name: name
     kind: Text
     unique: true
-    allow_override: any
     optional: false
+    allow_override: any
     order_weight: 1000
   relationships:
   - name: physical_disks

docs/docs/reference/routing_policies_bgp.mdx

@@ -91,17 +91,17 @@ extensions:
       label: Import Routing Policies
       kind: Generic
       cardinality: many
-      identifier: bgppeergroup__import_policies
       optional: true
+      identifier: bgppeergroup__import_policies
       description: The routing-policies used by this instance for import.
       order_weight: 1750
     - name: export_routing_policies
       peer: RoutingPolicyBGP
       label: Export Routing Policies
       kind: Generic
       cardinality: many
-      identifier: bgppeergroup__export_policies
       optional: true
+      identifier: bgppeergroup__export_policies
       description: The routing-policies used by this instance for export.
       order_weight: 1800
   - kind: RoutingBGPSession
@@ -118,17 +118,17 @@ extensions:
       label: Import Routing Policies
       kind: Generic
       cardinality: many
-      identifier: bgpsession__import_policies
       optional: true
+      identifier: bgpsession__import_policies
       description: The routing-policies used by this instance for import.
       order_weight: 1850
     - name: export_routing_policies
       peer: RoutingPolicyBGP
       label: Export Routing Policies
       kind: Generic
       cardinality: many
-      identifier: bgpsession__export_policies
       optional: true
+      identifier: bgpsession__export_policies
       description: The routing-policies used by this instance for export.
       order_weight: 1900
 

docs/docs/reference/routing_policies_ospf.mdx

@@ -75,17 +75,17 @@ extensions:
       label: Import Routing Policies
       kind: Generic
       cardinality: many
-      identifier: ospf__import_policies
       optional: true
+      identifier: ospf__import_policies
       description: The routing-policies used by this instance for import.
       order_weight: 1600
     - name: export_routing_policies
       peer: RoutingPolicyOSPF
       label: Export Routing Policies
       kind: Generic
       cardinality: many
-      identifier: ospf__export_policies
       optional: true
+      identifier: ospf__export_policies
       description: The routing-policies used by this instance for export.
       order_weight: 1650
 

docs/docs/reference/routing_policies_pim.mdx

@@ -75,17 +75,17 @@ extensions:
       label: Import Routing Policies
       kind: Generic
       cardinality: many
-      identifier: pim__import_policies
       optional: true
+      identifier: pim__import_policies
       description: The routing-policies used by this instance for import.
       order_weight: 1500
     - name: export_routing_policies
       peer: RoutingPolicyPIM
       label: Export Routing Policies
       kind: Generic
       cardinality: many
-      identifier: pim__export_policies
       optional: true
+      identifier: pim__export_policies
       description: The routing-policies used by this instance for export.
       order_weight: 1550
 

docs/docs/reference/security.mdx

@@ -50,7 +50,7 @@ This schema extension contains models for implementing detailed security.
 
 | name | peer | optional | cardinality | kind |
 | ---- | ---- | -------- | ----------- | ---- |
-| ip_address | InfraIPAddress | False | one | Attribute |
+| ip_address | IpamIPAddress | False | one | Attribute |
 
 ### IPAMIPPrefix
 
@@ -71,7 +71,7 @@ This schema extension contains models for implementing detailed security.
 
 | name | peer | optional | cardinality | kind |
 | ---- | ---- | -------- | ----------- | ---- |
-| ip_prefix | InfraPrefix | False | one | Attribute |
+| ip_prefix | IpamPrefix | False | one | Attribute |
 
 ### IPAddress
 
@@ -272,7 +272,7 @@ This schema extension contains models for implementing detailed security.
 - **Namespace:** Security
 - **Icon:** mdi:firewall
 - **Human Friendly ID:** name__value
-- **Inherit From:** InfraGenericDevice, CoreArtifactTarget, SecurityPolicyAssignment
+- **Inherit From:** DcimGenericDevice, DcimPhysicalDevice, CoreArtifactTarget, SecurityPolicyAssignment
 
 #### Attributes
 
@@ -322,13 +322,13 @@ This schema extension contains models for implementing detailed security.
 - **Label:** Firewall Interface
 - **Namespace:** Security
 - **Icon:** mdi:ethernet
-- **Inherit From:** InfraInterface, InfraEndpoint
+- **Inherit From:** DcimInterface, DcimEndpoint
 
 #### Relationships
 
 | name | peer | optional | cardinality | kind |
 | ---- | ---- | -------- | ----------- | ---- |
-| ip_addresses | InfraIPAddress | True | many | Component |
+| ip_addresses | IpamIPAddress | True | many | Component |
 | security_zone | SecurityZone | False | one | Attribute |
 
 ## Generics
@@ -558,7 +558,7 @@ nodes:
     optional: true
   relationships:
   - name: ip_address
-    peer: InfraIPAddress
+    peer: IpamIPAddress
     cardinality: one
     kind: Attribute
     optional: false
@@ -579,7 +579,7 @@ nodes:
     optional: true
   relationships:
   - name: ip_prefix
-    peer: InfraPrefix
+    peer: IpamPrefix
     cardinality: one
     kind: Attribute
     optional: false
@@ -907,14 +907,15 @@ nodes:
 - name: Firewall
   namespace: Security
   inherit_from:
-  - InfraGenericDevice
+  - DcimGenericDevice
+  - DcimPhysicalDevice
   - CoreArtifactTarget
   - SecurityPolicyAssignment
   icon: mdi:firewall
   include_in_menu: true
   human_friendly_id:
   - name__value
-  menu_placement: InfraGenericDevice
+  menu_placement: DcimGenericDevice
   attributes:
   - name: role
     kind: Dropdown
@@ -1034,16 +1035,16 @@ nodes:
 - name: FirewallInterface
   namespace: Security
   label: Firewall Interface
-  menu_placement: InfraGenericDevice
+  menu_placement: DcimGenericDevice
   include_in_menu: false
   icon: mdi:ethernet
   display_label: name__value
   inherit_from:
-  - InfraInterface
-  - InfraEndpoint
+  - DcimInterface
+  - DcimEndpoint
   relationships:
   - name: ip_addresses
-    peer: InfraIPAddress
+    peer: IpamIPAddress
     optional: true
     cardinality: many
     kind: Component