docs: align documentation with nx9-wg implementation

README.md

@@ -14,7 +14,8 @@
 - **Native Linux WireGuard Engine**: Direct interaction with Linux networking and kernel interfaces without shelling out to `wg` or `wg-quick`.
 - **nftables Isolation**: Dedicated `table inet nx9_wg` with input, forward, and NAT postrouting masquerade chains.
 - **Continuous Reconciliation**: Automated drift detection and idempotent convergence between desired database state and live Linux kernel state.
-- **Pure Rust Client Enrollment**: Full-tunnel and split-tunnel `.conf` builder, high-resolution SVG/PNG QR generator, and ASCII terminal QR output.
+- **Pure Rust Client Enrollment**: Full-tunnel and split-tunnel `.conf` builder, high-resolution SVG/PNG QR generator, ASCII terminal QR output, and client-aware environment/MTU profiles.
+- **Deterministic IP Allocation**: Automatic IPv4/IPv6 peer address allocation with collision and reserved-address protection.
 - **Consistent Backups**: Atomic SQLite snapshots (`VACUUM INTO`), manifest hashing with SHA-256, verification, and safety snapshots before restore.
 - **Complete CLI & Axum REST API**: Multi-format CLI (`table`, `json`, `yaml`, `csv`) and RESTful API with real-time WebSocket telemetry.
 
@@ -27,14 +28,14 @@
 # Build the workspace
 cargo build --release
 
-# Run all 41 unit and integration tests
+# Run the complete workspace test suite
 cargo test --workspace
 ```
 
 ### 2. Initialize the Administrator
 ```bash
 # Initialize with a generated password:
-cargo run -- init --generate-password
+cargo run -- init --generate-password --write-password-file /tmp/nx9-wg-admin-password
 
 # Or initialize with a specific password:
 cargo run -- init --username admin --password "YourStrongPassword123!"
@@ -42,6 +43,9 @@ cargo run -- init --username admin --password "YourStrongPassword123!"
 
 ### 3. Start the Daemon
 ```bash
+cargo run -- serve
+
+# To intentionally expose the management API on all interfaces:
 cargo run -- serve --bind 0.0.0.0:8080
 ```
 
@@ -51,7 +55,7 @@ cargo run -- serve --bind 0.0.0.0:8080
 cargo run -- interface create --name wg0 --port 51820 --address-v4 10.0.0.1/24
 
 # Create peer Alice
-cargo run -- peer create --interface-id <INTERFACE_UUID> --name alice --address-v4 10.0.0.2/32
+cargo run -- peer create --interface <INTERFACE_NAME_OR_ID> --name alice --address-v4 10.0.0.2/32
 
 # Display terminal QR code for instant mobile scan:
 cargo run -- peer qr <PEER_UUID>

docs/architecture.md

@@ -2,23 +2,23 @@
 
 ## System Overview
 
-`nx9-wg` is structured as a modular Rust workspace consisting of seven specialized crates and a root binary.
+`nx9-wg` is structured as a modular Rust workspace consisting of six specialized crates and a root binary.
 
 | Crate | Responsibility | Dependencies |
 | :--- | :--- | :--- |
-| **`nx9-core`** | Domain entities, cryptographic utilities (Argon2id, x25519, SHA-256), data validation, and configuration types. | `serde`, `argon2`, `x25519-dalek`, `sha2`, `ipnet`, `chrono`, `uuid` |
+| **`nx9-wg-core`** | Domain entities, cryptographic utilities (Argon2id, x25519, SHA-256), data validation, and configuration types. | `serde`, `argon2`, `x25519-dalek`, `sha2`, `ipnet`, `chrono`, `uuid` |
-| **`nx9-db`** | Authoritative persistence layer using SQLite with WAL mode, automated migrations, and isolated repository modules. | `nx9-core`, `sqlx` (sqlite) |
+| **`nx9-wg-db`** | Authoritative persistence layer using SQLite with WAL mode, automated migrations, and isolated repository modules. | `nx9-wg-core`, `sqlx` (sqlite) |
-| **`nx9-wireguard`**| WireGuard interface controller, client `.conf` configuration builder, live telemetry inspection, and pure Rust QR engine. | `nx9-core`, `qrcode`, `image`, `base64` |
+| **`nx9-wireguard`**| WireGuard interface controller, client `.conf` configuration builder, live telemetry inspection, and pure Rust QR engine. | `nx9-wg-core`, `qrcode`, `image`, `base64` |
-| **`nx9-network`** | Linux kernel IP forwarding, routing table synchronization, and atomic `inet nx9_wg` nftables ruleset generator. | `nx9-core`, `ipnet` |
+| **`nx9-wg-network`** | Linux kernel IP forwarding, routing table synchronization, and atomic `inet nx9_wg` nftables ruleset generator. | `nx9-wg-core`, `ipnet` |
-| **`nx9-api`** | Axum REST API, session and token authentication middleware, WebSocket live event broadcast, and Reconciliation Engine. | `nx9-core`, `nx9-db`, `nx9-wireguard`, `nx9-network`, `axum`, `tower` |
+| **`nx9-wg-api`** | Axum REST API, session and token authentication middleware, WebSocket live event broadcast, and Reconciliation Engine. | `nx9-wg-core`, `nx9-wg-db`, `nx9-wireguard`, `nx9-wg-network`, `axum`, `tower` |
-| **`nx9-ui`** | Dioxus web client shell (client only, business logic isolated in backend). | `nx9-core` |
+| **`nx9-wg-ui`** | Dioxus web client shell (client only, business logic isolated in backend). | `nx9-wg-core` |
 | **`nx9-wg`** | Primary application binary providing CLI operations and HTTP daemon server. | All workspace crates, `clap` |
 
 ---
 
 ## Architectural Invariants
 
-1. **Strict SQL Isolation**: All raw SQL queries and SQLite interactions are confined entirely to `crates/nx9-db/`. No other crate or handler interacts with SQLite directly.
+1. **Strict SQL Isolation**: All raw SQL queries and SQLite interactions are confined entirely to `crates/nx9-wg-db/`. No other crate or handler interacts with SQLite directly.
 2. **Zero Shelling Out**: WireGuard, routing, and packet filtering interact with kernel abstractions and netlink without executing `wg`, `wg-quick`, or `iptables` subprocesses.
 3. **Single Administrator Model**: The system maintains exactly one administrative identity with `CHECK (id = 1)`. No RBAC, multi-tenant, or organization complexity is introduced.
 4. **Secret Redaction**: Passwords, private keys, preshared keys, and API tokens are never logged, persisted in plaintext, or exposed in error messages. All secret wrapper types implement custom `Debug` redactions (`[REDACTED]`).

docs/cli.md

@@ -30,6 +30,9 @@ nx9-wg version --format json
 ### 2. `serve`
 Starts the Axum REST API, WebSocket event streamer, and background reconciliation daemon.
 ```bash
+nx9-wg serve
+
+# To intentionally expose the management API on all interfaces:
 nx9-wg serve --bind 0.0.0.0:8080
 ```
 
@@ -62,7 +65,7 @@ nx9-wg init --password-file /run/secrets/admin_pw
 - `nx9-wg admin sessions list`: List active sessions.
 - `nx9-wg admin sessions revoke <SESSION_ID>`: Invalidate specific session.
 - `nx9-wg admin sessions revoke-all`: Invalidate all active administrator sessions.
-- `nx9-wg admin tokens create --name <NAME> [--days <DAYS>]`: Generate a long-lived API token.
+- `nx9-wg admin tokens create --name <NAME> [--days <DAYS>] [--write-token-file <PATH>]`: Generate a long-lived API token. The recommended secure workflow writes the one-time plaintext token to a file with restrictive permissions; token hashes are redacted from normal CLI output.
 - `nx9-wg admin tokens list`: List all API token metadata.
 - `nx9-wg admin tokens revoke <TOKEN_ID>`: Revoke an API token.
 

docs/configuration.md

@@ -46,7 +46,7 @@ Every environment variable recognized by `nx9-wg` uses the mandatory `NX9_WG_` n
 | `NX9_WG_CONFIG` | `config_file` | `--config, -c` | Path to TOML configuration file | `/etc/nx9-wg/config.toml` |
 | `NX9_WG_DATA_DIR` | `data_dir` | `--data-dir, -d` | Path to persistent data directory | `/var/lib/nx9-wg` |
 | `NX9_WG_DATABASE` | N/A | `--database` | Path to SQLite database file | `<data_dir>/nx9-wg.db` |
-| `NX9_WG_LISTEN_ADDR` | `bind_address` | `--bind` | HTTP / WebSocket daemon bind address | `0.0.0.0:8080` |
+| `NX9_WG_LISTEN_ADDR` | `bind_address` | `--bind` | HTTP / WebSocket daemon bind address | `127.0.0.1:8080` |
 | `NX9_WG_LOG_LEVEL` | `log_level` | `--log-level` | Log verbosity filter (`trace`, `debug`, `info`, `warn`, `error`) | `info` |
 | `NX9_WG_SESSION_TIMEOUT` | `session_expiry_hours` | N/A | Session inactivity timeout in hours | `24` |
 | `NX9_WG_RECONCILIATION_INTERVAL` | `reconciliation_interval_secs` | N/A | Background kernel reconciliation interval in seconds | `60` |

docs/installation.md

@@ -12,7 +12,7 @@
 
 ### Building from Source
 ```bash
-git clone https://github.com/nx9/nx9-wg.git
+git clone ssh://git@git.nx9.in:6645/thakares/nx9-wg.git
 cd nx9-wg
 cargo build --release --bin nx9-wg
 
@@ -28,7 +28,7 @@ sudo cp config.example.toml /etc/nx9-wg/config.toml
 
 ### Bootstrapping the Administrator Account
 ```bash
-sudo nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg init --generate-password
+sudo nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
 ```
 
 ---