Improve testability, packaging, and docs

README.md

@@ -1,6 +1,34 @@
 # libnftables-dotnet
 
-.NET bindings for system-installed `libnftables`, generated with SWIG.
+`libnftables-dotnet` is a command-centric .NET wrapper over system-installed `libnftables`, with low-level SWIG-generated bindings and a small managed API for common workflows.
+
+## Current Scope
+
+This library is intentionally narrow.
+
+- High-level managed API:
+  - `Validate`
+  - `Apply`
+  - `Snapshot`
+  - `Restore`
+- Low-level managed wrapper:
+  - `NftContext` for direct control over flags, buffering, include paths, variables, and command execution
+
+Non-goals for the current release:
+
+- Typed .NET models for tables, chains, rules, sets, or maps
+- Event monitoring or subscriptions
+- Cross-platform support beyond Linux x64
+
+## Runtime Support
+
+Native operations currently support:
+
+- Linux only
+- x64 only
+- System-installed `libnftables`
+
+The package includes the generated Linux x64 native wrapper, but it still depends on the host system providing `libnftables`.
 
 ## Requirements
 
@@ -8,7 +36,9 @@
 - `libnftables` headers and shared library installed
 - `gcc`
 - .NET SDK 10+
-- `swig` (only needed to regenerate bindings)
+- `swig` only if you regenerate bindings
+
+On Debian/Ubuntu-like systems, the runtime dependency is typically installed from the system package repository. Exact package names can vary by distro.
 
 ## Build
 
@@ -16,35 +46,21 @@
 dotnet build
 ```
 
-`dotnet build` compiles the native SWIG wrapper (`libLibNftablesBindings.so`) from checked-in generated C wrapper code.
+`dotnet build` compiles the native SWIG wrapper (`libLibNftablesBindings.so`) from the checked-in generated C wrapper code.
 
-## Regenerate SWIG bindings
+## Test
 
 ```bash
-./eng/regen-bindings.sh
+dotnet test LibNftables.slnx
 ```
 
-## Native wrapper build only
+The test suite contains:
 
-```bash
-./eng/build-native.sh
-```
+- Managed/unit tests that do not require a native runtime
+- Native integration tests that self-gate when `libnftables` is unavailable
+- Capability-dependent tests that only run when `CAP_NET_ADMIN` is available
 
-## Notes
-
-- Native dependency remains system-level `libnftables` (`-lnftables`).
-- Managed APIs:
-  - `NftContext`: advanced low-level context wrapper over native calls.
-  - `INftablesClient` / `NftablesClient`: high-level command-centric API with `Validate`, `Apply`, `Snapshot`, and `Restore` (sync + async).
-- Fail-fast runtime policy: Linux x64 only for native operations.
-
-## Documentation
-
-- High-level managed API XML docs are provided on all public `LibNftables` types/members.
-- Low-level generated binding reference: `docs/low-level-bindings-reference.md`.
-- Generated SWIG files under `src/LibNftables.Bindings/Generated/` are auto-generated and not hand-edited.
-
-## High-level example
+## High-Level Example
 
 ```csharp
 using LibNftables;
@@ -57,3 +73,64 @@ if (validation.IsValid)
     client.Apply(NftApplyRequest.FromText("add table inet my_table"));
 }
 ```
+
+## Low-Level Example
+
+```csharp
+using LibNftables;
+
+using var context = new NftContext();
+context.DryRun = true;
+context.BufferOutput();
+context.BufferError();
+
+context.RunCommand("add table inet demo");
+
+string? output = context.GetOutputBuffer();
+string? error = context.GetErrorBuffer();
+```
+
+## Troubleshooting
+
+### `NftNativeLoadException`
+
+This usually means one of these is missing or incompatible:
+
+- the bundled wrapper `libLibNftablesBindings.so`
+- the host `libnftables` shared library
+- Linux x64 runtime compatibility
+
+### `NftUnsupportedException`
+
+This is expected on:
+
+- non-Linux hosts
+- non-x64 processes
+
+### `NftPermissionException`
+
+Some operations require elevated privileges or `CAP_NET_ADMIN`, especially when interacting with the live ruleset.
+
+### Validation failures
+
+`Validate` returns `IsValid = false` for invalid nft syntax. `Apply` and `Restore` throw when the request shape is invalid or native parsing fails.
+
+## Bindings and Regeneration
+
+- Native wrapper build only:
+
+```bash
+./eng/build-native.sh
+```
+
+- Regenerate SWIG bindings:
+
+```bash
+./eng/regen-bindings.sh
+```
+
+Low-level generated binding reference:
+
+- `docs/low-level-bindings-reference.md`
+
+Generated SWIG files under `src/LibNftables.Bindings/Generated/` are generated artifacts and should not be edited by hand.