docs: resolve all code review feedback (security, safety, formatting)

Author: MChandrahas

docs/TROUBLESHOOTING.md

@@ -20,7 +20,7 @@ Common errors and solutions for Cortex Linux.
 ### Error: "No API key found"
 
 **Symptom:**
-```
+```text
 Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable.
 ```
 
@@ -29,15 +29,15 @@ Error: No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment var
 1. **Set the environment variable:**
 ```bash
 # For Claude (recommended)
-export ANTHROPIC_API_KEY='sk-ant-api03-your-key-here'
+export ANTHROPIC_API_KEY='<YOUR_ANTHROPIC_API_KEY>'
 
 # For OpenAI
-export OPENAI_API_KEY='sk-your-key-here'
+export OPENAI_API_KEY='<YOUR_OPENAI_API_KEY>'
 ```
 
 2.  **Add to shell config for persistence:**
 ```bash
-echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.bashrc
+echo 'export ANTHROPIC_API_KEY="<YOUR_ANTHROPIC_API_KEY>"' >> ~/.bashrc
 source ~/.bashrc
 ```
 
@@ -46,7 +46,8 @@ source ~/.bashrc
 cortex wizard
 ```
 
-4.  **For offline mode (no API key needed):**
+4. **For Local Provider mode (No API key needed):**
+   *Note: Installation of tools like Docker may still require an internet connection.*
 ```bash
 export CORTEX_PROVIDER=ollama
 cortex install docker
@@ -55,7 +56,7 @@ cortex install docker
 ### Error: "API rate limit exceeded"
 
 **Symptom:**
-```
+```text
 Error: Rate limit exceeded. Please wait before trying again.
 ```
 
@@ -70,14 +71,14 @@ sleep 60 && cortex install docker
 export CORTEX_PROVIDER=ollama
 ```
 
------
+---
 
 ## Installation Errors
 
 ### Error: "Package not found"
 
 **Symptom:**
-```
+```text
 E: Unable to locate package xyz
 ```
 
@@ -107,10 +108,11 @@ sudo apt --fix-broken install
 sudo apt update && sudo apt upgrade
 ```
 
+
 ### Error: "dpkg lock"
 
 **Symptom:**
-```
+```text
 E: Could not get lock /var/lib/dpkg/lock-frontend
 ```
 
@@ -121,18 +123,26 @@ E: Could not get lock /var/lib/dpkg/lock-frontend
 sudo lsof /var/lib/dpkg/lock-frontend
 ```
 
-2.  **Kill stuck apt process (use with caution):**
+2. **If it's genuinely stuck, stop the specific process (use with caution):**
 ```bash
-sudo killall apt apt-get
+# Check for apt, apt-get, or unattended-upgrades
+ps aux | egrep 'apt|apt-get|unattended' | egrep -v egrep
+
+# Then (only if needed) kill the specific PID (replace <PID>):
+sudo kill <PID>
+
+# Recovery: Run these if the package manager breaks after killing the process
+sudo dpkg --configure -a
+sudo apt --fix-broken install
 ```
------
+---
 
 ## Network & Connectivity
 
 ### Error: "Could not resolve host"
 
 **Symptom:**
-```
+```text
 Could not resolve 'archive.ubuntu.com'
 ```
 
@@ -143,11 +153,17 @@ Could not resolve 'archive.ubuntu.com'
 ping -c 3 8.8.8.8
 ```
 
-2.  **Try different DNS (Safe Method):**
+2.  **Try different DNS (Temporary):**
+    *Note: `/etc/resolv.conf` is often overwritten. Use `resolvectl` for permanent changes.*
 ```bash
+# Append Google DNS
 echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf
+
+# Rollback (Undo): Edit the file and remove the line
+sudo nano /etc/resolv.conf
 ```
 
+
 ### Error: "SSL certificate problem"
 
 **Solutions:**
@@ -163,7 +179,7 @@ sudo update-ca-certificates
 timedatectl status
 sudo timedatectl set-ntp true
 ```
------
+---
 
 ## Permission Problems
 
@@ -181,33 +197,44 @@ sudo cortex install docker --execute
 ls -la ~/.cortex/
 ```
 
------
+---
 
 ## LLM Provider Issues
 
 ### Error: "Ollama not running"
 
 **Symptom:**
-```
+```text
 Error: Could not connect to Ollama at localhost:11434
-```
+````
 
 **Solutions:**
 
-1.  **Start Ollama:**
+1.  **Start System Service (Recommended):**
+
+```bash
+sudo systemctl start ollama
+```
+
+2.  **Manual Start (Fallback):**
+    *Note: Only use this if the system service is unavailable.*
+
 ```bash
-ollama serve &
+ollama serve
 ```
 
-2.  **Install Ollama if missing:**
+3.  **Install Ollama if missing:**
+    *Note: Always review remote scripts before running them.*
+
 ```bash
 curl -fsSL https://ollama.com/install.sh | sh
 ```
 
 ### Error: "Context length exceeded"
 
 **Symptom:**
-```
+
+```text
 Error: This model's maximum context length is 4096 tokens
 ```
 
@@ -218,17 +245,18 @@ Error: This model's maximum context length is 4096 tokens
 
 2.  **Change Provider:**
     Switch to a provider that supports larger context windows (e.g., Anthropic) using the wizard:
+
 ```bash
 cortex wizard
 ```
------
+---
 
 ## Package Manager Conflicts
 
 ### Error: "Snap vs apt conflict"
 
 **Symptom:**
-```
+```text
 error: cannot install "firefox": classic confinement requires snaps
 ```
 
@@ -238,7 +266,7 @@ error: cannot install "firefox": classic confinement requires snaps
 ```bash
 sudo snap install firefox --classic
 ```
------
+---
 
 ## Performance Issues
 
@@ -255,7 +283,7 @@ export CORTEX_PROVIDER=ollama
 ```bash
 ping api.anthropic.com
 ```
------
+---
 
 ## Rollback & Recovery