defaults: built-in baseline is dual-stack (IPv6 + IPv4), not IPv6-only

BuiltinFamilyDefaults() now returns {WantV6: true, WantV4: true}. Pods
that want a single family explicitly opt out via the
flock.fritzlab.net/ipv4 (or ipv6) annotation, or the operator narrows
the default at the node level via NodeConfig.Spec.Defaults.

Annotation precedence is unchanged: pod annotation > NodeConfig defaults
> built-in baseline. Tests updated to reflect the new baseline; the
"opt out of v4" path now has explicit coverage.

Docs updated:
  - NodeConfig.Spec.Defaults Go doc + CRD descriptions reflect the new
    baseline and its overrides
  - README opening framing softened from "IPv6-first" to "dual-stack,
    IPv6-friendly"; example pods + spec.defaults table flipped to
    treat dual-stack as the default and v6/v4-only as overrides
  - README NetworkPolicy line in the comparison table flipped to
    "yes (nftables)" since v1 enforcement shipped
  - Limitations note about IPv4-only destinations rewritten — every
    pod has v4 by default now, so the question is whether your IPv4
    pool is routable beyond your network

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

pkg/agent/annotations_test.go

@@ -13,8 +13,8 @@ func boolPtr(b bool) *bool { return &b }
 
 func TestBuiltinFamilyDefaults(t *testing.T) {
 	d := BuiltinFamilyDefaults()
-	if !d.WantV6 || d.WantV4 {
-		t.Fatalf("built-in defaults wrong: v6=%v v4=%v (want true/false)", d.WantV6, d.WantV4)
+	if !d.WantV6 || !d.WantV4 {
+		t.Fatalf("built-in defaults wrong: v6=%v v4=%v (want dual-stack true/true)", d.WantV6, d.WantV4)
 	}
 }
 
@@ -37,14 +37,16 @@ func TestFamilyDefaultsFromNodeConfig_PartialOverride(t *testing.T) {
 	nc := &flockv1alpha1.NodeConfig{
 		Spec: flockv1alpha1.NodeConfigSpec{
 			Defaults: &flockv1alpha1.FamilyDefaults{
-				IPv4: boolPtr(true),
+				IPv4: boolPtr(false),
 			},
 		},
 	}
 	d := FamilyDefaultsFromNodeConfig(nc)
-	// IPv6 was unset → keeps built-in true; IPv4 was set → flipped on.
-	if !d.WantV6 || !d.WantV4 {
-		t.Fatalf("partial override wrong: %+v (want v6=true, v4=true)", d)
+	// IPv6 unset → keeps built-in true; IPv4 explicitly set to false →
+	// node opts the family off. Validates that an explicit false beats
+	// the dual-stack baseline rather than being silently overridden.
+	if !d.WantV6 || d.WantV4 {
+		t.Fatalf("partial override wrong: %+v (want v6=true, v4=false)", d)
 	}
 }
 
@@ -64,12 +66,27 @@ func TestFamilyDefaultsFromNodeConfig_FullOverride(t *testing.T) {
 }
 
 func TestParseAnnotations_BuiltinDefaults(t *testing.T) {
+	// Built-in baseline is dual-stack — no annotation needed.
 	a, err := ParseAnnotations(nil, BuiltinFamilyDefaults())
 	if err != nil {
 		t.Fatal(err)
 	}
+	if !a.WantV6 || !a.WantV4 {
+		t.Fatalf("expected dual-stack default, got v6=%v v4=%v", a.WantV6, a.WantV4)
+	}
+}
+
+// TestParseAnnotations_OptOutV4 — pods that want IPv6 only must opt out
+// explicitly via the ipv4 annotation now that the built-in is dual-stack.
+func TestParseAnnotations_OptOutV4(t *testing.T) {
+	a, err := ParseAnnotations(map[string]string{
+		annotationPrefix + "ipv4": "false",
+	}, BuiltinFamilyDefaults())
+	if err != nil {
+		t.Fatal(err)
+	}
 	if !a.WantV6 || a.WantV4 {
-		t.Fatalf("defaults wrong: v6=%v v4=%v", a.WantV6, a.WantV4)
+		t.Fatalf("ipv4=false override failed: v6=%v v4=%v", a.WantV6, a.WantV4)
 	}
 }
 
@@ -100,6 +117,8 @@ func TestParseAnnotations_AnnotationOverridesNodeDefault(t *testing.T) {
 }
 
 func TestParseAnnotations_DualStackViaAnnotation(t *testing.T) {
+	// Same as built-in default; explicit ipv4=true is a no-op now but must
+	// still parse cleanly.
 	a, err := ParseAnnotations(map[string]string{
 		annotationPrefix + "ipv4": "true",
 	}, BuiltinFamilyDefaults())
@@ -112,10 +131,12 @@ func TestParseAnnotations_DualStackViaAnnotation(t *testing.T) {
 }
 
 func TestParseAnnotations_NoFamily(t *testing.T) {
+	// Pod opts out of both families → must be rejected.
 	if _, err := ParseAnnotations(map[string]string{
 		annotationPrefix + "ipv6": "false",
+		annotationPrefix + "ipv4": "false",
 	}, BuiltinFamilyDefaults()); err == nil {
-		t.Fatalf("expected error: ipv6=false ipv4=false")
+		t.Fatalf("expected error when pod opts out of both families")
 	}
 }