docs: update root readme and submodule pointers

README.md

@@ -1,148 +1,37 @@
-# NexusGuard SD-WAN
+# NexusGuard SD-WAN Suite
 
-**Zero-Trust Network Isolation with Stealth WireGuard Tunneling**
+NexusGuard is an Enterprise Zero-Trust SD-WAN solution built with Go, Vue 3, and WireGuard.
 
-NexusGuard is an SD-WAN system that enforces Zero-Trust network isolation through hardware-bound device identity, nftables-based micro-segmentation, and userspace WireGuard tunneling — all managed from a Vue 3 dashboard.
+## System Architecture
+This suite contains three main components:
+1. **[Server Core (Master/Hub)](apps/server-core/README.md)**: The central API and VPN Hub managing IPAM, routing, and `nftables` isolation.
+2. **[Dashboard UI](apps/dashboard-ui/README.md)**: The Admin web interface for managing users, devices, and firewall rules.
+3. **[Device Agent](apps/device-agent/README.md)**: A stealth background service for client machines that establishes secure WireGuard tunnels.
 
-## Architecture
+---
 
-```
+## Complete Workflow Guide
-┌─────────────────────────────────────────────────────┐
-│                   Dashboard UI                      │
-│              (Vue 3 + Vite + Tailwind)              │
-└────────────────────┬────────────────────────────────┘
-                     │ JWT Auth / REST API
-                     ▼
-┌──────────────────────────────────────────────────────┐
-│                    Server Core                        │
-│  (Go + Gin + GORM + PostgreSQL + Redis + nftables)   │
-└──────┬─────────────────────────────────────┬─────────┘
-       │ encrypted config (AES-256-GCM)      │
-       │ heartbeat / provisioning            │
-       ▼                                     ▼
-┌──────────────┐                     ┌──────────────┐
-│ Device Agent │  ─── WireGuard ──▶  │ Device Agent │
-│ (Stealth WG) │  peer-to-peer       │ (Stealth WG) │
-└──────────────┘                     └──────────────┘
-```
-
-## Repository Structure
-
-| Repository | Language | Role |
-|---|---|---|
-| [server-core](./apps/server-core) | Go 1.25 | REST API, auth, device management, nftables orchestration, IPAM |
-| [device-agent](./apps/device-agent) | Go 1.25 | Stealth WireGuard agent, HWID binding, encrypted provisioning |
-| [dashboard-ui](./apps/dashboard-ui) | TypeScript / Vue 3 | Management dashboard, device CRUD, firewall rule editor |
-
-## Key Features
-
-- **Zero-Trust Firewall** — nftables default-drop policy with per-user isolation sets
-- **Hardware-Bound Identity** — AES-256-GCM key derived from hardware fingerprint (product_uuid / machine-id / cpuinfo)
-- **Stealth Tunneling** — pure userspace WireGuard via wireguard-go `IpcSet()`, zero config files on disk
-- **Encrypted Provisioning** — one-time registration token + HWID → encrypted WireGuard config (key never transmitted)
-- **JWT Auth** — dashboard authentication with 24h token expiry
-- **Redis Heartbeat** — real-time device online/offline tracking with 90s TTL
-- **IPAM** — automatic IP allocation from configurable CIDR pool (default 10.8.0.0/16)
-
-## Quick Start
-
-### Prerequisites
-
-- Docker + Docker Compose (for local dev)
-- Go 1.25+ (for native builds)
-- Node 24+ (for dashboard development)
-
-### Clone with Submodules
 
+### 1. Initial Setup & Creating the Admin (Terminal)
+For maximum security, the initial administrator account **cannot** be created via the web. It must be created directly on the server via the terminal.
+Inside the `apps/server-core` directory (or inside your docker container), run:
 ```bash
-git clone --recursive https://git.datadunia.com/nexusguard/Nexus-Guard-Suite.git
+go run . -create-admin -user "admin" -pass "YourSecurePassword123"
-cd Nexus-Guard-Suite
 ```
+*(This command creates the superuser `admin` in the database).*
 
-If already cloned without `--recursive`:
+### 2. Creating Regular Users (Web Dashboard)
+1. Open the **Dashboard UI** in your web browser.
+2. Log in using the `admin` credentials created in Step 1.
+3. Once logged in as `admin`, you have the authorization to create regular User accounts for your team members.
+*(Note: Public registration is disabled. Only the `admin` can provision new users).*
 
+### 3. Registering a Device
+1. A User logs into the Dashboard UI using their assigned account.
+2. They click **"+ New Device"** and enter a recognizable name (e.g., "Johns-Laptop").
+3. The Dashboard will display a one-time **Registration Token**. 
+4. The user copies this token and runs the agent installer on their machine:
    ```bash
-git submodule update --init --recursive
+   sudo ./install_agent.sh --server-url "http://<SERVER_IP>:8080" --token "<REGISTRATION_TOKEN>"
-```
-
-### Start Server + Database
-
-```bash
-cp apps/server-core/.env.example apps/server-core/.env
-# edit .env with your secrets
-docker-compose up -d
-```
-
-This starts PostgreSQL 16, Redis 7, and Server-Core on port 8080.
-
-### Build & Run Dashboard
-
-```bash
-cd apps/dashboard-ui
-cp .env.example .env
-npm install
-npm run dev
-```
-
-### Deploy Agent on a Linux Host
-
-```bash
-# Using the bash installer (requires root)
-sudo bash apps/device-agent/scripts/install_agent.sh \
-  --server-url http://your-server:8080 \
-  --token your-registration-token
-```
-
-Or build from source:
-
-```bash
-cd apps/device-agent
-go build -o sys-bridge .
-SERVER_URL=http://your-server:8080 REG_TOKEN=your-token ./sys-bridge
-```
-
-## Tech Stack
-
-| Component | Technology |
-|---|---|
-| Backend API | Go 1.25, Gin, GORM |
-| Database | PostgreSQL 16 |
-| Cache & Heartbeat | Redis 7 |
-| Firewall | nftables (google/nftables) |
-| Tunneling | wireguard-go (userspace) |
-| Cryptography | AES-256-GCM, SHA-256 |
-| Dashboard | Vue 3, Vite 8, Pinia, Tailwind CSS 4 |
-| Dashboard API | Axios, vue-router |
-| CI/CD | Gitea Actions |
-
-## Project Phases
-
-| Phase | Status | Description |
-|---|---|---|
-| Phase 1 — Server Core | ✅ Complete | Go backend, nftables manager, IPAM, crypto, REST API |
-| Phase 2 — Device Agent | ✅ Complete | Stealth WireGuard tunnel, HWID discovery, provisioning client |
-| Phase 3 — DevOps | ✅ Complete | Docker Compose, bash installer, systemd service, Gitea CI/CD |
-| Phase 4 — Dashboard UI | ✅ Complete | Vue 3 dashboard, device CRUD, firewall rule editor |
-| Phase 5 — Advanced Docs | ✅ Complete | TLS deployment, STUN, key rotation, peer discovery notes |
-
-## Security Design
-
-- **No agent disk writes**: WireGuard config lives in memory only (IpcSet)
-- **Encrypted at rest**: Device private keys encrypted in DB; configs decrypted per-session
-- **One-time tokens**: Registration tokens invalidated after first use
-- **Auth isolation**: JWT for dashboard ↔ server; X-Token-Auth for agent ↔ server
-- **nftables element-level ops**: No `nft flush table`, only individual element add/remove
-
-## Development
-
-```bash
-# Run all Go tests
-cd apps/server-core && go test ./... -tags dev
-cd apps/device-agent && go test ./...
-
-# Run dashboard dev server
-cd apps/dashboard-ui && npm run dev
-
-# Full integration test (Linux with nftables)
-# See integration smoke tests in plan document
    ```
+5. The device connects, binds its Hardware ID securely, provisions its WireGuard keys, and appears as **Online** in the Dashboard.