doc remediation

specs/004-vps-migration/contracts/openapi.yaml

@@ -14,7 +14,7 @@ paths:
           description: Proxy mappings resolve to services on host server
   /verify/firewall:
     get:
-      summary: Verify iptables ruleset parity
+      summary: Verify nftables parity against the iptables reference
       responses:
         "200":
           description: Firewall flows match expected allow/deny behavior

specs/004-vps-migration/data-model.md

@@ -17,7 +17,7 @@
 
 ## FirewallRuleSet
 
-- **Fields**: sourceFile (iptables), rules[], appliedHost
+- **Fields**: sourceFile (iptables reference), rules[], appliedHost
 - **Rules**: Ruleset must be applied as-is; no translation allowed.
 
 ## VPNPeer

specs/004-vps-migration/plan.md

@@ -5,18 +5,18 @@
 
 ## Summary
 
-Migrate VPS responsibilities to the new NixOS host by making it the primary reverse-proxy host (nginx only), mirroring the existing iptables ruleset, enabling wireguard with secret-managed keys, and restoring SSH/service-user access, while keeping all services running on the host server. Provide validation steps, review historical configs for gaps, and document analytics data migration.
+Migrate VPS responsibilities to the new NixOS host by making it the primary reverse-proxy host (nginx only), mirroring the existing iptables ruleset via nftables/NixOS equivalents, enabling wireguard with secret-managed keys, and restoring SSH/service-user access, while keeping all services running on the host server. Provide validation steps, review historical configs for gaps, and document analytics data migration.
 
 ## Technical Context
 
 **Language/Version**: Nix (flakes; nixpkgs 25.11)  
-**Primary Dependencies**: NixOS modules, sops-nix, nginx, wireguard, openssh, iptables  
+**Primary Dependencies**: NixOS modules, sops-nix, nginx, wireguard, openssh, nftables (iptables reference)  
 **Storage**: Files (configuration and secrets)  
 **Testing**: Manual validation steps (no automated test harness)  
 **Target Platform**: Linux server (NixOS)  
 **Project Type**: configuration repo  
 **Performance Goals**: N/A (configuration change)  
-**Constraints**: Services remain on host server; VPS only terminates proxy and exposes wireguard port; iptables parity required  
+**Constraints**: Services remain on host server; VPS only terminates proxy and exposes wireguard port; nftables parity required  
 **Scale/Scope**: Single VPS + host server, small set of VPN peers and admin SSH principals
 
 ## Constitution Check
@@ -45,8 +45,8 @@ specs/004-vps-migration/
 hosts/
 modules/
 secrets/
-iptables
+iptables (reference ruleset)
 scripts/
 ```
 
-**Structure Decision**: Use the existing NixOS configuration layout (`hosts/`, `modules/`, `secrets/`) and the root `iptables` ruleset file.
+**Structure Decision**: Use the existing NixOS configuration layout (`hosts/`, `modules/`, `secrets/`) and the root `iptables` ruleset file as the reference for nftables parity.

specs/004-vps-migration/quickstart.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - Access to this repo and the new VPS host configuration
-- Existing iptables ruleset file available at repo root: `iptables`
+- Existing iptables ruleset file available at repo root (reference for nftables parity): `iptables`
 - VPN keys present in the secrets system
 - SSH public keys present in `secrets/ssh/`
 
@@ -19,7 +19,7 @@
 3. Update host configuration:
    - Set new VPS as primary reverse proxy host
    - Enable proxying for all enabled services (services remain on host server)
-   - Apply iptables ruleset as-is
+   - Apply nftables/NixOS firewall rules derived from the iptables reference
    - Enable wireguard on VPS and expose port
    - Add service users and admin SSH keys
    - Update VPS public IP to `45.33.0.228` in SSH configuration

specs/004-vps-migration/research.md

@@ -8,7 +8,7 @@
 
 ## Decision 2: Firewall parity
 
-- **Decision**: Apply the existing iptables ruleset as-is on the new VPS.
+- **Decision**: Use the existing iptables ruleset as the source of truth and implement equivalent nftables/NixOS rules on the new VPS.
 - **Rationale**: Ensures exact behavioral parity for complex routing and hot-swap behavior.
 - **Alternatives considered**: Translating to another firewall system; partial translation with mixed rules.
 

specs/004-vps-migration/spec.md

@@ -3,7 +3,7 @@
 **Feature Branch**: `004-vps-migration`  
 **Created**: 2026-02-04  
 **Status**: Draft  
-**Input**: User description: "start feature branch 004, the git fetch command will fail, so force 004. Feature 003 added a new hosts vps, as a linode host, I want to now fully migrate my existing fedora vps to this new nixos vps. to do so I want to bring in the configurations fedora vps has. 1. right now the nginx logic of my servers is disabled, because I let the fedora vps handle the reverse proxy through caddy. But I dont want that caddy logic, on nixos I want to let nginx take care of the reverse proxies, plus the logic is already backed in, there is a isLocal logic to the factory, and I dont remember exactly the name of the code. but there is some flag under the my. options that specifies the mainHost, the constitution mentions that mainHost is the host handling nginx and because the vps will be it, then main host needs to become vps, I think before it was miniserver. This change means, that all the currently enabled servers on the toggles.nix from the host server, should have the enableProxy flag on vps (double check the logic) this should make it so, that nginx runs on vps, and the servers run on server. 2. Add a step to ask me for the caddy files, just to check that the subdomains caddy handles for each server match the subdomains on the servers/.*nix files. 3. I use iptables on the fedora vps, and the nixos vps, well I dont mind you using another firewall but there are some complex firewall rules that I need them to work 100% as the original vps, the rules will be on a file named iptables, this is perhaps the most important step, otherwise the complex network configuration this vps has wont be able to hot swap and serve my servers to the world.
+**Input**: User description: "start feature branch 004, the git fetch command will fail, so force 004. Feature 003 added a new hosts vps, as a linode host, I want to now fully migrate my existing fedora vps to this new nixos vps. to do so I want to bring in the configurations fedora vps has. 1. right now the nginx logic of my servers is disabled, because I let the fedora vps handle the reverse proxy through caddy. But I dont want that caddy logic, on nixos I want to let nginx take care of the reverse proxies, plus the logic is already backed in, there is a isLocal logic to the factory, and I dont remember exactly the name of the code. but there is some flag under the my. options that specifies the mainHost, the constitution mentions that mainHost is the host handling nginx and because the vps will be it, then main host needs to become vps, I think before it was miniserver. This change means, that all the currently enabled servers on the toggles.nix from the host server, should have the enableProxy flag on vps (double check the logic) this should make it so, that nginx runs on vps, and the servers run on server. 2. Add a step to ask me for the caddy files, just to check that the subdomains caddy handles for each server match the subdomains on the servers/.*nix files. 3. I use iptables on the fedora vps, and the nixos vps, well I dont mind you using another firewall but there are some complex firewall rules that I need them to work 100% as the original vps, the rules will be on a file named iptables (treat this as the reference ruleset for nftables parity), this is perhaps the most important step, otherwise the complex network configuration this vps has wont be able to hot swap and serve my servers to the world.
 
 4. modify the existing wireguard.nix module, doublecheck that isnt toggled anywhere, toggle it on vps and add this configuration to it
 [Interface]

specs/004-vps-migration/tasks.md

@@ -11,7 +11,7 @@ Deliver MVP as User Story 1 (primary host reverse proxy + keep services on host
 
 ## Phase 1: Setup
 
-- [x] T001 Confirm baseline files exist: iptables, secrets/ssh/ed25519_deploy.pub, secrets/ssh/ed25519_lidarr-reports.pub, secrets system entries for VPN keys
+- [x] T001 Confirm baseline files exist: iptables (reference ruleset), secrets/ssh/ed25519_deploy.pub, secrets/ssh/ed25519_lidarr-reports.pub, secrets system entries for VPN keys
 - [x] T002 Create working checklist placeholder for verification steps in /home/jawz/Development/NixOS/specs/004-vps-migration/tasks.md (this file)
 
 ## Phase 2: Foundational
@@ -34,11 +34,11 @@ Deliver MVP as User Story 1 (primary host reverse proxy + keep services on host
 
 ## Phase 4: User Story 2 (P1) - Firewall parity
 
-**Story goal**: Firewall behavior on new VPS matches old VPS by applying iptables ruleset as-is.
+**Story goal**: Firewall behavior on new VPS matches old VPS by implementing nftables/NixOS rules derived from the iptables reference.
 
 **Independent test criteria**: Known inbound/outbound flows match existing VPS behavior.
 
-- [x] T011 [US2] Apply firewall parity to VPS configuration using nftables/NixOS rules derived from the repo root iptables file and document any intentional deviations
+- [x] T011 [US2] Apply firewall parity to VPS configuration using nftables/NixOS rules derived from the repo root iptables reference and document any intentional deviations
 
 ## Phase 5: User Story 3 (P2) - Secure access and VPN peers
 
@@ -80,7 +80,7 @@ Deliver MVP as User Story 1 (primary host reverse proxy + keep services on host
 ## Parallel Execution Examples
 
 - US1: T007, T008, T009 can proceed once T003 and T006 are reviewed.
-- US2: T011 can proceed once iptables application location is identified.
+- US2: T011 can proceed once the iptables reference ruleset location is identified.
 - US3: T012, T016, T017, T018, and T020 can proceed after T004 and T005 review; T013 depends on user-provided secrets.
 - US4: T022, T023, T024 can proceed independently once logs are reviewed and quickstart.md is open.