USB SYSTEM TOOLKIT - COMPLETE USER GUIDE
===========================================

This guide covers every tool in the Additional Tools section (and the Network Repair tool), plus how they integrate with the main menu and Local AI Assistant.

HOW TO ACCESS TOOLS
-------------------
- From main menu: Choose 13 (Additional Tools) → select the number.
- Directly: Run the .ps1 (Windows) or .sh (Mac) from the tools/ folder.
- Via Local AI Assistant (option 12): Type natural phrases like "run event log analyzer", "backup my files", "show my gpu", "fix my network", etc. The AI will guide or launch the tool.
- For local copies (saved to Desktop via option 11): All tools work the same. Self-diagnostics and repair logs print directly in the chat/console instead of writing to a "drive" folder.

IMPORTANT NOTES FOR ALL TOOLS
-----------------------------
- Most tools are read-only or safe-by-default.
- Windows tools often benefit from running as Administrator for full access (the menu will note this).
- Mac tools may prompt for sudo/password for some actions.
- When running from a local copy (not the original USB), detailed reports and logs are printed in the console for you to copy/save manually.
- The Local AI remembers context and can suggest or run these tools for you.
- Self-Diagnostics (last item) validates that all tools are present and working.

================================================================================
TOOL 1: Event Log Analyzer
================================================================================
Purpose: Quickly view recent critical errors and warnings from Windows Event Logs or macOS logs.

Windows (.ps1):
- Pulls the last 50 Error/Warning events from System and Application logs.
- Shows Time, Level, Source, ID, and Message in a table.
- Tip: For more, use "Get-WinEvent -LogName System -MaxEvents 100 | Out-GridView" or filter by specific log.

Mac (.sh):
- Uses "log show" or equivalent to display recent errors.
- Good for kernel panics, app crashes, etc.

How to use:
- Menu: Additional Tools → 1
- AI: "show event logs", "analyze errors", "what crashed recently"
- Direct: Run the script; it prints and pauses.

Requirements: Standard user for basic view; admin for some protected logs.
Safety: Read-only. No changes made.
Tip: Great first step when something "just broke". Pair with self-diagnostics.

================================================================================
TOOL 2: Startup Manager
================================================================================
Purpose: List programs, services, and agents that start automatically with the OS.

Windows (.ps1):
- Uses Win32_StartupCommand to show Name, Command, Location.
- Tip: To disable, use msconfig, Task Manager > Startup tab, or Autoruns (portable).

Mac (.sh):
- Lists login items, launch agents/daemons from ~/Library and /Library.

How to use:
- Menu: Additional Tools → 2
- AI: "show startup items", "what starts with my pc", "disable startup programs"
- Direct run shows the list.

Requirements: Standard user (admin sees more system-wide items).
Safety: Read-only view. Disabling is manual.
Tip: High startup item count is a common cause of slow boot. Use with System Benchmark.

================================================================================
TOOL 3: Quick Backup Tool
================================================================================
Purpose: Quickly back up important user folders to a dated folder (on Desktop by default or the USB).

Windows (.ps1):
- Backs up Documents and Desktop to Desktop\backups\YYYY-MM-DD_HH-mm\
- Uses robocopy-style Copy-Item with error handling.

Mac (.sh):
- Similar logic using rsync or cp to ~/Desktop/backups/...

How to use:
- Menu: Additional Tools → 3
- AI: "backup my files", "quick backup", "save my documents"
- Direct: Run it; it creates the folder and copies.

Requirements: Write access to destination.
Safety: Non-destructive (copies only). No deletes.
Tip: Run before big changes or updates. For local copies, the backup goes to your Desktop.

================================================================================
TOOL 4: File Recovery Helper
================================================================================
Purpose: Guidance and quick checks for recovering deleted or lost files.

Windows (.ps1):
- Reminds to check Recycle Bin.
- Suggests File History / Previous Versions.
- Advanced: chkdsk guidance, portable Recuva recommendation.

Mac (.sh):
- Guidance for Time Machine, Trash, and third-party tools.
- diskutil and fsck hints.

How to use:
- Menu: Additional Tools → 4
- AI: "recover deleted file", "file recovery help", "I deleted something important"
- Direct: Prints steps and common commands.

Requirements: None for guidance; admin for chkdsk.
Safety: Purely informational. Does not attempt recovery itself (to avoid risk).
Tip: Act fast — the sooner you run this after deletion, the better the chances. Stop using the drive if possible.

================================================================================
TOOL 5: Malware Scan Launcher
================================================================================
Purpose: Quick start for built-in or recommended malware scanning.

Windows (.ps1):
- Launches Windows Defender Quick Scan (Start-MpScan -ScanType QuickScan).
- Suggestions for Full Scan and portable Malwarebytes.

Mac (.sh):
- Guidance for XProtect, MRT, and recommending Malwarebytes or similar.

How to use:
- Menu: Additional Tools → 5
- AI: "scan for malware", "run antivirus", "check for viruses"
- Direct: Starts the scan immediately.

Requirements: Windows Defender service running (usually is).
Safety: Starts the scan but does not quarantine without your approval in the Defender UI.
Tip: Run periodically or after suspicious downloads. Combine with Privacy Cleaner.

================================================================================
TOOL 6: Privacy Cleaner
================================================================================
Purpose: Clear recent files, temp data, and other privacy-sensitive caches.

Windows (.ps1):
- Removes Recent items, %TEMP%, etc. (with SilentlyContinue for safety).

Mac (.sh):
- Clears caches, recent items, .DS_Store, etc. where safe.

How to use:
- Menu: Additional Tools → 6
- AI: "clear privacy data", "clean temp files", "delete recent history"
- Direct: Runs the cleanups and reports what was done.

Requirements: Write access to user folders.
Safety: Uses -ErrorAction SilentlyContinue / 2>/dev/null. No system files touched.
Tip: Great before handing your PC to someone or selling it. Run the self-diagnostics after to confirm no breakage.

================================================================================
TOOL 7: Portable App Launcher
================================================================================
Purpose: Discover and launch portable apps stored on the USB or in a designated folder.

Windows (.ps1) / Mac (.sh):
- Lists subfolders in current directory (or USB root).
- Suggestions for common portables (Notepad++, 7-Zip, etc.).

How to use:
- Menu: Additional Tools → 7
- AI: "launch portable apps", "portable app launcher", "what portables do I have"
- Direct: Shows list; user can manually launch .exe / .app from the folder.

Requirements: Apps must be placed in the folder (or USB root for best results).
Safety: Pure launcher — does not install anything.
Tip: Copy your favorite portables to the USB root or a "portables" subfolder. The AI knows about this tool.

================================================================================
TOOL 8: Wi-Fi QR Code Generator
================================================================================
Purpose: Generate the Wi-Fi QR code string (WIFI:T:WPA;S:ssid;P:password;;) so you can easily connect other devices by scanning.

Windows (.ps1) / Mac (.sh):
- Detects current SSID.
- Prints the QR string and the netsh / airport command to retrieve the actual password (if you have it saved).

How to use:
- Menu: Additional Tools → 8
- AI: "wifi qr code", "show wifi password as qr", "connect phone to wifi"
- Direct: Run to get the string instantly.

Requirements: You must know or retrieve the password (the tool helps retrieve it on Windows).
Safety: Does not store or transmit anything. Just prints the standard Wi-Fi QR format.
Tip: Use a QR code generator app or website with the printed string to create a scannable image. Works great for guests.

================================================================================
TOOL 9: Note / Scratchpad
================================================================================
Purpose: Quick daily note-taking that saves to a consistent location (user notes folder or USB).

Windows (.ps1):
- Creates dated .txt in %USERPROFILE%\notes\ and opens in Notepad.

Mac (.sh):
- Similar logic, usually to ~/notes/ or Desktop, opens in default editor.

How to use:
- Menu: Additional Tools → 9
- AI: "take a note", "scratchpad", "open daily note"
- Direct: Creates/opens the file for today.

Requirements: Write permission to the notes folder.
Safety: Simple text append. No encryption (use for non-sensitive notes).
Tip: Great for quick thoughts while troubleshooting. The date in filename makes it easy to find later.

================================================================================
TOOL 10: System Benchmark Lite
================================================================================
Purpose: Quick CPU and disk performance snapshot.

Windows (.ps1):
- Shows processor name.
- Creates a small test file in %TEMP% and times the write (Measure-Command + fsutil).
- Suggests CrystalDiskMark for deeper tests.

Mac (.sh):
- Uses time + dd or similar for disk test + sysctl for CPU.

How to use:
- Menu: Additional Tools → 10
- AI: "benchmark my pc", "test disk speed", "how fast is my computer"
- Direct: Runs the tests and shows timings.

Requirements: Write access to temp folder. Disk test may need admin on some systems.
Safety: Creates and immediately deletes a small test file.
Tip: Run before/after optimization or when you suspect slowdowns. Compare numbers over time.

================================================================================
TOOL 11: Drive Health Dashboard
================================================================================
Purpose: Overview of physical disks, volumes, and health status (SMART where available).

Windows (.ps1):
- Get-PhysicalDisk (FriendlyName, MediaType, Size, HealthStatus, BusType).
- Get-Volume (DriveLetter, Label, free space, HealthStatus).
- Note: For full SMART, use CrystalDiskInfo portable.

Mac (.sh):
- diskutil list + df -h + system_profiler for disk details.

How to use:
- Menu: Additional Tools → 11
- AI: "drive health", "check disk smart", "is my drive failing"
- Direct: Prints tables.

Requirements: Standard user for basic info.
Safety: Read-only.
Tip: Red or "Failing" health status means back up immediately. Pair with quick_backup.

================================================================================
TOOL 12: Graphics / GPU Info
================================================================================
Purpose: Detailed information about graphics adapters, drivers, current resolution, and VRAM.

Windows (.ps1):
- Win32_VideoController (name, RAM, driver version, processor, resolution, refresh, status).
- Win32_DisplayConfiguration.
- Notes on how to get real-time temps (recommend portable GPU-Z).

Mac (.sh):
- system_profiler SPDisplaysDataType (chipset, VRAM, resolution, main display, etc.).

How to use:
- Menu: Additional Tools → 12
- AI: "show my gpu", "graphics info", "what graphics card do I have", "display resolution"
- Direct: Prints formatted info.

Requirements: None.
Safety: Read-only.
Tip: Use when troubleshooting graphics issues, games, or multiple monitors. The AI can also pull this data live.

================================================================================
TOOL 13: Display & Monitors
================================================================================
Purpose: Information about connected monitors, resolutions, and multi-display setup.

Windows (.ps1):
- Win32_DesktopMonitor details.
- Current settings per video controller (resolution, refresh, bits per pixel).

Mac (.sh):
- system_profiler SPDisplaysDataType focused on displays.

How to use:
- Menu: Additional Tools → 13
- AI: "display info", "monitor resolution", "multi monitor setup", "what resolution am I using"
- Direct: Prints the data.

Requirements: None.
Safety: Read-only.
Tip: Useful before/after graphics driver updates or when setting up projectors/second screens.

================================================================================
TOOL 14: Audio Devices & Sound
================================================================================
Purpose: List sound devices, status, and troubleshooting steps.

Windows (.ps1):
- Win32_SoundDevice (name, manufacturer, status).
- Audio endpoints where available.
- Built-in troubleshooter hint (msdt.exe).

Mac (.sh):
- system_profiler SPAudioDataType.

How to use:
- Menu: Additional Tools → 14
- AI: "audio devices", "sound not working", "list speakers", "microphone test"
- Direct: Shows devices + tips.

Requirements: None for listing.
Safety: Read-only. Troubleshooter is launched only if you choose.
Tip: Great when sound stops after updates or driver changes.

================================================================================
TOOL 15: Security & Firewall Status
================================================================================
Purpose: Snapshot of firewall profiles, Windows Defender / Security Center status, and macOS equivalents.

Windows (.ps1):
- Get-NetFirewallProfile (enabled, inbound/outbound actions).
- Get-MpComputerStatus (real-time protection, signatures, etc.).

Mac (.sh):
- socketfilterfw status (Application Firewall).
- csrutil status (SIP - System Integrity Protection).

How to use:
- Menu: Additional Tools → 15
- AI: "firewall status", "security status", "is defender on", "sip status"
- Direct: Prints the current state + quick tips.

Requirements: Standard user for most info.
Safety: Read-only.
Tip: Use before connecting to public Wi-Fi or after suspect downloads. Combine with privacy_cleaner.

================================================================================
TOOL 16: USB & Peripherals
================================================================================
Purpose: List connected USB devices, hubs, controllers, and basic status.

Windows (.ps1):
- Get-PnpDevice for USB class.
- Win32_USBHub / controllers.
- Status filtering.

Mac (.sh):
- system_profiler SPUSBDataType (and Thunderbolt if present).

How to use:
- Menu: Additional Tools → 16
- AI: "usb devices", "what is plugged in", "peripherals list", "bluetooth devices"
- Direct: Prints tree or table.

Requirements: None.
Safety: Read-only.
Tip: Excellent for "my USB drive isn't showing up" or "which port is this device on". Restart the menu after plugging/unplugging.

================================================================================
TOOL 17: Network Repair
================================================================================
Purpose: Perform a safe, logged reset of the network stack to fix common "no internet" or "can't connect" issues.

Windows (.ps1):
- Flush DNS, netsh winsock reset, netsh int ip reset, ipconfig /release + /renew.
- Attempts to restart key services.
- Full detailed log printed (and saved if on USB).
- Requires explicit YES confirmation.
- Temp connection loss expected.

Mac (.sh):
- Flush DNS (dscacheutil), restart mDNSResponder.
- Guidance for SMC/NVRAM reset and manual steps.

How to use:
- Menu: Additional Tools → 17
- AI: "fix my internet", "repair my network", "reset wifi", "no connection"
- Direct: Run and follow the prompts.

Requirements: Admin recommended for full Windows reset.
Safety: Confirmation required. Everything is logged. Non-destructive (resets config, does not delete user data).
Tip: Run this before calling support for "the internet is broken". Reboot after. Works great from the AI when you're frustrated.

================================================================================
TOOL 18: Full PC Diagnostic (complete scan + analysis + troubleshooting tips)
================================================================================
Purpose: A single comprehensive diagnostic that scans the entire PC, identifies problems with clear descriptions, and provides specific troubleshooting tips.

Windows (.ps1):
- Collects: OS/hardware details, RAM usage, storage space/health (SMART via PhysicalDisk), CPU/process load, graphics status, network connectivity, basic Defender status, recent System log errors.
- Analysis: Flags CRITICAL/WARNING conditions (e.g. RAM >90%, disk >95% full, unhealthy physical disks, high CPU from top processes, no active adapters, high recent errors, etc.).
- Output: Clear summary of issues + detailed report with actionable tips (often referencing other menu tools or exact commands like sfc /scannow).
- Respects local copy: prints everything in the chat.

Mac (.sh):
- Uses system_profiler, df, memory_pressure, kernel panic logs, ping, etc.
- Similar analysis for storage, memory pressure, crashes, network.
- Outputs summary + tips + saves report when on USB.

How to use:
- Menu: Additional Tools → 18 (or 19 depending on numbering).
- AI: "run full pc diagnostic", "complete system scan", "what's wrong with my pc", "diagnose entire system", "full pc check".
- Direct: Run the script; it prints the full analysis and tips.

Requirements: Standard user for most data; admin recommended for deeper logs.
Safety: Read-only data collection + analysis. No automatic changes.
Tip: This is the "one script for complete diagnostic" you asked for. Run it when the PC feels "off" overall. It ties together the individual tools and gives prioritized tips. Re-run after fixes to verify improvement.

================================================================================
TOOL 19: Toolkit Self-Diagnostics
================================================================================
Purpose: Read-only health check of the entire toolkit (files, syntax, AI features, menu consistency, hardcoded paths, etc.).

Windows (.ps1) / Mac (.sh):
- Checks core files, all tools present.
- Syntax validation for .ps1 (Parser) and .sh (bash -n).
- AI feature checks (help list, proactive suggestions, matching for shortcut/repair/mental health/pickup lines, calculator support, etc.).
- Menu consistency between platforms.
- Hardcoded drive letter warnings.
- Reports errors/warnings.
- Saves short report to reports/ (or prints in chat for local copies).
- Appends summary to central log (USB only).

How to use:
- Menu: Main menu 14 or Additional Tools → last item (18 or 19 depending on count).
- AI: "run self diagnostics", "check toolkit health", "is everything working"
- Direct: Run the script from tools/ or USB root.

Requirements: Read access to all toolkit files.
Safety: 100% read-only. Never modifies your PC or the drive (except the optional report file and log append on USB).
Tip: Run this regularly, especially after copying the toolkit locally or adding new tools. It will tell you exactly what needs attention (e.g., missing tool, old reference, AI feature gap).

================================================================================
ADDITIONAL NOTES
================================================================================

- Core Menu Functions (not separate files): The main options 1-12 (System Overview, Hardware, Storage, Network, Top Processes, Optimization, Reports, Quick Tools, etc.) are built into the menu scripts. The AI can trigger most of them directly.

- Local Copy Behavior: When you use option 11 to save a copy to your Desktop, reports from self-diagnostics and repair tools are printed in the chat instead of relying on a "drive" folder. All tools remain functional.

- AI Integration: The Local AI (option 12) has been expanded with hundreds of response variations and support for natural phrases across all tools. Type "help" or "examples" inside the AI for the full current list.

- Safety Philosophy: Every tool that can change something asks for confirmation or uses "SilentlyContinue" + logging. Self-diagnostics and most info tools are strictly read-only.

- Updating: After adding tools or making changes, run Self-Diagnostics. It will validate the new items.

- Reporting Issues: The central diagnostics/toolkit_error_log.txt (on the original USB) collects run summaries for review.

Run the toolkit, explore the Additional Tools menu, and ask the Local AI for help with any of them. Everything is designed to be discoverable and safe.

If you add more tools in the future, simply update this USERGUIDE.txt and the ExpectedTools lists in both self_diagnostics scripts.

Enjoy your toolkit!
