From 8be5d8b22b41076cca5a641782409b27ad87e7dd Mon Sep 17 00:00:00 2001
From: Deepesh Kafaltiya <kafaltiyadeepesh@gmail.com>
Date: Mon, 1 Jun 2026 13:16:13 +0530
Subject: [PATCH 1/2] docs: add troubleshooting and local setup failsafe
 guidelines to README

---
 README.md | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f4c5d3f8..fb210b55 100644
--- a/README.md
+++ b/README.md
@@ -328,4 +328,43 @@ This project is released under the [MIT License](LICENSE).
 
 - `LICENSE` is the canonical legal text for this repository.
 - Contributions merged into this repository are distributed under the same MIT License unless explicitly stated otherwise.
-- Third-party tools, libraries, and external scanners referenced by SecuScan may have their own licenses and usage terms. Check upstream projects before redistributing bundled integrations.
\ No newline at end of file
+- Third-party tools, libraries, and external scanners referenced by SecuScan may have their own licenses and usage terms. Check upstream projects before redistributing bundled integrations.
+
+
+---
+
+## 🛠️ Troubleshooting & Local Setup Failsafe
+
+If your local environment glitches or throws errors during installation or launch, find your fast, actionable solution below.
+
+### 1. Stale Local Vite Module Cache
+**Symptoms:** Changes in your frontend components don't update in the browser, or Vite throws internal parsing/bundling syntax errors.
+**Fix:** Force Vite to ignore its stale cache and run a fresh reload:
+```bash
+cd frontend
+npm run dev -- --force
+
+### 2. Node Dependency Resolution Loops (`npm i` hanging/failing)
+**Symptoms:** `npm install` throws severe dependency tree conflicts, peer dependency errors, or hangs indefinitely.
+**Fix:** Force an override of strict package-lock rules using the legacy peer flags:
+```bash
+npm install --legacy-peer-deps
+
+###3. Missing or Mismatched Environment Variables
+**Symptoms**: The frontend loads, but API requests return undefined network targets, or authentication/scans fail to connect.
+**Fix**: Verify you have your local .env setup active. Run this in your root layout:
+```bash
+cp .env.example .env
+
+
+###4. Port 5173 Already in Use Error
+**Symptoms**: Terminal displays Port 5173 is already in use, using port 5174 instead.
+**Fix**: Kill the hidden background ghost process running on that port:
+
+```Windows (Command Prompt / PowerShell):
+```PowerShell
+Stop-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess -Force
+
+```Linux / macOS:
+```Bash
+kill -9 $(lsof -t -i:5173)
\ No newline at end of file

From 9f463f58dd63da167e609d5a4bf0ee05aed0ea45 Mon Sep 17 00:00:00 2001
From: Utkarsh Singh <183999732+utksh1@users.noreply.github.com>
Date: Tue, 2 Jun 2026 00:56:58 +0530
Subject: [PATCH 2/2] docs: fix troubleshooting markdown

---
 README.md | 49 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index fb210b55..d84cbb5e 100644
--- a/README.md
+++ b/README.md
@@ -333,38 +333,55 @@ This project is released under the [MIT License](LICENSE).
 
 ---
 
-## 🛠️ Troubleshooting & Local Setup Failsafe
+## Troubleshooting & Local Setup Failsafe
 
-If your local environment glitches or throws errors during installation or launch, find your fast, actionable solution below.
+Use these checks when local installation or launch fails.
 
 ### 1. Stale Local Vite Module Cache
-**Symptoms:** Changes in your frontend components don't update in the browser, or Vite throws internal parsing/bundling syntax errors.
+
+**Symptoms:** Frontend changes do not appear in the browser, or Vite reports internal parsing or bundling errors.
+
 **Fix:** Force Vite to ignore its stale cache and run a fresh reload:
+
 ```bash
 cd frontend
 npm run dev -- --force
+```
 
 ### 2. Node Dependency Resolution Loops (`npm i` hanging/failing)
-**Symptoms:** `npm install` throws severe dependency tree conflicts, peer dependency errors, or hangs indefinitely.
-**Fix:** Force an override of strict package-lock rules using the legacy peer flags:
+
+**Symptoms:** `npm install` reports dependency tree conflicts, peer dependency errors, or hangs indefinitely.
+
+**Fix:** Retry with the legacy peer dependency resolver:
+
 ```bash
 npm install --legacy-peer-deps
+```
+
+### 3. Missing or Mismatched Environment Variables
+
+**Symptoms:** The frontend loads, but API requests fail or scans cannot connect to the backend.
+
+**Fix:** Create a local `.env` file from the example file:
 
-###3. Missing or Mismatched Environment Variables
-**Symptoms**: The frontend loads, but API requests return undefined network targets, or authentication/scans fail to connect.
-**Fix**: Verify you have your local .env setup active. Run this in your root layout:
 ```bash
 cp .env.example .env
+```
+
+### 4. Port 5173 Already in Use
 
+**Symptoms:** Vite reports that port `5173` is already in use and switches to another port.
 
-###4. Port 5173 Already in Use Error
-**Symptoms**: Terminal displays Port 5173 is already in use, using port 5174 instead.
-**Fix**: Kill the hidden background ghost process running on that port:
+**Fix:** Stop the process using that port.
 
-```Windows (Command Prompt / PowerShell):
-```PowerShell
+Windows PowerShell:
+
+```powershell
 Stop-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess -Force
+```
+
+Linux or macOS:
 
-```Linux / macOS:
-```Bash
-kill -9 $(lsof -t -i:5173)
\ No newline at end of file
+```bash
+kill "$(lsof -t -i:5173)"
+```