Complete typed map ergonomics and preview API

README.md

@@ -9,6 +9,7 @@ This library is intentionally narrow.
 - High-level managed API:
   - typed `NftRuleset` / `NftTable` / `NftSet` / `NftMap` / `NftChain` / `NftRule` authoring
   - `RenderRuleset`
+  - `ValidateAndRenderRuleset`
   - `ValidateRuleset`
   - `ApplyRuleset`
   - `Snapshot`
@@ -114,6 +115,55 @@ if (validation.IsValid)
 
 Raw command text remains available through `NftApplyRequest` as a fallback for nft syntax not yet modeled by the typed API.
 
+## Supported Typed Subset
+
+The typed API currently supports this subset directly:
+
+- Sets with typed values for IPv4/IPv6 addresses and CIDRs, ports/services, interface names, marks, and raw literals.
+- Maps declared and populated inline, authored through dictionary-style helpers on `NftMap`.
+- Chains with typed base-chain metadata: type, hook, priority, and policy.
+- Common firewall rules:
+  - source/destination address matches
+  - source/destination port matches
+  - input/output interface matches
+  - set membership matches
+  - verdicts: accept, drop, reject, jump
+
+Use `NftApplyRequest` as the fallback when you need:
+
+- nft features outside the current typed subset
+- live map mutation commands
+- custom map key/value type expressions with non-raw typed values
+- snapshot parsing back into typed object models
+- full nft expression parity
+
+## Map Authoring Example
+
+```csharp
+var map = new NftMap
+{
+    Name = "service_policy",
+    KeyType = NftMapType.InetService,
+    ValueType = NftMapType.Verdict,
+};
+
+map.Add(NftValue.Port(80), NftValue.Verdict(NftVerdict.Accept));
+map.Add(NftValue.Port(443), NftValue.Verdict(NftVerdict.Drop));
+```
+
+Entries are rendered in insertion order. Duplicate keys are rejected by `NftMap.Add`. Use `NftMap.Set` to replace an existing key without changing its order.
+
+## Validate-And-Render Example
+
+```csharp
+NftRenderedValidationResult preview = client.ValidateAndRenderRuleset(ruleset);
+
+if (preview.ValidationResult.IsValid)
+{
+    client.ApplyRuleset(ruleset);
+}
+```
+
 ## Low-Level Example
 
 ```csharp
@@ -153,7 +203,7 @@ Some operations require elevated privileges or `CAP_NET_ADMIN`, especially when
 
 ### Validation failures
 
-`ValidateRuleset` returns `IsValid = false` for invalid nft syntax after rendering the typed model. `ApplyRuleset` and `Restore` throw when the typed/request shape is invalid or native parsing fails.
+`ValidateRuleset` and `ValidateAndRenderRuleset` return `IsValid = false` for invalid nft syntax after rendering the typed model. `ApplyRuleset` and `Restore` throw when the typed/request shape is invalid or native parsing fails.
 
 ## Bindings and Regeneration