NodeConfig defaults + code-quality pass + fuzz tests + README

NodeConfig.Spec.Defaults adds per-node IPv6/IPv4 family defaults that pod
annotations can override; built-in baseline (v6=true, v4=false) still
applies when the field is omitted.

bird.Render now validates every operator-supplied value (peer addresses,
CIDRs, anycast IPs, source addresses) before templating — fuzz found a
peer address containing `}` produced unbalanced braces in bird.conf.
Failing input preserved as a regression seed.

Fuzz targets added for ParseAnnotations, ParseCNIArgs, HostIfaceName,
canonical, IPAM allocate sequences, embed.Embed, and bird.Render.
Hardened canonical/ipToU32 against nil and non-IPv4 inputs.

README rewritten for outside readers — quickstart, NodeConfig + annotation
reference with worked examples, anycast use cases, comparison vs Calico
and Cilium, requirements, limitations.

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

pkg/agent/doc.go

@@ -0,0 +1,22 @@
+// Package agent owns the in-process flock-agent runtime. The agent is a
+// single Linux DaemonSet pod per node and holds:
+//
+//   - the durable per-node allocation file at /var/lib/flock/allocations.json
+//     (see Store in state.go),
+//   - an in-memory IPAM seeded from NodeConfig CIDRs and reconciled against
+//     the allocation file at startup (see ipam.go),
+//   - dynamic informers watching the per-node NodeConfig CR (nodeconfig.go)
+//     and the local-node Pod set (podinfo.go),
+//   - an RPC server speaking to the lightweight CNI plugin binary
+//     (cmd/flock and pkg/cni), so kubelet's CNI invocations are answered by
+//     a long-lived process rather than spinning up a fresh binary per ADD,
+//   - the BirdManager that renders bird.conf and triggers `birdc reload`
+//     on changes (bird.go), and
+//   - the AnycastReconciler that programs per-pod /128 and /32 host routes
+//     gated on Pod readiness (anycast_linux.go).
+//
+// The package is split between platform-specific files (anycast_linux.go,
+// netns_linux.go, runtime_linux.go) and stub files used on non-Linux build
+// hosts so the rest of the package — IPAM, parsing, store, RPC plumbing —
+// stays unit-testable on macOS and Windows CI.
+package agent