diff --git a/docs/index.yml b/docs/index.yml
index 730f9e7782..11e8312488 100644
--- a/docs/index.yml
+++ b/docs/index.yml
@@ -110,8 +110,18 @@ navigation:
 
     - section: Operations
       contents:
-        - page: NVLink Partitioning
-          path: manuals/nvlink_partitioning.md
+        - section: Network Isolation
+          contents:
+            - page: Overview
+              path: manuals/network_isolation.md
+            - page: Ethernet Isolation
+              path: manuals/networking/ethernet_isolation.md
+            - page: Network Security Groups
+              path: manuals/networking/network_security_groups.md
+            - page: InfiniBand Isolation
+              path: manuals/networking/infiniband_isolation.md
+            - page: NVLink Partitioning
+              path: manuals/nvlink_partitioning.md
         - page: Release Instance API Enhancements
           path: manuals/breakfix_integration.md
         - page: IP Resource Pools
diff --git a/docs/manuals/network_isolation.md b/docs/manuals/network_isolation.md
new file mode 100644
index 0000000000..3ff5f2b773
--- /dev/null
+++ b/docs/manuals/network_isolation.md
@@ -0,0 +1,100 @@
+# Network Isolation
+
+NICo enforces tenant network isolation across three independent fabrics. Each
+fabric uses a different mechanism, is configured through a different operator
+API, and is verified separately. This page summarises the model so an operator
+can choose the right guide; it is not a replacement for the per-fabric
+configuration guides linked below.
+
+| Fabric | Operator-facing primitive | Isolation enforced by |
+|---|---|---|
+| Ethernet | VPC + VpcPrefix (+ optional Network Security Group) | DPU VRF per VPC (HBN / NVUE) over a pure type-5 EVPN overlay |
+| InfiniBand | InfiniBand partition | UFM P_Key partition membership; `IbFabricMonitor` reconciler |
+| NVLink | NVLink logical partition | NMX-M / NMX-C partition lifecycle; `NvlPartitionMonitor` reconciler |
+
+---
+
+## Ethernet
+
+A tenant's instance reaches a VPC by drawing addresses from one of the
+**VpcPrefixes** attached to that VPC. NICo carves a /31 link-net per
+interface from the prefix — one address to the instance, one to the
+DPU's SVI in the VPC's VRF. An instance may participate in several VPCs
+at once by having interfaces drawing from prefixes in different VPCs.
+On the DPU of the managed host backing the instance, each related VPC
+materialises as a Linux VRF; every host interface drawing from a prefix
+in that VPC lives in that VRF.
+
+VRFs are isolated by default. Cross-VPC reachability requires explicit VPC
+peering or controlled route leaking via the VPC's routing profile. Layer 3 / 4
+filtering within or across VPCs is provided by Network Security Groups,
+attached at VPC or instance scope.
+
+See [Ethernet Isolation](networking/ethernet_isolation.md) for the operator
+configuration guide.
+
+---
+
+## InfiniBand
+
+Each tenant InfiniBand partition maps to a UFM P_Key. Membership is enforced
+by the subnet manager at the fabric level: hosts that are not full members of
+a P_Key cannot exchange traffic with other members of that P_Key, regardless
+of physical connectivity. NICo reconciles desired partition membership against
+UFM via the `IbFabricMonitor` background task and surfaces the synchronisation
+status to operators and to tenants.
+
+See [InfiniBand Isolation](networking/infiniband_isolation.md) for the operator
+configuration guide.
+
+---
+
+## NVLink
+
+NVLink logical partitions group GPUs across hosts into a single isolated
+NVLink domain. NICo drives partition lifecycle against the NMX-M REST API and
+the NMX-C gRPC API and reconciles desired partitions periodically. Each tenant
+instance that requests NVLink connectivity is placed into the partition
+corresponding to its allocation; a host whose GPUs are not in a partition
+cannot reach any other host's GPUs over NVLink.
+
+See [NVLink Partitioning](nvlink_partitioning.md) for the operator
+configuration guide.
+
+---
+
+## Cross-cutting behaviour
+
+The following invariants apply to every fabric.
+
+- **Per-fabric synchronisation status.** Each instance's `InstanceStatus`
+  exposes a per-fabric `configs_synced` field that is `true` only when the
+  observed fabric state matches the desired configuration. The aggregate
+  `configs_synced` field is the logical AND of all per-fabric fields and gates
+  the instance's `Ready` state.
+- **Provisioning blocks on isolation convergence.** During initial
+  provisioning, the instance state machine waits until every requested fabric
+  has applied the desired configuration before the instance is marked `Ready`.
+  Tenants observe this as the `Configuring` tenant state, and the machine
+  remains in `WaitingForNetworkConfig` until the DPU reports back.
+- **Termination blocks on isolation convergence.** During termination, the
+  state machine waits until every fabric reports that the host has been
+  removed from all tenant partitions before the instance is reported as
+  deleted. This guarantees a terminated instance cannot continue to exchange
+  traffic on any fabric.
+- **Force-delete still tears down fabric state.** Force-deleting a managed
+  host explicitly detaches it from every fabric through the same external
+  APIs the normal lifecycle uses, so external fabric managers do not retain
+  stale tenant references.
+- **External fabric reachability is monitored.** Each external fabric service
+  (UFM, NMX-M, NMX-C) is monitored from NICo with request-success and latency
+  metrics so that fabric-side outages can be distinguished from NICo-side
+  configuration errors.
+
+For the architectural rationale and the patterns shared across all three
+fabrics, see
+[Networking Integrations](../architecture/networking_integrations.md).
+
+For the Day 0 IP, DHCP, DNS, and admin-network configuration that every
+isolation guarantee on this page rests on, see
+[Day 0 IP and Network Configuration](../getting-started/installation-options/day0-ip-network-config.md).
diff --git a/docs/manuals/networking/ethernet_isolation.md b/docs/manuals/networking/ethernet_isolation.md
new file mode 100644
index 0000000000..d1bcd5ef4b
--- /dev/null
+++ b/docs/manuals/networking/ethernet_isolation.md
@@ -0,0 +1,397 @@
+# Ethernet Isolation
+
+This page explains how NICo provides Ethernet network isolation between
+tenants and across VPCs, and how an operator configures and verifies it. It
+is the Day-1 configuration guide; the architectural rationale lives in
+[Networking Integrations](../../architecture/networking_integrations.md), and
+the deep mechanics of VXLAN / EVPN, BGP route-targets, and routing profiles
+live in [VPC Network Virtualization](../vpc/vpc_network_virtualization.md).
+
+**Related pages**
+
+- [Network Isolation Overview](../network_isolation.md)
+- [Day 0 IP and Network Configuration](../../getting-started/installation-options/day0-ip-network-config.md)
+  — the operator-facing Day 0 reference for IP pools, admin / underlay
+  segments, DHCP, and DNS. The isolation guarantees on this page assume
+  the Day 0 configuration is already in place.
+- [VPC Network Virtualization](../vpc/vpc_network_virtualization.md) — the
+  full VXLAN / EVPN, VRF, BGP, and routing-profile reference
+- [VPC Routing Profiles](../vpc/vpc_routing_profiles.md)
+- [VPC Peering](../vpc/vpc_peering_management.md)
+- [Network Security Groups](network_security_groups.md)
+- [IP Resource Pools](ip_resource_pools.md)
+- [VNI Resource Pools](../vpc/vni_resource_pools.md)
+
+---
+
+## The Isolation Model
+
+NICo's Ethernet isolation is built on three objects that compose into a
+single chain. This page describes the **Native Networking (FNN)** model,
+which is the official NICo network virtualization model.
+
+```
+Instance ──► Network Interface ──► VpcPrefix ──► VPC ──► VRF on DPU
+                                  (/31 link-net is vended per interface)
+```
+
+Read this chain top to bottom:
+
+1. A **tenant instance** owns one or more **network interfaces** on the host
+   it is allocated to.
+2. Each interface is allocated an IP address from one of the **VpcPrefixes**
+   attached to a VPC. NICo carves a `/31` link-net from the VpcPrefix per
+   interface — one address goes to the instance, the other goes to the
+   DPU's SVI. The /31 is the operator-visible unit of consumption for the
+   prefix; `VpcPrefixStatus` reports `total_31_segments` and
+   `available_31_segments` so operators can size prefixes against expected
+   instance counts.
+3. Every VpcPrefix belongs to exactly one **VPC**. Attaching an interface
+   to a VpcPrefix is what places the interface in the parent VPC. A VPC
+   may have several VpcPrefixes; an instance may have interfaces drawing
+   from prefixes in different VPCs.
+4. On the DPU of the managed host backing the instance, each VPC the
+   instance touches materialises as a **Linux VRF**. The DPU's SVI for
+   each vended /31 lives in that VRF; everything beyond the SVI is
+   routed.
+
+> **Implementation detail.** Internally, NICo records each vended /31 as a
+> `NetworkSegment` row attached to the VpcPrefix. Operators do not
+> normally manipulate these directly — they are visible through the same
+> RPCs but are tenant-managed only as a byproduct of instance
+> configuration.
+
+An operator configures three things independently to control what reaches
+what:
+
+| Concern | What it determines | Operator primitive |
+|---|---|---|
+| Subnet attachment | Which VPC's VRF an interface joins, and which CIDR pool its IP comes from | **VpcPrefix** attached to a VPC |
+| Routing (L3) | Reachability between subnets and between VPCs across the fabric | VPC and its routing profile (type-5 EVPN imports / exports, route leaking) |
+| Filtering (L3 / L4) | Which permitted flows reach an instance's prefixes and ports | Network Security Group |
+
+An instance may have interfaces drawing from VpcPrefixes in **several VPCs
+at once** (for example, a tenant-data VPC and a separate storage VPC). Each
+VPC that the instance touches becomes its own VRF on the DPU; nothing
+forwards between VRFs by default.
+
+---
+
+## VXLAN / EVPN Underlay (in Brief)
+
+NICo carries tenant traffic over a VXLAN / EVPN overlay. Each DPU is a VTEP
+that peers with the site fabric (route servers or top-of-rack switches) using
+BGP EVPN. Each VPC is identified on the overlay by a VNI; the per-VPC VRF on
+the DPU imports and exports BGP routes tagged with route-targets derived from
+the VPC's VNI and the site's `datacenter_asn`. Isolation between VPCs is a
+direct consequence: a VRF imports only the route-targets its routing profile
+declares, so a route advertised in one VPC does not appear in another VPC's
+forwarding table.
+
+The tenant overlay is a **pure type-5 EVPN (IP-prefix) overlay**. NICo does
+not stretch any tenant L2 segment across the fabric. The host-to-DPU link is
+layer-2 (the segment's VLAN ID is the multiplexer), the DPU acts as the L3
+gateway via the segment's SVI, and the DPU re-advertises the host's
+instance route into the fabric as a type-5 EVPN prefix tagged with the VPC's
+route-target. Cross-host reachability inside a tenant VPC is therefore an
+L3 routing decision, never an L2 bridging decision; the segment's VNI is an
+L3VNI identifying the parent VPC's VRF, not an L2VNI extending a broadcast
+domain.
+
+The admin overlay (see [Default Isolation](#default-isolation-the-admin-overlay))
+is the one exception: admin segments carry both an L2VNI and an L3VNI to
+support admin-side workflows that occasionally require L2 reachability.
+Tenant segments never do.
+
+For the full BGP / route-target / VTEP picture (loopback pools, per-DPU ASN,
+internal vs. external VNI pools, default-route mechanisms, and the
+configuration checklist for a new site), follow
+[VPC Network Virtualization](../vpc/vpc_network_virtualization.md). This page
+does not duplicate that material.
+
+---
+
+## Routing Isolation: VPCs and VRFs
+
+A VPC is the unit of routing isolation:
+
+- Every VPC has its own VRF on every DPU that hosts an instance with an
+  interface in that VPC. The VRF holds only the routes the VPC's routing
+  profile permits.
+- Routes inside one VPC's VRF are not visible to another VPC's VRF. This is
+  enforced by BGP route-target import / export, not by ACLs, and applies
+  identically to instances of the same tenant and instances of different
+  tenants.
+- Reachability between two VPCs is opt-in. An operator can establish it
+  through:
+  - **VPC peering** — see
+    [VPC Peering](../vpc/vpc_peering_management.md). Peered VPCs install
+    each other's host routes via additional route-target imports.
+  - **A shared external route-target** declared in both VPCs' routing
+    profiles, when the network team operates a transit VRF.
+  - **Controlled route leaking** between a VPC VRF and the underlay default
+    VRF via the `leak_*` fields on the routing profile. This is intended for
+    internet access or for narrow injection of underlay prefixes, and is
+    described in detail under
+    [VPC Network Virtualization → Controlled Route Leaking](../vpc/vpc_network_virtualization.md#controlled-route-leaking).
+- The set of prefixes a tenant must never reach (for example, the management
+  plane) is declared once site-wide in `deny_prefixes` in the API server
+  configuration. The DPU enforces this as an ACL on every tenant VRF.
+
+---
+
+## Default Isolation: The Admin Overlay
+
+NICo guarantees that a managed host is never permitted to carry tenant
+traffic unless an explicit tenant configuration places it into a VPC. This
+guarantee is upheld by an **admin overlay** that is separate from every
+tenant VPC.
+
+- During site initialisation NICo creates an admin VPC and a set of admin
+  network segments. These are not tenant-visible and exist only to give the
+  DPU somewhere safe to attach a host before, between, and after tenant
+  allocations.
+- When the API server assembles the per-host network configuration for a
+  DPU, it sets `use_admin_network = true` in `ManagedHostNetworkConfig`
+  whenever the host has no instance allocated, the instance has no
+  interfaces configured for this DPU, or the host is in a transient
+  lifecycle state in which tenant traffic must not flow. The DPU agent
+  then places every host interface on the admin overlay instead of any
+  tenant VPC's VRF.
+- A DPU that cannot retrieve its configuration at all — for example,
+  because the host is unknown to NICo and `GetManagedHostNetworkConfig`
+  returns `NOT_FOUND` — places itself into **isolated mode**: every host
+  interface is detached from any tenant overlay until NICo issues an
+  explicit configuration. This is the fail-closed default; nothing in the
+  data path will silently fall back to a tenant network.
+- The same admin-overlay path is used to enforce isolation during
+  instance termination. The instance state machine blocks the
+  termination flow until the DPU confirms that all tenant interfaces have
+  been moved off tenant VPCs and onto the admin overlay (or that the
+  machine has been tagged with a health alert preventing reuse). This is
+  what guarantees that a tenant whose instance has been released cannot
+  remain on the wire as a "ghost instance".
+
+A "default VPC" in the cloud-provider sense — a system-created VPC that
+every tenant inherits — does not exist in NICo. Tenants get the VPCs an
+operator (or the tenant API) creates for them; absent any such VPC, an
+instance has nowhere to send tenant traffic.
+
+For the deeper handler-level account, see
+[VPC Network Virtualization → How a DPU Gets Its Configuration](../vpc/vpc_network_virtualization.md#how-a-dpu-gets-its-configuration).
+
+---
+
+## Subnet Attachment: VPC Prefixes
+
+A **VpcPrefix** is the tenant-facing primitive for declaring an IPv4 or
+IPv6 CIDR pool that a VPC may draw instance-interface addresses from.
+Creating a VpcPrefix is how a tenant says "instances allocated into this
+VPC should get IPs from this CIDR."
+
+A VpcPrefix has:
+
+- A **parent VPC**, set at creation time. The prefix cannot be moved
+  between VPCs.
+- A **CIDR** (`config.prefix`), IPv4 or IPv6, that NICo carves /31
+  link-nets out of when instance interfaces are allocated.
+- A **status** field reporting `total_31_segments` and
+  `available_31_segments`. A prefix is exhausted when available reaches
+  zero; further interface allocations against this prefix fail until
+  either another VpcPrefix with capacity is attached to the same VPC, or
+  the exhausted prefix is replaced.
+- A **metadata** block (name, labels) for operator and tenant
+  bookkeeping.
+
+A VPC may have any number of VpcPrefixes attached. When an instance
+interface is created in a VPC, NICo selects one of that VPC's prefixes
+with available capacity and vends the next free /31 from it: one address
+to the instance, the other to the DPU's SVI in the VPC's VRF.
+
+The fabric carries the prefix as a type-5 EVPN route in the parent VPC's
+VRF, tagged with the route-targets the VPC's routing profile declares.
+There is no per-prefix VNI; the L3VNI is the VPC's VNI and applies
+uniformly to every prefix attached to that VPC.
+
+### How a Tenant Creates a VpcPrefix
+
+In the FNN model, prefixes are created via the gRPC `CreateVpcPrefix` RPC
+or its REST equivalent (`POST /v2/org/{org}/carbide/vpc-prefix`).
+Operators can drive the same flow via `admin-cli`:
+
+```
+nico-admin-cli vpc-prefix create --vpc-id <vpc-id> --prefix <cidr> [--name <label>]
+nico-admin-cli vpc-prefix show
+```
+
+Update and delete subcommands follow the same pattern. `DeleteVpcPrefix`
+succeeds only when no /31 from the prefix is currently in use; in
+practice that means every instance interface drawing from the prefix
+must be released first.
+
+### Implementation Note: NetworkSegments
+
+Internally, NICo records each vended /31 as a `NetworkSegment` row
+attached to the parent VpcPrefix. The `NetworkSegment` is the unit of
+on-the-wire configuration the DPU receives — one VLAN ID, one /31, one
+SVI in the VPC's VRF — but operators rarely manipulate segments
+directly. The VpcPrefix's `available_31_segments` counter is the
+operator's view of pool consumption, and the per-instance
+`configs_synced.ethernet` field is the operator's view of convergence.
+Segments come and go with instance-interface lifecycle; the VpcPrefix
+is what the tenant declares and what persists.
+
+### Multi-Prefix and Multi-VPC Instances
+
+The VpcPrefix-attached-to-a-VPC model supports two common patterns
+without any extra tenant configuration:
+
+- **Multiple prefixes in the same VPC.** A VPC may host several
+  VpcPrefixes — for example, a primary tenant subnet and a separate
+  storage subnet. All of them land in the same VRF on the DPU. This is
+  the right approach when a workload needs distinct CIDRs but a single
+  routing policy.
+- **Prefixes in different VPCs.** An instance's interfaces may draw
+  from prefixes attached to different VPCs. Each VPC materialises as
+  its own VRF on the DPU; the instance straddles them at the OS layer.
+  This is how a workload joins, for example, a tenant-data VPC and a
+  shared-services VPC simultaneously without giving up VPC-level
+  routing isolation.
+
+Per-interface attachment is configured through `UpdateInstanceConfig`.
+The state machine guards `Ready` until the DPU reports that every
+interface has converged on its target VPC / prefix / VRF; tenants
+observe the in-flight state as `Configuring`.
+
+---
+
+## Layer 3 / 4 Isolation: Network Security Groups
+
+Network Security Groups (NSGs) provide stateful or stateless rule-based
+filtering on top of the VRF model. A NSG is a tenant-owned object that
+carries a prioritised list of `(direction, protocol, src/dst CIDR,
+src/dst port range, action)` rules and is attached at one of two scopes:
+
+- **VPC scope.** Every instance in the VPC inherits the NSG's rules.
+- **Instance scope.** The NSG applies to that instance only and overrides
+  the VPC-scope NSG (if any).
+
+NSG rules are pushed to the DPU as part of the same per-interface
+configuration response that carries the segment and VRF information, and are
+materialised into NVUE ACLs by the DPU agent. Propagation status is reported
+back to NICo so that the per-instance `configs_synced` signal reflects NSG
+convergence as well as VRF / segment convergence.
+
+NSGs are the right tool for tenant-controlled segmentation **inside** a VPC
+(for example, blocking East-West traffic between application tiers) and for
+restricting which underlay-leaked prefixes a tenant is permitted to reach.
+They are not a substitute for the VPC's routing isolation: an NSG cannot
+make two VPCs reachable that the routing profile keeps apart.
+
+See [Network Security Groups](network_security_groups.md) for the full rule
+syntax, RPC reference, attachment workflow, and the current limitations.
+
+---
+
+## Configuration Workflow
+
+Configure Ethernet isolation in the following order. Each step builds on
+the previous one.
+
+### 1. Confirm site-level prerequisites
+
+Before any tenant configuration, the site must already have:
+
+- The full Day 0 IP and network configuration in place. See
+  [Day 0 IP and Network Configuration](../../getting-started/installation-options/day0-ip-network-config.md)
+  for the canonical reference — admin network segment(s) declared in
+  `[networks.admin]`, OOB management segments under `[networks.<name>]`,
+  the `lo-ip` and `vpc-dpu-lo` loopback pools, DHCP relays, and DNS.
+- Configured `fnn-asn`, `vpc-vni`, and (if external VPCs are needed)
+  `external-vpc-vni` resource pools.
+- A `datacenter_asn`, a `deny_prefixes` list, and at least one routing
+  profile defined under `fnn.routing_profiles`.
+- BGP / EVPN agreement with the network team on route-target convention.
+
+If any of these are missing, follow the Day 0 page first, then the
+[VPC Network Virtualization → Configuration Checklist for a New Site](../vpc/vpc_network_virtualization.md#configuration-checklist-for-a-new-site).
+None of the steps below will succeed otherwise.
+
+### 2. Create the VPC
+
+Use `admin-cli vpc create` (or `CreateVpc` directly) and supply the routing
+profile name. The profile determines whether the VPC is internal or external
+and which route-targets it imports and exports. Creation fails fast if the
+named profile is not defined site-wide.
+
+### 3. Attach VpcPrefixes to the VPC
+
+Use `admin-cli vpc-prefix create` (or `CreateVpcPrefix`). Supply the
+parent VPC and the CIDR. Repeat for as many prefixes as the VPC needs.
+Per-instance /31 link-nets and their underlying NetworkSegment rows are
+vended automatically as instances are allocated; the operator does not
+create segments directly.
+
+### 4. (Optional) Create and attach Network Security Groups
+
+For the tenant traffic patterns that require L3 / L4 filtering, create
+NSGs and attach them at VPC or instance scope. See
+[Network Security Groups](network_security_groups.md).
+
+### 5. Allocate instances and attach interfaces
+
+When an instance is allocated, declare each interface's parent VPC in
+the instance configuration. NICo selects a VpcPrefix in that VPC with
+capacity and vends a /31 to the interface. The instance is blocked in
+`WaitingForNetworkConfig` until the DPU reports every interface
+converged on the requested VPC, prefix, NSG, and VRF; only then does
+the instance reach `Ready`.
+
+---
+
+## Verification
+
+For each tenant that an operator has configured, confirm the following:
+
+1. **VPC presence and status.** `admin-cli vpc list` shows the VPC in
+   `Ready` state; `admin-cli vpc show <id>` shows the expected routing
+   profile and (if applicable) the attached NSG.
+2. **VpcPrefix presence and capacity.** `admin-cli vpc-prefix show`
+   (optionally filtered by VPC) lists every VpcPrefix attached to the
+   VPC and reports `available_31_segments`. Every VPC that needs to host
+   instances must have at least one VpcPrefix with available capacity.
+3. **Instance configuration convergence.** `admin-cli instance show <id>`
+   reports `tenant.state = Ready` and `configs_synced.ethernet = true`.
+   While provisioning is in flight, the tenant state is `Configuring` and
+   the per-fabric `configs_synced.ethernet` is `false`.
+4. **DPU view.** `admin-cli dpu show <machine_id>` (or the equivalent
+   per-host inspection) reports a separate VRF for each VPC the instance
+   touches, and the host interfaces are members of the expected VRFs.
+5. **Underlay reachability.** All BGP sessions reported by the DPU are
+   `established`, and the DPU's loopback addresses are reachable from
+   every other DPU and from the route servers.
+
+The negative case is equally important: an unallocated host should report
+its DPU on the admin overlay, with no tenant VRF present. A host whose
+`GetManagedHostNetworkConfig` returns `NOT_FOUND` should report itself in
+isolated mode and refuse to carry tenant traffic.
+
+---
+
+## Troubleshooting
+
+Most Ethernet-isolation symptoms reduce to one of the following classes.
+Diagnose in order; each pointer leads to a focused troubleshooting section
+elsewhere in the docs.
+
+| Symptom | Likely class | Where to look |
+|---|---|---|
+| Instance never leaves `Configuring`; `configs_synced.ethernet = false` | DPU has not converged on the requested VPC / prefix / VRF | [Stuck in WaitingForNetworkConfig and DPU Health](../../playbooks/stuck_objects/waiting_for_network_config.md) |
+| `CreateVpc` returns `NOT_FOUND` for the routing profile | Routing profile name not defined in `fnn.routing_profiles` | [VPC Routing Profiles](../vpc/vpc_routing_profiles.md) |
+| Instance allocation fails with "no prefix capacity" | The instance's VPC has no VpcPrefix with `available_31_segments > 0`; attach another prefix | This page, [Subnet Attachment: VPC Prefixes](#subnet-attachment-vpc-prefixes) |
+| Intra-VPC reachability works, internet access fails | Routing-profile `route_target_imports` or default-route mechanism misconfigured | [VPC Network Virtualization → Internet Connectivity](../vpc/vpc_network_virtualization.md#internet-connectivity) |
+| Egress works, no return traffic | Network device VRFs not importing the VPC's `route_targets_on_exports` | [VPC Network Virtualization → Export Route-Targets and Return-Path Reachability](../vpc/vpc_network_virtualization.md#export-route-targets-and-return-path-reachability) |
+| Two instances in the same VPC cannot reach each other on a permitted port | NSG rule denies the flow | [Network Security Groups](network_security_groups.md) |
+| Tenant traffic appears on an unallocated host | `use_admin_network` not asserted; treat as a security incident | [Force Deleting and Rebuilding Hosts](../../playbooks/force_delete.md) and the architecture reference |
+| `DeleteVpcPrefix` fails | At least one /31 from the prefix is still in use by an instance interface; release those instances first | This page, [How a Tenant Creates a VpcPrefix](#how-a-tenant-creates-a-vpcprefix) |
+| New VPC has nowhere to put instances | No VpcPrefix attached yet; create one with `admin-cli vpc-prefix create --vpc-id <id> --prefix <cidr>` | This page |
diff --git a/docs/manuals/networking/infiniband_isolation.md b/docs/manuals/networking/infiniband_isolation.md
new file mode 100644
index 0000000000..c3cd1c333a
--- /dev/null
+++ b/docs/manuals/networking/infiniband_isolation.md
@@ -0,0 +1,363 @@
+# InfiniBand Isolation
+
+This page is the Day-1 configuration guide for InfiniBand isolation in NICo.
+It describes how a tenant's InfiniBand traffic is isolated from every other
+tenant's via UFM-managed P_Key partitions, what an operator configures up
+front, and how to verify that a host has ended up where it is supposed to be.
+
+The InfiniBand fabric itself — UFM installation, `gv.cfg` / `opensm.conf`
+tuning, M_Key and SA_Key configuration, and static topology files — is
+covered separately in the [InfiniBand Setup
+runbook](../../playbooks/ib_runbook.md). That runbook is a prerequisite for
+this page: NICo's isolation guarantees rest on a properly hardened UFM and
+subnet manager.
+
+**Related pages**
+
+- [Network Isolation Overview](../network_isolation.md)
+- [InfiniBand Setup Runbook](../../playbooks/ib_runbook.md) — UFM and OpenSM
+  hardening (prerequisite)
+- [InfiniBand NIC and Port Selection](../../architecture/infiniband/nic_selection.md)
+  — how NICo picks which host NICs / ports are managed
+- [Networking Integrations](../../architecture/networking_integrations.md) —
+  shared architectural patterns across all three fabrics
+
+---
+
+## The Isolation Model
+
+InfiniBand isolation in NICo is built on the InfiniBand-native P_Key
+mechanism enforced by the subnet manager. The operator-facing chain is:
+
+```
+Instance ──► IB Interface ──► IbPartition (NICo) ──► P_Key (UFM)
+```
+
+Read it top to bottom:
+
+1. A **tenant instance** has one or more **IB interfaces**, one per
+   InfiniBand port on the host the instance is allocated to.
+2. Each IB interface references exactly one **`IbPartition`** by ID — this
+   is the NICo object the tenant manipulates.
+3. The `IbPartition` corresponds to a single **P_Key** on UFM. NICo either
+   allocates the P_Key value from a configured range or honours an
+   explicit P_Key the operator supplied.
+4. Enforcement happens at the **subnet manager**. A host port that is not
+   a member of a P_Key cannot exchange InfiniBand traffic with any other
+   member of that P_Key, regardless of physical connectivity. The
+   isolation is fabric-side, not host-side: a misconfigured host cannot
+   bypass it.
+
+Two instances in different P_Keys cannot send any IB traffic to each other.
+Two instances in the same P_Key can. There is no operator-visible
+"peering" concept for InfiniBand the way there is for Ethernet VPCs;
+sharing requires placing both instances' interfaces in the same partition.
+
+---
+
+## What Lives Where
+
+| Concern | Location |
+|---|---|
+| Subnet manager, M_Key / SA_Key hardening, static topology | UFM host (see the IB runbook) |
+| UFM endpoint URL(s) and managed P_Key ranges | NICo API server TOML, under `[ib_fabrics.<name>]` |
+| Fabric-wide toggles (enable, MTU, rate limit, service level, monitor cadence) | NICo API server TOML, under `[ib_config]` |
+| UFM API credentials | Vault (or the configured secrets backend), not the TOML file |
+| `IbPartition` objects (tenant-owned) | NICo database, managed via gRPC RPCs |
+| Per-interface partition assignment | `InstanceInfinibandConfig` on the instance, managed via `UpdateInstanceConfig` |
+| Reconciliation between desired and actual UFM state | `IbFabricMonitor`, a background task inside the API server |
+
+NICo treats UFM as the authoritative source for **observed** fabric state.
+It does not cache UFM partition membership separately from what the monitor
+last read. This means that direct out-of-band changes to UFM (an operator
+editing partitions in the UFM UI, for example) will be detected on the next
+monitor iteration and reconciled back to NICo's intended state.
+
+---
+
+## Configuring NICo to Talk to UFM
+
+Two TOML blocks are involved. Both live in the API server's config file.
+
+### `[ib_fabrics.<name>]` — Endpoints and P_Key Pool
+
+Each named entry defines one InfiniBand fabric that NICo manages.
+
+```toml
+[ib_fabrics.fabric_a]
+endpoints = ["https://ufm-a.example.internal:443"]
+
+  [[ib_fabrics.fabric_a.pkeys]]
+  start = "0x100"
+  end   = "0x1ff"
+
+  [[ib_fabrics.fabric_a.pkeys]]
+  start = "0x300"
+  end   = "0x3ff"
+```
+
+Fields:
+
+| Field | Purpose |
+|---|---|
+| `endpoints` | UFM server URLs. At the time of writing only the first endpoint is consulted; multi-endpoint support exists in the schema for forward compatibility |
+| `pkeys` | One or more inclusive P_Key ranges, hex-encoded. These define the pool that NICo's auto-allocator draws from when a tenant creates an `IbPartition` without specifying a P_Key |
+
+P_Key ranges may be **extended in future restarts but never shrunk**:
+removing or narrowing a range under live tenants would orphan allocated
+partitions. Plan the pool with headroom.
+
+### `[ib_config]` — Fabric Toggles
+
+```toml
+[ib_config]
+enabled = true
+allow_insecure = false
+mtu = 4096
+rate_limit = 200
+service_level = 0
+fabric_monitor_run_interval = "60s"
+```
+
+| Field | Purpose |
+|---|---|
+| `enabled` | Master switch. With `false`, NICo will not call UFM and will not run the monitor |
+| `allow_insecure` | Permit TLS to UFM without certificate verification. Intended for development only |
+| `mtu`, `rate_limit`, `service_level` | Defaults applied to NICo-managed partitions when not overridden per partition |
+| `fabric_monitor_run_interval` | Steady-state cadence for `IbFabricMonitor`. Defaults to 60 seconds |
+
+### UFM credentials
+
+UFM API credentials are not stored in TOML. They are read from the
+configured secrets backend (Vault under standard deployments) by the UFM
+client during initialisation. Rotate them at the secrets backend; NICo
+picks up the new value on its next client re-initialisation.
+
+---
+
+## P_Key Allocation
+
+When a tenant calls `CreateIbPartition`, the request may include or omit a
+desired P_Key:
+
+- **`pkey` omitted.** NICo allocates a free P_Key from the configured
+  pool ranges and returns it on the response. This is the normal tenant
+  flow.
+- **`pkey` specified** (hex, for example `"0x76b"`). NICo accepts the
+  request only if the requested value falls inside a pool range that is
+  **not** marked as auto-assigned, and is otherwise free. Otherwise the
+  request is rejected.
+
+The model's `IbPartition` object retains the allocated P_Key for the
+lifetime of the partition. There is no "renumber" operation; to change a
+P_Key, delete the partition and create a new one (which the tenant flow
+handles via instance reconfiguration).
+
+`UpdateIbPartition` is restricted to fields other than P_Key (name, MTU,
+rate limit, and so on). `DeleteIbPartition` requires that no instance
+still references the partition.
+
+---
+
+## Membership: Full vs Limited
+
+UFM distinguishes **full** and **limited** P_Key membership. Full members
+can communicate with both full and limited members of the same P_Key;
+limited members can only talk to full members.
+
+NICo's posture:
+
+- The `IbPortMembership` enum is **read-only** from NICo's perspective.
+  The monitor records whatever UFM reports for each port-in-partition
+  binding.
+- NICo does **not** expose a config option to choose full or limited
+  membership when creating a partition. Whatever UFM is configured to use
+  (typically full members, with the default partition restricted by the
+  `default_membership = limited` hardening in the IB runbook) is what
+  appears on a NICo-managed binding.
+- The monitor flags a security alert if the default partition shows full
+  membership on a NICo-managed port; that is an indication the UFM
+  hardening described in the runbook has not been applied.
+
+---
+
+## The `IbFabricMonitor`
+
+`IbFabricMonitor` is the background reconciler inside the API server.
+Every iteration it:
+
+1. Reads UFM state: port information (state, GUID, LID), partition
+   membership lists, fabric version, M_Key / SM_Key / SA_Key configuration,
+   and default-partition membership.
+2. Compares observed UFM state to the desired state implied by each
+   instance's `InstanceInfinibandConfig`.
+3. For each IB interface in an instance config, if the host GUID is not
+   already a member of the expected P_Key, calls `bind_ib_ports()` to add
+   it.
+4. For any GUID found in a NICo-managed P_Key that no longer matches a
+   live instance config, calls `unbind_ib_ports()` to remove it.
+5. Updates per-machine InfiniBand status observations in the NICo
+   database, which is what feeds the `configs_synced.infiniband` field on
+   `InstanceStatus`.
+
+Cadence is set by `fabric_monitor_run_interval` (default 60 seconds). After
+applying any UFM changes, the monitor accelerates the next iteration to
+~1 second so that convergence shows up quickly in observed state. Once a
+steady iteration completes with no changes, the monitor returns to the
+configured interval.
+
+The monitor exposes metrics under the `carbide_ib_monitor_*` namespace:
+
+| Metric | Use |
+|---|---|
+| `carbide_ib_monitor_iteration_latency` | Time per reconcile pass; a sudden rise indicates UFM slowness |
+| `carbide_ib_monitor_ufm_changes_applied` | Counter of bind/unbind operations issued; nonzero in steady state is an anomaly |
+| `carbide_ib_monitor_machines_by_port_state_count` | Port-state histogram; helps spot hosts stuck `Initialize` or `Down` |
+| `carbide_ib_monitor_machines_with_missing_pkeys_count` | Hosts that should be in a partition but are not — investigate |
+| `carbide_ib_monitor_machines_with_unexpected_pkeys_count` | Hosts that are in partitions they should not be — investigate immediately |
+| `carbide_ib_monitor_ufm_partitions_count` | Partition count UFM reports; sanity check against NICo's view |
+| UFM-error counters | Connection / authentication failures; the schema for these is acknowledged as incomplete in the current code |
+
+---
+
+## How a Tenant Ends Up in a Partition
+
+For a tenant instance with an IB interface attached to a partition:
+
+1. The tenant calls `UpdateInstanceConfig` with an
+   `InstanceInfinibandConfig` containing one
+   `InstanceIbInterfaceConfig` per IB port, each referencing the
+   desired `ib_partition_id`.
+2. NICo validates the config (every referenced `IbPartition` exists,
+   ownership matches the tenant) and stores it in the database.
+3. The next `IbFabricMonitor` iteration observes the new desired state
+   and issues `bind_ib_ports()` for each host GUID that is not already a
+   member of the expected P_Key.
+4. UFM updates partition membership. On the following iteration the
+   monitor reads back the new membership and updates the machine's IB
+   status observation.
+5. `InstanceStatus::infiniband::configs_synced` flips to `true` once
+   observed UFM state matches desired state. The aggregate
+   `configs_synced` and therefore the instance's `Ready` state follow.
+
+Tenants observe the in-flight state as `Configuring` and the
+`InstanceStatus` machine remains in `WaitingForNetworkConfig` until the
+monitor reports convergence.
+
+---
+
+## Force-Delete and Cleanup
+
+When an instance is released or its host is force-deleted, NICo clears
+the IB interfaces from the instance config. The reconciler then sees host
+GUIDs in NICo-managed P_Keys that no longer correspond to any live
+instance and removes them via `unbind_ib_ports()`.
+
+NICo tracks the cleanup with an `IbCleanupPending` health alert on the
+machine. The alert is set when cleanup is required and cleared once the
+monitor confirms that every GUID has been removed from UFM-side
+partitions. A machine with an outstanding `IbCleanupPending` alert is
+ineligible for reuse by another tenant: this is the IB equivalent of the
+Ethernet termination guard described in
+[Default Isolation](../vpc/vpc_network_virtualization.md#default-isolation-the-admin-overlay).
+
+There is no dedicated "force-delete IB partition" RPC. Partitions persist
+in the NICo database independent of instance churn; their membership is
+what is reconciled against UFM. To remove a partition entirely, every
+instance referencing it must release first, then `DeleteIbPartition` will
+succeed.
+
+---
+
+## Configuration Workflow
+
+### Operator (per site)
+
+1. Stand up UFM per the [InfiniBand Setup runbook](../../playbooks/ib_runbook.md).
+   Confirm `default_membership = limited`, M_Key / SA_Key hardening, and
+   any required static topology configuration.
+2. Provision a UFM API user with permission to read ports / partitions
+   and to create / update / delete partitions. Store its credentials in
+   the secrets backend.
+3. In the NICo API server config:
+   - Set `[ib_config].enabled = true` and any fabric-wide MTU / rate /
+     service-level defaults.
+   - For each fabric, define `[ib_fabrics.<name>]` with the UFM
+     endpoint(s) and one or more `pkeys` ranges. Size the ranges with
+     room for future growth.
+4. Restart the API server. The `IbFabricMonitor` begins its periodic
+   reconciliation on the next tick.
+
+### Tenant (per partition)
+
+1. `CreateIbPartition` for each isolation domain the tenant needs
+   (typically one per workload).
+2. On `UpdateInstanceConfig`, attach each IB interface to the
+   appropriate `ib_partition_id`.
+3. Wait for `configs_synced.infiniband = true` to converge.
+
+---
+
+## Verification
+
+NICo does not ship a single "is IB healthy" command. Verification is a
+short, repeatable checklist.
+
+1. **UFM is reachable.** Check the API server log for "Failed to create
+   UFM client" or similar startup errors. Confirm
+   `carbide_ib_monitor_iteration_latency` is being recorded (the monitor
+   is running) and that UFM error counters are flat.
+2. **Configured partitions exist in UFM.** Run `nico-admin-cli ib_partition
+   show` (with `--id`, `--tenant-org-id`, or `--name` filters as needed)
+   and confirm each partition is in a converged tenant state. The state
+   machine outcome field surfaces UFM sync failures.
+3. **Host is a member of the expected partitions.** Inspect the
+   machine's `infiniband_status_observation` via the machine debug
+   tooling and confirm each managed port reports membership in the
+   intended P_Key. Cross-check with the live UFM partition table for
+   the same partition.
+4. **No anomalies in the monitor metrics.**
+   `carbide_ib_monitor_machines_with_missing_pkeys_count` and
+   `carbide_ib_monitor_machines_with_unexpected_pkeys_count` should both
+   be `0` in steady state. Either being non-zero is a divergence between
+   intent and UFM state and warrants investigation.
+5. **No outstanding cleanup.** Confirm no managed machine has an
+   `IbCleanupPending` alert.
+
+---
+
+## Limitations Worth Knowing
+
+The IB integration is in production but with the following gaps:
+
+- **Single-endpoint UFM today.** Only the first entry in `endpoints` is
+  used at runtime. UFM HA is handled by UFM itself (virtual IP / HA
+  pair); the multi-endpoint config field exists for forward
+  compatibility.
+- **P_Key ranges are append-only in practice.** Restarting with a
+  narrowed range under live partitions is unsafe; ranges should only
+  grow.
+- **No tenant-facing UFM-reachability probe.** Operators rely on
+  metrics and log lines rather than a `ping`-style health command.
+- **SHARP, index-0, and default-membership knobs are not yet wired.**
+  The model has fields reserved for these but they are not honoured by
+  the integration.
+- **UFM error taxonomy is incomplete.** Some UFM failure modes surface
+  as a generic error in the API server log. Distinguishing transient
+  network issues from misconfiguration may require correlating against
+  UFM-side logs.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Instance never leaves `Configuring`; `configs_synced.infiniband = false` | UFM unreachable, host port `Down` or `Initialize`, or PKey allocation pending |
+| `CreateIbPartition` fails with PKey-allocation error | `[ib_fabrics.<name>].pkeys` pool exhausted; extend the ranges |
+| `CreateIbPartition` with an explicit `pkey` rejected | Requested PKey falls in an auto-allocate range or is already in use |
+| `carbide_ib_monitor_machines_with_unexpected_pkeys_count > 0` | Host is in a partition no instance config asks for; out-of-band UFM edit or a stale binding the monitor will clean up |
+| `carbide_ib_monitor_machines_with_missing_pkeys_count > 0` | Desired binding has not (yet) been applied to UFM; check UFM error counters and monitor latency |
+| `IbCleanupPending` alert does not clear | Monitor cannot remove a GUID from a partition (UFM error, or the binding sits outside any NICo-managed range); inspect UFM-side state directly |
+| `DeleteIbPartition` fails | At least one instance still references the partition |
+| Default partition reports full membership on managed ports | UFM hardening incomplete; revisit `default_membership = limited` in the IB runbook |
diff --git a/docs/manuals/networking/network_security_groups.md b/docs/manuals/networking/network_security_groups.md
new file mode 100644
index 0000000000..91d307b79d
--- /dev/null
+++ b/docs/manuals/networking/network_security_groups.md
@@ -0,0 +1,338 @@
+# Network Security Groups
+
+Network Security Groups (NSGs) are tenant-owned, rule-based filters that sit
+on top of the VPC / VRF model. They provide stateful or stateless L3 / L4
+filtering for traffic into and out of tenant instances, complementing the
+routing isolation that the VPC itself provides.
+
+This page describes the NSG object model, how rules are attached to traffic,
+how the operator enables and constrains the feature, and how to verify and
+troubleshoot rule enforcement.
+
+**Related pages**
+
+- [Network Isolation Overview](../network_isolation.md)
+- [Ethernet Isolation](ethernet_isolation.md) — the routing / VRF / segment
+  layer that NSGs sit on top of
+- [VPC Network Virtualization](../vpc/vpc_network_virtualization.md) — VPC,
+  VRF, and DPU configuration mechanics
+
+---
+
+## Where NSGs Sit in the Stack
+
+A tenant's traffic on a NICo-managed host passes through three independent
+isolation layers in order:
+
+1. **VPC / VRF.** The DPU places each interface into the VRF of the VPC
+   whose VpcPrefix the interface draws its /31 from. Routes do not leak
+   between VRFs unless an operator opts in via routing-profile flags or
+   VPC peering.
+2. **`deny_prefixes` site ACL.** The site-wide `deny_prefixes` list,
+   configured under the API server's networking config, blocks tenant
+   traffic to a fixed set of prefixes (typically management plane and
+   infrastructure). This applies to every VRF on every DPU and cannot be
+   overridden by a tenant.
+3. **Network Security Groups.** Per-VPC and per-instance rule sets, set by
+   the tenant, with optional site-wide operator overrides inserted ahead of
+   tenant rules.
+
+NSGs are the right tool for filtering East-West traffic *inside* a VPC, for
+restricting which underlay-leaked prefixes a tenant is permitted to reach,
+and for enforcing site-wide baselines (operator overrides) that no tenant
+can disable. They are not a substitute for VPC routing isolation: an NSG
+cannot make two VPCs reachable that the routing profile keeps apart.
+
+---
+
+## The Rule Model
+
+An NSG is a tenant-owned object with the following shape:
+
+| Field | Purpose |
+|---|---|
+| `id` | NSG identifier, returned at creation |
+| `tenant_organization_id` | The owning tenant |
+| `stateful_egress` | When `true`, return traffic for egress flows is permitted automatically. Requires the site-level `stateful_acls_enabled` flag (see below) |
+| `rules` | Ordered list of `NetworkSecurityGroupRule` entries, evaluated by priority |
+| `version` | Optimistic-concurrency token; required for `UpdateNetworkSecurityGroup` |
+
+Each rule has:
+
+| Field | Allowed values |
+|---|---|
+| `direction` | `Ingress` or `Egress` |
+| `ipv6` | `true` for IPv6 rules, `false` for IPv4 (split into two policies on the DPU) |
+| `protocol` | `Any`, `Icmp`, `Icmp6`, `Udp`, `Tcp` |
+| `src_net` / `dst_net` | A CIDR prefix (the wire model is `NetworkSecurityGroupRuleNet::Prefix(IpNetwork)`) |
+| `src_port_start` / `src_port_end` | Optional inclusive source port range |
+| `dst_port_start` / `dst_port_end` | Optional inclusive destination port range |
+| `action` | `Permit` or `Deny` |
+| `priority` | Integer; lower numbers evaluated first inside a policy |
+
+Rules are evaluated in priority order. The first matching `Permit` or
+`Deny` decides the packet; there is no implicit fall-through behaviour
+between rules of the same NSG.
+
+---
+
+## Attaching an NSG
+
+NSGs attach at exactly two scopes:
+
+- **VPC scope.** Set `network_security_group_id` on the VPC via
+  `UpdateVpc` (admin-cli: `vpc update`). Every instance that has interfaces
+  in this VPC inherits the NSG's rules.
+- **Instance scope.** Set `network_security_group_id` on the instance via
+  `UpdateInstanceConfig` (admin-cli: `instance update`). The instance NSG
+  **replaces** the VPC NSG for that instance. Instance-scope NSGs are not
+  merged with VPC-scope NSGs; the instance-scope NSG wins outright.
+
+An NSG can be referenced by multiple VPCs and multiple instances
+concurrently. `NetworkSecurityGroupAttachments` (returned by the
+attachments-listing RPC) reports the full set of references for a given
+NSG ID.
+
+Attaching, detaching, or updating an NSG triggers reconciliation: the new
+rule set is pushed to every DPU whose instances are affected, and each DPU
+reports `NetworkSecurityGroupPropagationStatus` back to NICo. The
+instance's `configs_synced.ethernet` field gates the `Ready` state on
+this propagation completing.
+
+### Deletion
+
+`DeleteNetworkSecurityGroup` succeeds only when the NSG is not referenced
+by any VPC or instance. The expected workflow is:
+
+1. Detach the NSG from any VPCs (via `UpdateVpc` with the field cleared).
+2. Detach the NSG from any instances (via `UpdateInstanceConfig`).
+3. Wait for `configs_synced` to converge on the affected instances.
+4. Issue `DeleteNetworkSecurityGroup`.
+
+---
+
+## DPU Enforcement
+
+NSG rules are resolved on the API server and pushed to the DPU as part of
+the per-interface configuration response, alongside the VRF, segment, and
+routing-profile data described in
+[VPC Network Virtualization](../vpc/vpc_network_virtualization.md). The DPU
+agent materialises them into NVUE ACLs.
+
+The DPU receives, per interface:
+
+- The resolved rule set (already expanded across port and prefix ranges).
+- A `source` tag (`NSG_SOURCE_NONE`, `NSG_SOURCE_VPC`, or
+  `NSG_SOURCE_INSTANCE`) indicating which scope produced the rules.
+- The `stateful_egress` flag.
+- The NSG `id` and `version`, used by the propagation-status reporting.
+
+The agent renders IPv4 and IPv6 rules into separate NVUE policies and
+combines ingress and egress rules into the appropriate direction. Site-wide
+operator overrides (see below) are rendered into a **separate policy** that
+the DPU evaluates **before** any tenant policy.
+
+---
+
+## Site-Level Operator Configuration
+
+The operator controls three site-wide knobs that affect NSG behaviour.
+These live in the API server configuration file under
+`[network_security_group]`:
+
+```toml
+[network_security_group]
+# Hard cap on the number of expanded rules per NSG.
+# Expansion = src port range × dst port range × src prefix list × dst prefix list.
+max_network_security_group_size = 200
+
+# Master switch for stateful (reflexive) ACL support.
+# Leave disabled until every DPU in the site is running HBN 2.3 or later.
+stateful_acls_enabled = false
+
+# Site-wide override rules. Inserted into a separate policy on the DPU
+# that is evaluated AFTER deny_prefixes but BEFORE any tenant NSG rules.
+# A tenant cannot disable or contradict these.
+policy_overrides = []
+```
+
+### `max_network_security_group_size`
+
+NICo expands rule entries before pushing them to the DPU (the cartesian
+product of source ports × destination ports × source prefixes × destination
+prefixes). This cap is the operator's protection against a tenant
+accidentally requesting a vast rule set. The DPU agent also enforces its
+own ceiling, on the order of 10,000 expanded rules, as a final safeguard.
+
+A tenant whose NSG would expand beyond this limit receives an error from
+`CreateNetworkSecurityGroup` or `UpdateNetworkSecurityGroup`. Tune this
+value if tenants legitimately need larger rule sets; do not raise it
+unilaterally without coordinating with whatever ceiling is configured on
+the DPU side.
+
+### `stateful_acls_enabled`
+
+Toggling this flag controls whether NICo will configure the DPU's default
+stateful-ACL options in the NVUE config it pushes. Stateful NSG behaviour
+also requires the tenant to set `stateful_egress = true` on the NSG;
+without the site-level switch, the DPU treats every rule as stateless
+regardless of the per-NSG flag.
+
+Leave `stateful_acls_enabled = false` until every DPU in the site is
+running HBN 2.3 or later. Earlier HBN versions implement reflexive ACLs in
+a way that lets a single rule permit traffic in both directions, which is
+operationally unsafe.
+
+### `policy_overrides`
+
+`policy_overrides` is a list of `NetworkSecurityGroupRule` entries (same
+shape as tenant rules) that the operator wishes to enforce site-wide.
+
+These rules are inserted into a **separate policy** on the DPU, evaluated:
+
+1. **After** `deny_prefixes` (the absolute site denylist).
+2. **Before** any tenant-defined NSG rules.
+
+This ordering gives the operator a reliable place to:
+
+- Force-permit infrastructure flows (for example, package mirrors,
+  telemetry collectors, time servers) that every tenant must be able to
+  reach, without depending on each tenant putting them in their own NSG.
+- Force-deny baselines that every tenant must obey, regardless of what
+  their own NSGs say. A tenant cannot write a `Permit` rule that
+  contradicts an operator override, because the override is evaluated
+  first and decides the packet.
+
+Each entry follows the same JSON / TOML structure as a tenant rule. A
+worked example:
+
+```toml
+[network_security_group]
+stateful_acls_enabled = false
+max_network_security_group_size = 200
+
+  [[network_security_group.policy_overrides]]
+  direction = "Egress"
+  ipv6 = false
+  protocol = "Udp"
+  dst_net = "10.0.5.0/24"          # site-controller VIPs
+  dst_port_start = 123
+  dst_port_end = 123
+  action = "Permit"
+  priority = 10
+
+  [[network_security_group.policy_overrides]]
+  direction = "Egress"
+  ipv6 = false
+  protocol = "Tcp"
+  dst_net = "0.0.0.0/0"
+  dst_port_start = 22
+  dst_port_end = 22
+  action = "Deny"
+  priority = 20
+```
+
+Changing `policy_overrides` requires restarting the API server (it is a
+static configuration field, not a runtime-mutable RPC). After restart, the
+new override set propagates to every DPU as part of the next
+configuration-poll cycle.
+
+---
+
+## Quarantine and Forced Override
+
+When a managed host is placed into a quarantine lifecycle state, NICo
+substitutes a quarantine-specific override policy in place of
+`policy_overrides`. The intent is to give an operator a way to constrain
+traffic from a host that is under investigation without having to detach
+it from its tenant VPCs first. This is internal behaviour and is not
+operator-configurable; quarantine is driven by the machine lifecycle and
+health-alert subsystem.
+
+---
+
+## Current Limitations
+
+The NSG feature is in production use, but the following limitations are
+worth knowing before designing rule sets:
+
+- **Rule `src_net` / `dst_net` accept CIDR prefixes only.** The model has
+  a structural extension point for VPC references (so that a tenant could
+  say "permit from any instance in VPC X"), but VPC-reference resolution
+  is not yet implemented. Use explicit CIDRs.
+- **IPv4 and IPv6 are separate rules.** A rule has an `ipv6` boolean and
+  applies only to one address family; if a tenant needs both, two rules
+  are required.
+- **`stateful_egress` requires the site flag.** A tenant may set
+  `stateful_egress = true` on the NSG, but it has no effect until the
+  site-level `stateful_acls_enabled = true`.
+- **Updates require version-token agreement.** `UpdateNetworkSecurityGroup`
+  takes the NSG's `version` and fails if it has been concurrently modified.
+  This is the standard NICo optimistic-concurrency pattern.
+
+---
+
+## Configuration Workflow
+
+The site operator's NSG configuration is normally done once and rarely
+changed; the tenant flow is what runs day-to-day.
+
+### Operator (once per site)
+
+1. Confirm the HBN version on every DPU in the site. If any DPU is on a
+   version earlier than HBN 2.3, leave `stateful_acls_enabled = false`.
+2. Decide the rule-size budget per NSG and set
+   `max_network_security_group_size` accordingly.
+3. Decide what baseline traffic must be permitted (telemetry, NTP, package
+   mirrors) and what baseline must be denied (operator-defined denylist
+   that goes beyond `deny_prefixes`). Encode these as
+   `policy_overrides`.
+4. Restart the API server.
+
+### Tenant (per NSG)
+
+1. `CreateNetworkSecurityGroup` with the desired rule set. The response
+   includes the NSG `id` and `version`.
+2. Attach the NSG either at VPC scope (`UpdateVpc`) or instance scope
+   (`UpdateInstanceConfig`).
+3. Wait for the affected instances to report
+   `configs_synced.ethernet = true`.
+
+Updates use `UpdateNetworkSecurityGroup` with the current `version` token.
+Deletion uses `DeleteNetworkSecurityGroup` after detaching every reference.
+
+---
+
+## Verification
+
+For a given tenant configuration, confirm:
+
+1. **NSG exists and is the expected version.**
+   `admin-cli network-security-group show <id>` shows the rules,
+   `stateful_egress`, and current `version`.
+2. **The NSG is attached where intended.** Use the attachments-listing
+   RPC (or `admin-cli network-security-group attachments <id>`) to confirm
+   the set of VPCs and instances that reference the NSG.
+3. **Per-instance propagation has converged.**
+   `admin-cli instance show <id>` reports `configs_synced.ethernet = true`.
+   While propagation is in flight, the instance's tenant state shows
+   `Configuring`.
+4. **Operator overrides are present site-wide.** On any active DPU,
+   inspect the running NVUE ACL configuration; the override policy is
+   distinct from the tenant policy and contains the rules listed in the
+   API server's `policy_overrides`. A discrepancy means the API server
+   was not restarted after the configuration change.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `CreateNetworkSecurityGroup` fails with size-limit error | Expanded rule count exceeds `max_network_security_group_size` |
+| Stateful return traffic is being dropped | `stateful_acls_enabled = false` site-wide, or `stateful_egress = false` on the NSG, or DPU on HBN earlier than 2.3 |
+| Tenant rule that "should permit" a flow has no effect | An operator `policy_overrides` rule denies the same flow at higher (earlier-evaluated) priority |
+| Two instances in the same VPC cannot reach each other on a permitted port | NSG attached only to one side, or the NSG attached at instance scope overrides the VPC-scope NSG |
+| `DeleteNetworkSecurityGroup` fails | At least one VPC or instance still references the NSG; see attachments listing |
+| Site-wide override change does not take effect | API server was not restarted after editing `policy_overrides` |
+| Per-instance `configs_synced.ethernet = false` after NSG change | NSG propagation has not yet reached the DPU, or the DPU is reporting an error in `NetworkSecurityGroupPropagationStatus` |
diff --git a/docs/manuals/nvlink_partitioning.md b/docs/manuals/nvlink_partitioning.md
index a363a81ae8..fb5bf5446d 100644
--- a/docs/manuals/nvlink_partitioning.md
+++ b/docs/manuals/nvlink_partitioning.md
@@ -84,6 +84,115 @@ If you want finer control, leave `nvLinkLogicalPartitionId` unset on the VPC and
 | VPC doesn't have `nvLinkLogicalPartitionId` set, Instance specifies `nvLinkInterfaces` | Per-GPU NVLink Logical Partition assignments are used |
 | Same `nvLinkLogicalPartitionId` on multiple VPCs | Allowed — no implicit exclusivity |
 
+### How NICo Reconciles NVLink State
+
+NICo runs a periodic reconciler against NMX-M and NMX-C to keep the actual
+NVLink partition topology aligned with the desired state implied by tenant
+instance configurations. The behaviour matters whenever an operator is
+diagnosing latency between an API call and an instance becoming `Ready`.
+
+Each reconciliation pass does the following:
+
+1. Loads every NVLink Logical Partition and every NVLink Physical Partition
+   from the NICo database.
+2. Queries each configured NMX-M and / or NMX-C endpoint for the current
+   partition list and GPU membership on that endpoint's chassis or domain.
+3. Compares observed state against desired state.
+4. Issues create / update / remove operations to the fabric-management
+   service to converge it onto desired state.
+5. Updates per-machine GPU status observations in the NICo database. The
+   per-instance `configs_synced.nvlink` field is derived from these
+   observations and is what gates the instance's `Ready` state.
+
+Cadence is set by `nvlink_config.monitor_run_interval` (default `60s`).
+
+The reconciler exposes metrics under the
+`carbide_nvlink_partition_monitor_*` namespace. Useful ones:
+
+| Metric | Use |
+|---|---|
+| `carbide_nvlink_partition_monitor_iteration_latency` | Time per reconcile pass |
+| `carbide_nvlink_partition_monitor_nmxc_op_latency` | Per-operation latency against NMX-C |
+| `carbide_nvlink_partition_monitor_nmxc_changes_applied` | Counter of changes issued; nonzero in steady state is an anomaly |
+| `carbide_nvlink_partition_monitor_nmxc_connect_error_count` | Connection failures to any NMX-C endpoint |
+| `carbide_nvlink_partition_monitor_nmxm_connect_error_count` | Connection failures to NMX-M |
+| `carbide_nvlink_partition_monitor_num_logical_partitions` | Logical-partition count NICo is tracking |
+| `carbide_nvlink_partition_monitor_num_physical_partitions` | Physical-partition count NICo is tracking |
+| `carbide_nvlink_partition_monitor_nmxc_partition_count` | Partition count NMX-C reports |
+| `carbide_nvlink_partition_monitor_nmxc_gpu_count` | GPU count NMX-C reports across managed partitions |
+
+### Instance Release and Logical Partition Deletion
+
+When an instance is released (via `ReleaseInstance`):
+
+1. The instance's NVLink configuration is cleared from the database.
+2. The reconciler observes that GPUs previously assigned to the instance
+   are no longer requested in any live partition.
+3. The reconciler removes those GPUs from their NMX-M / NMX-C partitions.
+4. Once all NVLink state is removed, the machine's GPU status observation
+   reflects an empty domain assignment and the host becomes eligible for
+   reuse.
+
+When a Logical Partition is deleted, every underlying NVLink Physical
+Partition on each NMX-M / NMX-C endpoint backing it is also deleted. The
+deletion is rejected if any instance still references the Logical
+Partition.
+
+When a host is force-deleted, the instance running on it is implicitly
+released and the above cleanup path runs. Operators do not need to detach
+NVLink configuration manually before force-deleting.
+
+### Enabling NMX-C-based NVLink Partitioning
+
+NMX-C is the gRPC control path for NVLink partition management and is the
+current default for new deployments. NMX-M remains supported and is
+covered in the next section; the two are not mutually exclusive and a
+single site may use both.
+
+The TOML toggles live alongside the NMX-M ones under `[nvlink_config]`:
+
+```toml
+[nvlink_config]
+enabled = true
+monitor_run_interval = "60s"
+
+# Optional TLS material for NMX-C. Leave unset to use the system trust
+# store and present no client certificate.
+nmx_c_tls_ca_cert_path     = "/etc/nico/nmxc/ca.pem"
+nmx_c_tls_client_cert_path = "/etc/nico/nmxc/client.crt"
+nmx_c_tls_client_key_path  = "/etc/nico/nmxc/client.key"
+nmx_c_tls_authority        = "nmxc.example.internal"
+
+allow_insecure = false
+```
+
+| Field | Purpose |
+|---|---|
+| `nmx_c_tls_ca_cert_path` | Optional PEM containing additional CAs for verifying the NMX-C endpoint's certificate |
+| `nmx_c_tls_client_cert_path` | Optional client certificate for mTLS to NMX-C |
+| `nmx_c_tls_client_key_path` | Optional client key matching the certificate above |
+| `nmx_c_tls_authority` | Optional override for the expected server name during certificate verification (SNI / hostname check) |
+| `allow_insecure` | When `true`, disables TLS verification entirely. Intended for development |
+
+Unlike NMX-M, where a single endpoint URL is set in TOML, NMX-C endpoints
+are **per-chassis** and stored in the NICo database. Register them with
+`nico-admin-cli`, keyed by the chassis serial:
+
+```bash
+nico-admin-cli nvlink-nmxc-endpoints create \
+    --chassis-serial <serial> \
+    --endpoint https://nmxc-host:443
+
+nico-admin-cli nvlink-nmxc-endpoints show
+```
+
+`update` and `delete` subcommands follow the same pattern. The reconciler
+picks up new endpoints on the next iteration; no restart is required.
+
+The TLS material in TOML applies uniformly to every NMX-C endpoint NICo
+talks to. Per-endpoint credential overrides are not currently supported;
+deploy a uniform trust posture across the site's NMX-C control plane.
+
 ### Enabling NMX-M-based NVLink Partitioning
 
 This section describes how to enable NVLink support via the [NMX-M platform](https://docs.nvidia.com/networking/display/nmxmv8513000).
@@ -133,3 +242,42 @@ This section describes how to enable NVLink support via the [NMX-M platform](htt
     * carbide-core logs should not show "Failed to create NMXM client".
     * Logs should not show failures getting NMX-M partitions or GPU list.
     * Metrics show that `carbide_nvlink_partition_monitor_nmxm_connect_error_count` is `0`.
+
+### Verifying a Tenant's NVLink Placement
+
+After an instance has been created and the reconciler has had at least one
+opportunity to run, an operator can confirm correct placement with the
+following checks. There is no single all-in-one health command; the steps
+below should be repeatable as a checklist.
+
+1. **Reconciler is running.**
+   `carbide_nvlink_partition_monitor_iteration_latency` is being recorded
+   and both `carbide_nvlink_partition_monitor_nmxc_connect_error_count`
+   and `carbide_nvlink_partition_monitor_nmxm_connect_error_count` are
+   flat.
+2. **Logical-partition count matches expectation.**
+   `carbide_nvlink_partition_monitor_num_logical_partitions` reflects
+   the partitions a site planner expects to exist. A sudden change is
+   worth correlating with recent tenant API activity.
+3. **Per-instance configuration has converged.** The instance's
+   `InstanceStatus` reports `configs_synced.nvlink = true` and the
+   `nvLinkInterfaces` list on the instance shows the expected
+   `nvLinkLogicalPartitionId` and `nvLinkDomainId` for each GPU.
+4. **Per-machine GPU placement.**
+
+    ```
+    carbide-admin-cli machine nvlink-info --machine-id <machine-id>
+    ```
+
+    Returns the machine's NVLink GPU status observations, including the
+    Domain each GPU is currently assigned to. Use this to confirm that
+    two instances expected to share an NVLink Logical Partition have
+    actually landed in the same NVLink Domain — instances in different
+    Domains cannot share GPU memory regardless of having the same
+    Logical Partition ID.
+5. **Cleanup after release.** After releasing an instance, the same
+   `machine nvlink-info` output should show an empty Domain assignment
+   on the affected GPUs within one or two reconcile intervals. Failure
+   to clear indicates the reconciler could not remove the GPU from its
+   NMX-M / NMX-C partition; investigate the corresponding connect-error
+   and op-latency metrics.
diff --git a/docs/manuals/vpc/vpc_network_virtualization.md b/docs/manuals/vpc/vpc_network_virtualization.md
index d95945e9d1..9a80523190 100644
--- a/docs/manuals/vpc/vpc_network_virtualization.md
+++ b/docs/manuals/vpc/vpc_network_virtualization.md
@@ -130,6 +130,59 @@ the instance as ready only after the DPU confirms the configuration has been app
 
 ---
 
+## Default Isolation: The Admin Overlay
+
+NICo guarantees that a managed host never carries tenant traffic unless an explicit tenant
+configuration places it into a VPC. A "default VPC" in the cloud-provider sense — a system-created
+VPC that every tenant inherits — does not exist. Tenants get the VPCs an operator (or the tenant
+API) creates for them; absent any such VPC, an instance has no place to send tenant traffic.
+
+The guarantee is upheld by an **admin overlay** that is separate from every tenant VPC, and by a
+fail-closed default when no configuration is available at all.
+
+### The admin VPC and admin segments
+
+During site initialisation NICo creates an admin VPC together with a set of admin network
+segments. These are not tenant-visible and exist only to give the DPU somewhere safe to attach a
+host before, between, and after tenant allocations. The admin VPC follows the same VPC / VRF
+mechanics as any tenant VPC — it has its own VRF on each DPU, its own VNI, and its own routing
+profile — but it is reserved for NICo's own use.
+
+### `use_admin_network`
+
+When the API server assembles `ManagedHostNetworkConfig` for a DPU, it sets
+`use_admin_network = true` whenever any of the following hold:
+
+- The host has no instance allocated.
+- The instance has no interfaces configured for this DPU.
+- The host is in a transient lifecycle state (provisioning, repair, termination) in which tenant
+  traffic must not flow.
+
+With `use_admin_network = true` the DPU agent places every host interface into the admin VRF
+instead of any tenant VPC's VRF. From the wire's perspective, the host is on the admin overlay
+and cannot exchange traffic with any tenant instance.
+
+### Isolated mode (fail-closed)
+
+A DPU that cannot retrieve its configuration at all — for example, because the host is unknown to
+NICo and `GetManagedHostNetworkConfig` returns `NOT_FOUND` — places itself into **isolated
+mode**: every host interface is detached from any overlay until NICo issues an explicit
+configuration. This is the fail-closed default. Nothing in the data path silently falls back to a
+tenant network.
+
+### Termination guard
+
+The instance state machine blocks the termination flow until the DPU confirms that all tenant
+interfaces have been moved off tenant VPCs and onto the admin overlay (or that the machine has
+been tagged with a health alert preventing reuse). This is what guarantees that a tenant whose
+instance has been released cannot remain on the wire as a "ghost instance" pending disk wipe.
+
+For the per-fabric isolation story across Ethernet, InfiniBand, and NVLink, see
+[Network Isolation](../network_isolation.md) and
+[Ethernet Isolation](../networking/ethernet_isolation.md).
+
+---
+
 ## Intra-VPC Connectivity
 
 Instances in the same VPC communicate via the VPC VRF on each DPU. No operator configuration