feat: complete nx9-wg v0.8.0 platform

docs/development.md

@@ -1,52 +1,82 @@
-# Development and Contributing Guide
+# Developer Guide & Repository Reference
 
-## Environment Setup
-
-- **Rust Toolchain**: `rustc` and `cargo` 1.85+ (Edition 2024).
-- **SQLite3 development headers** (for `sqlx-sqlite`).
+This guide provides instructions for building, testing, linting, and contributing to the `nx9-wg` codebase.
 
 ---
 
-## Workspace Structure
+## 1. Workspace Layout
 
-```
-.
-├── Cargo.toml
-├── Cargo.lock
-├── config.example.toml
-├── nx9-wg.service
-├── Dockerfile
-├── src/
-│   └── main.rs
-├── crates/
-│   ├── nx9-core/         # Domain models, crypto, config, validation
-│   ├── nx9-db/           # SQLite schema, migrations, repositories
-│   ├── nx9-wireguard/    # WireGuard controller, .conf builder, QR engine
-│   ├── nx9-network/      # Forwarding, routing, nftables
-│   ├── nx9-api/          # Axum API, WebSocket, Reconciler, Backup
-│   └── nx9-ui/           # Dioxus UI shell
-└── docs/                 # Documentation suite
-```
+The repository is organized as a Cargo workspace containing 6 crates and the root application binary:
+
+- **`crates/nx9-wg-core`**: Common domain entities, RFC validators, cryptography, and configuration.
+- **`crates/nx9-wg-db`**: SQLite database persistence layer, migration SQL scripts, and repository implementations.
+- **`crates/nx9-wireguard`**: WireGuard Generic Netlink execution, RTNETLINK link management, config builder, and QR engine.
+- **`crates/nx9-wg-network`**: RTNETLINK route management, `libnftables.so.1` integration, and procfs forwarding.
+- **`crates/nx9-wg-api`**: Axum REST API router, WebSocket broadcaster, authentication middleware, and reconciliation engine.
+- **`crates/nx9-wg-ui`**: Design tokens, CSS stylesheet compiler, view models, and SPA asset integration.
+- **`src/main.rs`**: Root CLI command parser and daemon entry point.
 
 ---
 
-## Running Quality Gates
+## 2. Prerequisites & Build Commands
 
-Before submitting changes, all mandatory quality gates must pass:
+### Prerequisites
+- **Rust Toolchain**: 1.85+ (Edition 2024).
+- **C Compiler**: `gcc` or `clang` (for SQLite C amalgamation).
+- **Linux Libraries**: `libnftables-dev` (Debian/Ubuntu) or `nftables-devel` / `libnftables` (Fedora/Arch).
 
+### Build Commands
 ```bash
-# 1. Format check
+# Debug build
+cargo build --workspace
+
+# Release build
+cargo build --release
+
+# Format check
 cargo fmt --all -- --check
 
-# 2. Workspace check
-cargo check --workspace
+# Clippy linter
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
 
-# 3. Unit and integration tests
+---
+
+## 3. Test Execution & SAFE Mode (`LIVE=0`) vs Privileged Mode (`LIVE=1`)
+
+To prevent accidental modifications to developer workstations, all integration and live kernel test scripts default to SAFE mode (`LIVE=0`):
+
+```bash
+# 1. Run full workspace unit & integration tests
 cargo test --workspace
 
-# 4. Strict clippy with warnings denied
-cargo clippy --workspace --all-targets --all-features -- -D warnings
+# 2. Run Comprehensive CLI Verification Suite (210 checks)
+LIVE=0 bash scripts/test-cli-comprehensive.sh
 
-# 5. Marker scan
-git grep -n -E 'TODO|FIXME|XXX|HACK|unimplemented!|todo!|panic!' src/ crates/
+# 3. Run Native Linux Integration Test Suite (20 checks)
+LIVE=0 bash scripts/test-native-integration.sh
+
+# 4. Run Dedicated Live Kernel Test Suite (24 checks)
+LIVE=0 bash scripts/test-live-kernel.sh
 ```
+
+### Privileged Real-Kernel Testing (`LIVE=1`)
+> [!CAUTION]
+> `LIVE=1` tests must ONLY be executed on a dedicated disposable Linux virtual machine or container with `CAP_NET_ADMIN`. Never execute `LIVE=1` on a production host.
+
+```bash
+# On a dedicated disposable VM as root:
+sudo LIVE=1 bash scripts/test-live-kernel.sh
+```
+
+---
+
+## 4. Release Packaging
+
+To build the self-contained release distribution archives:
+
+```bash
+bash scripts/package-release.sh
+```
+
+Outputs `.tar.gz`, `.tar.xz`, and `.sha256` files in `target/dist/`.