init-deep: AGENTS.md Generation Plan

Generated: 2026-05-22 Branch: main (92051d5)

Overview

Generate hierarchical AGENTS.md files for the NexusGuard SD-WAN Suite monorepo. Scored 4 locations for AGENTS.md: root + 3 submodules.

Scoring Results

Location	Score	Reason	Action
`.` (root)	—	Always create root	CREATE
`apps/server-core/`	3+2+2+1=8+	54 files (3x), 9 subdirs (2x), go.mod (2x), Dockerfile (1x)	CREATE
`apps/dashboard-ui/`	3+2+2+1=8+	54 files (3x), 8 subdirs (2x), package.json (2x), tsconfig (1x)	CREATE
`apps/device-agent/`	3+0+2+0=5+	21 files (3x), 5 subdirs (0x), go.mod (2x)	CREATE (≥15)
`apps/server-core/api/`	0	17 files (<20)	SKIP (parent covers)
`apps/dashboard-ui/views/`	0	7 files (<20)	SKIP (parent covers)
`apps/dashboard-ui/api/`	0	7 files (<20)	SKIP (parent covers)

Files to Create/Update

No existing AGENTS.md files found. All 4 are new files (Write).

File 1: `./AGENTS.md` (Root — 122 lines)

# PROJECT KNOWLEDGE BASE

**Generated:** 2026-05-22
**Commit:** `92051d5`
**Branch:** `main`

## OVERVIEW
NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunneling, centralized IPAM, and real-time nftables network isolation. Monorepo with 3 git submodules: Go backend (Gin), Vue 3 dashboard, Go device agent.

## STRUCTURE

./ ├── apps/ │ ├── server-core/ # Go/Gin API backend (submodule) │ ├── dashboard-ui/ # Vue 3 + Vite frontend (submodule) │ └── device-agent/ # Go stealth daemon (submodule) ├── docker-compose.yml # Production orchestration ├── docker-compose.dev.yml # Dev (air hot-reload) ├── Makefile # up/down/dev/migrate/reset-db ├── setup.sh # First-run: generate .env + random keys ├── .env.example # DB/JWT/SALT/VITE config template ├── .gitmodules # 3 submodules → git.datadunia.com └── .opencode/ # IDE agent config (tooling, not project code)


**CRITICAL**: `apps/*` are **git submodules** — clone with `--recurse-submodules`.

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| API handlers | `apps/server-core/api/` | 17 files: auth, devices, peers, rules, share, provisioning, servers, wg |
| Backend core | `apps/server-core/internal/` | auth, config, firewall, heartbeat, ipam, models, wgmanager |
| Dev migration | `apps/server-core/main_dev.go` | GORM AutoMigrate (build tag `dev`) |
| Firewall rules | `apps/server-core/internal/firewall/` | nftables Linux rules |
| Dashboard views | `apps/dashboard-ui/src/views/` | Vue SFC pages |
| Dashboard API client | `apps/dashboard-ui/src/api/` | Axios API modules |
| Dashboard stores | `apps/dashboard-ui/src/stores/` | Pinia state stores |
| Agent client | `apps/device-agent/internal/client/` | Provisioning + heartbeat |
| Agent tunnel | `apps/device-agent/internal/tunnel/` | Memory-injected WireGuard |
| Shared crypto | `apps/*/shared/crypto/encryptor.go` | AES-256-GCM (duplicated identical) |
| CI workflows | `apps/*/.gitea/workflows/build.yml` | Gitea Actions per submodule |
| Build config | `apps/dashboard-ui/vite.config.ts` | Vite 8 + Vue + TailwindCSS v4 |
| Source of truth | `apps/server-core/docs/` | API_SPEC, KEY_ROTATION, PEER_DISCOVERY |
| Plan guardrails | `.sisyphus/plans/` | Anti-patterns, "Must NOT do" rules |

## CODE MAP
| Symbol | Type | Location | Role |
|--------|------|----------|------|
| `main()` (server-core) | func | `apps/server-core/main.go` | Entry: CLI flags + Gin init |
| `main()` (device-agent) | func | `apps/device-agent/main.go` | Entry: agent daemon lifecycle |
| `config.Load()` | func | `apps/server-core/internal/config/` | Env-based config loader |
| `auth.Init()` | func | `apps/server-core/internal/auth/` | JWT sign/verify init |
| `firewall.InitNetwork()` | func | `apps/server-core/internal/firewall/` | nftables table/set creation |
| `ipam.AllocateIP()` | func | `apps/server-core/internal/ipam/` | IP pool allocation from CIDR |
| `wgmanager.SetConfig()` | func | `apps/server-core/internal/wgmanager/` | WireGuard config push |
| `models.AutoMigrate()` | func | `apps/server-core/internal/models/` | GORM schema migration |
| `encrypt()` / `decrypt()` | func | `apps/*/shared/crypto/encryptor.go` | AES-256-GCM (identical) |

## CONVENTIONS
- **Go**: Standard layout (`main.go` in root, `internal/`, `api/`)
- **Vue 3**: Composition API + `<script setup lang="ts">` throughout
- **State management**: Pinia stores in `src/stores/`
- **API client**: Axios-based services in `src/api/` + base `src/services/`
- **Styling**: TailwindCSS v4 (no PostCSS — `@tailwindcss/vite` plugin)
- **DB**: GORM ORM, PostgreSQL, AutoMigrate in dev / `-migrate-prod` in prod
- **Naming**: `UPPER_SNAKE_CASE` env vars, `camelCase` Go vars, `PascalCase` exported Go
- **Auth**: JWT, admin-only enforced by middleware pattern
- **Build tags**: `//go:build dev` for AutoMigrate
- **Capabilities**: Server containers need `NET_ADMIN` + `NET_RAW`
- **Ports**: API 8080, Dashboard 80 (Nginx), Postgres 5432, Redis 6379

## ANTI-PATTERNS (THIS PROJECT)
- **NEVER** `nft flush table` — only atomic add/remove
- **NEVER** log plaintext or encryption keys
- **NEVER** reopen completed phases/commits — fix forward only
- **NEVER** rebuild `shared/crypto/encryptor.go` — copy identical file
- **NEVER** commit build artifacts (binaries, `dist/`)
- **NEVER** force push
- **NEVER** create cross-phase workarounds

## UNIQUE STYLES
- **Zero-Attack Surface**: `/auth/register` locked; admin via `-create-admin` CLI only
- **Stealth Agent**: No `/etc/wireguard/` — config in memory only
- **Duplicate crypto**: `encryptor.go` copy-pasted in server-core + device-agent (known debt, do not deduplicate)
- **nftables default Accept**: Contradicts Zero-Trust "Default DROP" — intentional gap

## COMMANDS
```bash
make up              # Start all services
make down            # Stop all services
make dev             # Start with hot-reload (air)
make logs            # Tail all logs
make migrate         # Run DB migration (requires local Go)
make reset-db        # Nuke PG volume + recreate + migrate

cd apps/server-core && go run -tags dev .
cd apps/dashboard-ui && npm run dev
cd apps/device-agent && go run .

go run -tags dev ./apps/server-core -create-admin -user admin -pass "..."

NOTES

Submodules → private Gitea (git.datadunia.com); CI via Gitea Actions per submodule
Go versions diverge: server-core 1.25.7, device-agent 1.25.1
No root linter configs (.golangci.yml, .eslintrc, .editorconfig)
Shell scripts use deprecated docker-compose v1, Makefile uses docker compose v2
Root has stale artifacts: connect_remote.txt, temp_section*.txt
package.json name is "temp-ui" (stale scaffold remnant)


---

## File 2: `apps/server-core/AGENTS.md` (Server Core — 70 lines)

```markdown
# SERVER CORE — Go/Gin Backend

## OVERVIEW
Central API and VPN Hub managing database state, JWT token distribution, and Linux nftables firewall isolation. Module: `git.datadunia.com/nexusguard/nexus-server-core`.

## STRUCTURE

apps/server-core/ ├── main.go # Entry: CLI flags, Gin init, DB connect ├── main_dev.go # Dev build: AutoMigrate on boot ├── main_prod.go # Prod build: no-op migration ├── api/ # 17 HTTP handler files (auth, devices, peers, rules...) ├── internal/ │ ├── auth/ # JWT init/signing (auth.Init) │ ├── config/ # Env-based config loader │ ├── firewall/ # nftables rule management (Linux only) │ ├── heartbeat/ # Redis heartbeat TTL check │ ├── ipam/ # IP pool allocation from CIDR │ ├── models/ # GORM models + AutoMigrate │ └── wgmanager/ # WireGuard config push to kernel ├── shared/crypto/ # AES-256-GCM (identical copy in device-agent) ├── migrations/ # SQL migration files └── docs/ # API_SPEC, KEY_ROTATION, PEER_DISCOVERY


## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Auth endpoints | `api/auth.go` | Login, admin creation |
| Device CRUD | `api/devices.go` | Device lifecycle |
| Peer management | `api/peers.go` | Peer CRUD + 500 fix |
| Firewall rules API | `api/rules.go` | nftables rule CRUD |
| Provisioning | `api/provisioning.go` | Registration token flow |
| Tests | `api/*_test.go` | auth_test, devices_test, rules_test, etc. |
| Config loading | `internal/config/config.go` | Env var parsing |
| nftables engine | `internal/firewall/nftables_linux.go` | InitNetwork, AddRule, RemoveRule |

## CONVENTIONS
- **Stack**: Go 1.25.7, Gin 1.12, GORM 1.31 (PostgreSQL), JWT v5, go-redis 9.x, google/nftables 0.3, wgctrl
- **DB**: GORM AutoMigrate in dev (`-tags dev`); `-migrate-prod` for production
- **Auth**: JWT middleware in `api/` — repeated admin-only checks (not centralized)
- **API style**: Gin `c.JSON` responses, status codes, error message strings
- **nftables**: Default Accept policy (`nftables_linux.go:35`) — known doc gap

## ANTI-PATTERNS (THIS PROJECT)
- **NEVER** `nft flush table` — destroys all peer isolation
- **NEVER** log plaintext or encryption keys
- **Admin-only authorization** is copy-pasted across 7+ handler files — refactoring opportunity

## COMMANDS
```bash
go run -tags dev .                          # Dev server
go run -tags dev . -migrate-prod            # Run migration manually
go run -tags dev . -create-admin -user admin -pass "..."
go test ./... -tags dev -cover              # Run all tests

NOTES

API runs on port 8080 (configurable via PORT/API_PORT)
Docker needs NET_ADMIN + NET_RAW capabilities
Tests exist for auth, devices, provisioning, rules, share


---

## File 3: `apps/dashboard-ui/AGENTS.md` (Dashboard UI — 60 lines)

```markdown
# DASHBOARD UI — Vue 3 Frontend

## OVERVIEW
Admin Web GUI for managing Nodes, Users, Devices, and Firewall rules. Futuristic glassmorphism design with Vue 3 + Vite + TailwindCSS v4.

## STRUCTURE

apps/dashboard-ui/ ├── src/ │ ├── main.ts # Vue app bootstrap (Pinia + Router) │ ├── App.vue # Root component │ ├── api/ # Axios API client modules (7 files) │ ├── views/ # Page components (7 SFCs) │ ├── components/ # Shared UI components (4 files) │ ├── stores/ # Pinia stores (2 files) │ ├── assets/ # CSS (main.css) │ ├── router/ # Vue Router config │ └── services/ # Base Axios HTTP service ├── public/ # Static assets ├── index.html # HTML shell ├── vite.config.ts # Vite 8 config (+Vue +TailwindCSS) ├── tsconfig.app.json # Strict TS, noUnusedLocals, noUnusedParameters └── nginx.conf # SPA nginx fallback


## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| API integration | `src/api/` | 7 modules matching backend routes |
| Page views | `src/views/` | Nodes, Devices, Firewall, Settings, etc. |
| State management | `src/stores/` | Pinia stores |
| Shared components | `src/components/` | Reusable UI elements |
| Routing | `src/router/index.ts` | Vue Router config |
| Base HTTP | `src/services/` | Axios instance with interceptors |

## CONVENTIONS
- **Stack**: Vue 3.5, Vite 8, TypeScript 6.0, TailwindCSS 4.3, Pinia 2.3, VueUse 14.3, Axios 1.16, HeadlessUI 1.7, Iconify 5.0
- **Style**: Composition API, `<script setup lang="ts">`, glassmorphism design
- **Build**: `vue-tsc -b && vite build` (type-check before build)
- **Dev**: `vite` (Vite 8 dev server, no explicit port)
- **TS**: Strict mode, ES2020, noUnusedLocals, noUnusedParameters
- **API base**: `VITE_API_BASE_URL` env var (baked at build time)

## ANTI-PATTERNS (THIS PROJECT)
- `package.json` name is `"temp-ui"` — stale scaffold remnant — rename
- No ESLint/Prettier configs exist
- `index.html` `<title>` still says "temp-ui"

## COMMANDS
```bash
npm run dev       # Vite dev server
npm run build     # vue-tsc + vite build
npm run build     # Build output → dist/ for Nginx

NOTES

Port 80 in Docker (Nginx), no explicit dev server port
VITE_API_BASE_URL injected via Docker ARG at build time
No package-lock.json committed? Verify — npm ci not npm install


---

## File 4: `apps/device-agent/AGENTS.md` (Device Agent — 50 lines)

```markdown
# DEVICE AGENT — Go Stealth Daemon

## OVERVIEW
Stealth background daemon for Linux client machines. Establishes memory-injected WireGuard tunnels — no `/etc/wireguard/` config files ever written to disk.

## STRUCTURE

apps/device-agent/ ├── main.go # Entry: env parsing, identity, provisioning, tunnel, heartbeat ├── internal/ │ ├── client/ # Provisioning (register + key exchange) + heartbeat │ ├── identity/ # HWID detection (machine identity binding) │ └── tunnel/ # Fileless WireGuard tunnel injection ├── shared/crypto/ # AES-256-GCM (identical copy in server-core) └── scripts/ ├── install_agent.sh # Systemd service installer └── sys-bridge.service # Systemd unit file


## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Provisioning flow | `internal/client/` | Registration, key exchange with server |
| HW identity | `internal/identity/` | Hardware ID detection |
| Tunnel injection | `internal/tunnel/` | Memory-only WireGuard config |
| Install script | `scripts/install_agent.sh` | One-command agent deployment |

## CONVENTIONS
- **Stack**: Go 1.25.1, wireguard, crypto, net, sys (minimal deps)
- **Design**: Stealth — no disk writes for WG config; tunnel lives in process memory
- **Lifecycle**: HWID → Provision → Tunnel → Heartbeat loop
- **Env vars**: `SERVER_URL`, `REG_TOKEN`
- **Cross-compile**: CI builds for linux/amd64, arm64, arm

## ANTI-PATTERNS (THIS PROJECT)
- **NEVER** write WireGuard config to `/etc/wireguard/` — stealth invariant
- **NEVER** log encryption keys or registration tokens
- `shared/crypto/` is duplicated from server-core (do not rewrite separately)

## COMMANDS
```bash
go run .                                       # Run (needs SERVER_URL + REG_TOKEN)
go build -o device-agent .                     # Build binary
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o device-agent-linux-arm64 .

NOTES

Cross-compiled in CI for 3 architectures (amd64, arm64, arm)
Go version 1.25.1 — slightly behind server-core's 1.25.7
Install via sudo ./install_agent.sh --server-url ... --token ...


---

## Execution Steps

1. **[DONE]** **Write** `./AGENTS.md` (root) — 109 lines, full treatment
2. **[DONE]** **Write** `apps/server-core/AGENTS.md` — 61 lines, domain-specific
3. **[DONE]** **Write** `apps/dashboard-ui/AGENTS.md` — 58 lines, domain-specific
4. **[DONE]** **Write** `apps/device-agent/AGENTS.md` — 50 lines, domain-specific
5. **[DONE]** **Verify**: no duplicate content between parent and children

## Quality Gates
- [x] Root AGENTS.md: 50-150 lines ✅ (109)
- [x] Subdir AGENTS.md: 30-80 lines each ✅ (61/58/50)
- [x] No generic advice in any file
- [x] No parent duplicates repeated in children
- [x] Telegraphic style throughout

15 KiB Raw Blame History

init-deep: AGENTS.md Generation Plan

Overview

Scoring Results

Files to Create/Update

File 1: ./AGENTS.md (Root — 122 lines)

NOTES

NOTES

NOTES

NOTES

15 KiB

Raw Blame History

File 1: `./AGENTS.md` (Root — 122 lines)