# 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)

```markdown
# 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