chore(docs) Update docs ahead of 1.1.0 release

Author: aenertia

BENCHMARKS.md

@@ -70,7 +70,7 @@ RXNM replaces heavy middleware with a direct, zero-dependency model. DBus-Lite m
 | **Total Disk Size** | **\~300 KB** | \~5.2 MB | \~400 KB | \~18.5 MB | 
 | **Breakdown** | 50KB Agent + 250KB Shell | Binaries + Plugins | Daemon + Scripts | Binaries + JNI | 
 | **Library Sprawl** | **0 Files** (Static) | \~140+ (.so) | \~15+ (.so) | \~65+ (.so) | 
-| **Privilege Model** | **Capabilities (cap_net)** | Root Daemon | Root Daemon | SELinux + Netd | 
+| **Privilege Model** | **Capabilities (cap_sys_admin, cap_net_admin)** | Root Daemon | Root Daemon | SELinux + Netd | 
 | **Immutable Support** | **Native (/run based)** | Challenging | Native | Native (A/B) | 
 
 ---
@@ -177,4 +177,10 @@ While RXNM is optimized for high-performance embedded scenarios, its design phil
 
 RXNM achieves functional parity with the **Android Networking Stack** (eBPF filtering, L2/L3 handoff, firmware-gated init) while maintaining the resource footprint of a minimalist embedded environment. It remains the "Third Way" for high-performance handheld and RISC-V development.
 
+### 📣 Call for Testers & Integrators!
+
+If RXNM's zero-resident, sub-5ms architecture sounds like the right fit for your embedded project, Linux distribution, or specific use case, we would love to hear from you! We are actively looking for integrators to stress-test these capabilities.
+
+*Please note: We track all issues, feature requests, and bug reports through our primary Codeberg repository. (The GitHub mirror is strictly read-only for CI purposes). Head over to Codeberg to join the discussion!*
+
 © 2026-present Joel Wirāmu Pauling

BUILD.md

@@ -48,7 +48,7 @@ Several critical paths have specific fallbacks when preferred tools are absent.
 
 ## 🚀 Build Profiles
 
-RXNM provides three primary compilation targets depending on your deployment constraints.
+RXNM provides four primary compilation targets depending on your deployment constraints.
 
 ### 1. The Standard Build (Dynamic Linking)
 
@@ -58,6 +58,7 @@ Best for desktop development, debugging, or standard glibc-based distributions (
 make
 sudo make install
 
+
 ```
 
 * **Result:** Dynamically linked `rxnm-agent` and modular shell libraries in `/usr/lib/rocknix-network-manager/lib/`.
@@ -72,6 +73,7 @@ Best for standard embedded devices, initramfs, or Alpine/Buildroot environments.
 make tiny
 sudo make install
 
+
 ```
 
 * **Result:** Statically linked `rxnm-agent`.
@@ -89,6 +91,7 @@ This target triggers `scripts/bundle.sh` to forcefully strip out enterprise netw
 ```
 make rocknix-release
 
+
 ```
 
 * **Result:** Outputs exactly two files to the `build/` directory:
@@ -99,6 +102,17 @@ make rocknix-release
 
 * **Validation:** Automatically runs a dedicated bundle fuzzer to ensure the script amalgamation did not introduce syntax errors.
 
+### 4. The Full Combined Bundle
+
+**Target:** Embedded environments requiring Enterprise networking features (Overlay Tunnels, Service Namespaces, VRF, Bond, MPLS stubs) without the filesystem overhead of multiple module files.
+
+```
+make combined-full
+
+```
+
+* **Result:** A single, monolithic script (`build/rxnm-full`) containing the entirety of RXNM's capabilities, paired with the static `build/rxnm-agent`.
+
 ## 🔀 Architecture: Dual Execution Paths (Bash vs. POSIX)
 
 RXNM is uniquely designed to adapt its execution strategy based on the host shell environment. It dynamically selects between two distinct architectural paths at runtime.
@@ -156,6 +170,7 @@ Runs basic linting, binary footprint validation, and Phase 2 Netlink checks.
 ```
 make check
 
+
 ```
 
 ### Full Regression Suite
@@ -165,6 +180,7 @@ Executes the entire local validation matrix (Fuzzing, Consistency, Profiling).
 ```
 make test-all
 
+
 ```
 
 #### Test Matrix Breakdown:
@@ -173,6 +189,10 @@ make test-all
 
 * **Foundation (`test_foundation.sh`):** Validates static linkage, binary size limits (<100KB), and timestamp synchrony.
 
+* **Core Agent (`test_phase2.sh`):** Validates raw Netlink parsing (Interface/IP existence) and experimental module syntax.
+
+* **JSON Querying (`test_query.sh`):** Validates the Agent's `--get` dot-notation data extraction path.
+
 * **Consistency (`test_consistency.sh`):** Strict JSON diffing. Compares the hardware data (IPs, Routes, MACs) extracted by the C-Agent against data parsed by the legacy Shell fallback.
 
 * **Performance (`test_performance.sh`):** Nanosecond latency benchmarking. Ensures the Agent responds in `< 5ms` on average, failing the build if a performance regression occurs.
@@ -181,6 +201,8 @@ make test-all
 
 * **Fuzzing (`test_cli_fuzz.sh` & `test_bundle_fuzz.sh`):** Injects malformed arguments into the CLI dispatcher within an isolated, mocked environment to ensure graceful degradation (no unhandled shell panics).
 
+* **Verification (`verify_release.sh`):** End-to-end integration checks for Service Namespaces (`CLONE_NEWNET`), experimental stub correctness, and pure bash degradation handling.
+
 ### Interoperability Tests (Systemd-Nspawn)
 
 The deepest level of testing spins up isolated OS containers (`systemd-nspawn`) connected via virtual bridges to simulate real-world hotplugging, DHCP convergence, and XDP behavior.
@@ -192,13 +214,14 @@ sudo ./tests/integration/run_interop.sh
 # Test the flat-file ROCKNIX minimal bundle architecture
 sudo ./tests/integration/run_rocknix_interop.sh
 
+
 ```
 
 ## 📂 Installation Paths
 
 `make install` deploys files to standard system paths compliant with FHS and systemd conventions.
 
-> **Security Note:** `rxnm-agent` uses `setns(fd, CLONE_NEWNET)` for namespace and service operations, which requires `CAP_SYS_ADMIN`. It must be run as root or granted the capability (e.g. via `setcap cap_sys_admin+ep`). In `systemd-nspawn` environments, passing `--capability=all` covers this. In production systemd units, consider adding `AmbientCapabilities=CAP_SYS_ADMIN`.
+> **Security Note:** `rxnm-agent` uses `setns(fd, CLONE_NEWNET)` for namespace and service operations, which requires `CAP_SYS_ADMIN` and `CAP_NET_ADMIN`. It must be run as root or granted the capability (e.g. via `setcap cap_sys_admin,cap_net_admin+ep`). In `systemd-nspawn` environments, passing `--capability=all` covers this. In production systemd units, consider adding `AmbientCapabilities=CAP_SYS_ADMIN CAP_NET_ADMIN`.
 
 **Note on the Main Entry Point:** To protect the relative path hierarchy required by the modular library system (and to keep `/usr/bin/` clean), the actual executable script is installed to `/usr/lib/rocknix-network-manager/bin/rxnm`. A symbolic link is then placed at `/usr/bin/rxnm` to expose the command globally. The dispatcher script inherently uses `readlink` to resolve its true location before attempting to source dependencies from `../lib/`.
 
@@ -211,13 +234,14 @@ sudo ./tests/integration/run_rocknix_interop.sh
 | **Templates** | `/usr/lib/systemd/network/` | Configuration defaults (e.g., USB Gadget, WiFi). | 
 | **Hooks** | `/usr/lib/systemd/system-sleep/rxnm-resume` | WiFi state restoration logic for suspend. | 
 | **Completion** | `/usr/share/bash-completion/completions/rxnm` | Tab completion logic. | 
-| **Service** | `/etc/systemd/system/rxnm.service` | Main boot-time orchestrator service. | 
+| **Systemd Units** | `systemd/*` (Provided in source) | Boot-time orchestration service (`rxnm.service`) and REST-Lite Socket interfaces (`rxnm-api.socket`). *Note: Handled by OS Packagers, not copied by `make install`.* | 
 
 To override the installation prefix (default `/usr`):
 
 ```
 make install PREFIX=/usr/local
 
+
 ```
 
 ## ⚔️ Cross-Compilation
@@ -230,6 +254,7 @@ RXNM's zero-dependency design makes it trivial to cross-compile for target embed
 export CC=aarch64-linux-gnu-gcc
 make tiny
 
+
 ```
 
 ### Cross-Compiling for RISC-V
@@ -238,6 +263,7 @@ make tiny
 export CC=riscv64-linux-gnu-gcc
 make tiny
 
+
 ```
 
 ## 🧹 Cleaning Up
@@ -247,4 +273,5 @@ To remove build artifacts, object files, generated headers, and temporary build
 ```
 make clean
 
+
 ```

NULLIFY.md

@@ -134,7 +134,7 @@ This creates a targeted "Logical Kill-Switch." In this scenario, the physical Wi
 
 During the design phase, extending eBPF to Bluetooth via `BPF_PROG_TYPE_SOCKET_FILTER` was evaluated and rejected. Raw socket filters in Linux act as sniffers; dropping a BLE packet in a socket filter only hides it from the daemon holding the socket, it *does not* prevent the kernel's HCI core from processing the packet and waking the system.
 
-* **The RXNM Approach:** To establish a true logical air-gap and save power, we use the native `hciconfig hci0 down` (or `bluetoothctl power off`). This logically closes the HCI interface at the hardware boundary, guaranteeing zero wakeups without risking notoriously buggy SDIO driver unloads (`modprobe -r`).
+* **The RXNM Approach:** To establish a true logical air-gap and save power, we use the native `hciconfig` (e.g., `hciconfig hci0 down`). This logically closes the HCI interface at the hardware boundary, guaranteeing zero wakeups without risking notoriously buggy SDIO driver unloads (`modprobe -r`).
 
 ### 5.2. Inputs: The Proxy Trap (Explicitly Out-of-Scope)
 

PLAN.md

@@ -13,15 +13,15 @@ RXNM 2.0 moves to a **Converged Engine** where the C Agent becomes the primary l
 
 ### Evolution Comparison
 
-| Metric | 1.0 (Hybrid RC3) | OpenWrt (netifd) | 2.0 (Converged Mono) | 
+| Metric | 1.1 (Hybrid) | OpenWrt (netifd) | 2.0 (Converged Mono) | 
 | :--- | :--- | :--- | :--- | 
 | **Logic Engine** | Bash / systemd-networkd | C / **ubus** / Shell Scripts | Monolithic C Engine | 
 | **Connectivity** | `iwd` (D-Bus) | `hostapd` / `wpa_s` | Internalized `ell`/`iwd` Logic | 
 | **Data Plane** | Kernel IP Stack | Kernel IP Stack / Bridge | **eBPF / XDP (Primary)** | 
 | **IPC** | D-Bus (System/Lite) | **ubus** (libubox) | **Zero-IPC (Internal)** | 
-| **Service Logic** | `ip netns` (Fork) | Flat Router Namespace | Native `setns` / BPF Maps | 
+| **Service Logic** | Native `unshare`/`setns` (Agent) | Flat Router Namespace | Native `setns` / BPF Maps | 
 | **CPU Wakeups (Idle)** | \~20-40 / sec | \~10-20 / sec | **< 2 / sec** | 
-| **Resident RAM** | \~11.5MB | \~6.5MB | **\~2.5MB (Unified)** | 
+| **Resident RAM** | \~7.7 MB | \~6.5MB | **\~2.5MB (Unified)** | 
 
 ## 2. Core Architecture Pillars
 
@@ -71,7 +71,7 @@ Comparison of the Monolithic 2.0 stack against standard `systemd-networkd` and O
 
 | Metric | systemd-networkd | OpenWrt (netifd) | Micro-RXNM 2.0 (Mono) | 
 | :--- | :--- | :--- | :--- | 
-| **Resident RAM** | \~11.5 MB | \~6.5 MB | **\~2.5 MB** | 
+| **Resident RAM** | \~7.7 MB (Total Stack) | \~6.5 MB | **\~2.5 MB** | 
 | **Binary Footprint** | \~5.2 MB | \~1.2 MB | **\~0.9 MB** | 
 | **Cold Start Latency** | \~450ms | \~250ms | **\~15ms** | 
 | **USB/TB Hotplug** | \~180ms | \~80ms | **< 5ms** | 
@@ -118,7 +118,7 @@ Comparison of the Monolithic 2.0 stack against standard `systemd-networkd` and O
 
 ## 7. Functionality Matrix: The 2.0 Standard
 
-| Feature | RXNM 1.0 (Hybrid) | OpenWrt (netifd) | RXNM 2.0 (Mono) | 
+| Feature | RXNM 1.1 (Hybrid) | OpenWrt (netifd) | RXNM 2.0 (Mono) | 
 | :--- | :--- | :--- | :--- | 
 | **Logic Engine** | systemd-networkd | C + Shell Scripts | **Internal C Logic** | 
 | **WiFi Auth** | External `iwd` | External `wpa_s` | **Internal Module** | 

README.md

@@ -118,7 +118,7 @@ How `rxnm` translates from traditional Linux networking tools.
 | **Set DHCP** | `rxnm interface eth0 set dhcp` | `nmcli con mod eth0 ipv4.method auto` | *(Automatic)* | `udhcpc -i eth0` | 
 | **Set Static IP** | `rxnm interface eth0 set static IP/24` | `nmcli con mod eth0 ipv4.addresses IP/24` | `connmanctl config ... ipv4 manual ...` | `ip addr add IP/24 dev eth0` | 
 | **Set Gateway** | `... set static ... --gateway GW` | `nmcli con mod eth0 ipv4.gateway GW` | *(As above)* | `ip route add default via GW` | 
-| **Link Up/Down** | `rxnm interface eth0 enable/disable` | `nmcli device connect/disconnect eth0` | `connmanctl enable/disable ethernet` | `ip link set eth0 up/down` | 
+| **L3 Deconfigure** | `rxnm interface eth0 disable` | `nmcli device disconnect eth0` | `connmanctl disable ethernet` | `ip addr flush dev eth0` | 
 | **Internet Check** | `rxnm system check internet` | `nmcli networking connectivity` | *(None)* | `ping -c 1 8.8.8.8` | 
 | **Power Silence** | `rxnm system nullify enable` | *(None)* | *(None)* | *(Requires custom XDP/eBPF code)* | 
 
@@ -199,7 +199,7 @@ rxnm wifi dpp enroll "DPP:C:81/1;M:001122334455;K:..."
 | `set dhcp` | Enable dynamic addressing | 
 | `set static` | Configure fixed IP/Gateway/DNS | 
 | `set hardware` | Adjust MAC, Speed, Duplex, or MTU | 
-| `enable/disable` | Administrative UP/DOWN toggle | 
+| `enable/disable` | Halts or initiates L3 configuration via networkd overrides | 
 
 **Examples:**
 ```bash
@@ -237,7 +237,9 @@ rxnm system nullify enable --soft-wol yes
 rxnm system ipv6 disable
 ```
 
-### 4. Virtual Networking & VPN (`rxnm bridge|bond|vlan|vrf|vpn`)
+### 4. Virtual Networking, Namespaces & VPN
+
+RXNM inherently supports deep integration with standard Linux overlay and containerization technologies. 
 
 **Examples:**
 ```bash
@@ -249,6 +251,11 @@ rxnm bridge add-member eth0 --bridge br0
 rxnm vpn wireguard connect wg0 \
   --private-key "..." --peer-key "..." \
   --endpoint "vpn.host.com:51820" --address "10.0.0.2/24"
+
+# Create an isolated Network Namespace (Requires RXNM_EXPERIMENTAL=true)
+RXNM_EXPERIMENTAL=true rxnm service create my_sandbox
+RXNM_EXPERIMENTAL=true rxnm service attach my_sandbox eth1
+RXNM_EXPERIMENTAL=true rxnm service exec my_sandbox ping 8.8.8.8
 ```
 
 ## 🥗 User Stories & Cookbooks
@@ -285,6 +292,14 @@ echo '{"category":"wifi", "action":"connect", "ssid":"HomeNet", "password":"test
 ### Integration Contract
 The [api-schema.json](https://codeberg.org/aenertia/rxnm/src/branch/main/api-schema.json) serves as the strict stability contract. It guarantees that frontend UI/C++ code won't break even if the underlying Linux kernel tools (like `iproute2` or `networkctl`) change their CLI output formatting. All structured output is strictly validated against this JSON schema.
 
+## 🔢 Versioning System
+
+RXNM follows strict [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) to ensure predictability for scripts, integrations, and downstream OS packagers.
+
+* **Major (`X.0.0`):** Significant architectural shifts (e.g., the transition from the v1.x Hybrid Bash/C architecture to the planned v2.0 Monolithic C Engine) or breaking changes to the JSON API schema (`api-schema.json`) and CLI syntax.
+* **Minor (`1.X.0`):** Addition of new networking features (e.g., new `rxnm service` commands, overlay tunnels), substantial performance optimizations, or backwards-compatible API extensions.
+* **Bugfix Only (`1.1.X`):** Strictly limited to non-breaking bug fixes, security patches, upstream kernel mitigations (like adding new quirks for flaky SDIO WiFi drivers), and compatibility updates. No new features or API keys will be introduced in these releases.
+
 ## 📦 Deployment & Build Profiles
 
 > **Security Note:** The native `rxnm-agent` C-accelerator requires `CAP_SYS_ADMIN` to perform namespace isolation and XDP/eBPF attachment. Ensure it runs as `root`, has capabilities set via `setcap cap_sys_admin+ep`, or uses `AmbientCapabilities=CAP_SYS_ADMIN` in its systemd unit.