Downloads Detective 1.0.0
=========================

Downloads Detective scans your Downloads folder, explains clutter, verifies file/folder relationships, and gives you guarded ways to move, recycle, rename and undo selected actions.

Quick start
-----------
1. Run DownloadsDetective.exe. The current Downloads folder scans automatically.
2. Choose Normal for the everyday package-aware view or Deep for forensic nested-file inspection. Changing the scan mode automatically restarts the scan.
3. In the Folders view, press Enter on a folder overview to scan into it. Pressing Enter on an empty folder simply tells you it is empty. Double-click opens the selected folder/item normally. Alt+Up returns to the parent; Ctrl+D returns directly to Downloads. Previously scanned unchanged folders restore instantly.
4. Alt+Up from the Downloads root asks before leaving Downloads. Tick "Don't ask again this session" if you do not want repeated warnings until the app restarts.
5. Shift+S toggles Normal/Deep. Ctrl+PageUp / Ctrl+PageDown move through the result tabs. These shortcuts and Ctrl+D can be changed under Settings > Hotkeys. Configurable hotkeys are ignored while typing.
6. Your selected result tab stays selected while you navigate between folders or change scan mode. Enter performs the in-app scan/drill action; double-click opens the selected item normally.
7. Review why an item was flagged before acting.

What the confidence colours mean
--------------------------------
- Pale green = content-verified evidence, such as an exact duplicate group or a ZIP whose extracted folder was verified file-by-file.
- Pale amber = a strong near-duplicate or contained-folder relationship. Differences may matter, so these are review-only.
- Uncoloured REVIEW rows are useful clues, not deletion claims.

Folder relationships
--------------------
Exact duplicate folders:
- Outer folder names can differ.
- Every meaningful file must have the same relative path, size and SHA-256 content.
- Known OS metadata such as desktop.ini / Thumbs.db is ignored consistently.
- Deep mode collapses redundant file-level duplicates already explained by the exact folder package.

Near-duplicate folders:
- Used for substantial, content-verified overlap rather than exact identity.
- Both file-count similarity and byte similarity are shown so thousands of tiny matching files cannot hide one huge changed file.
- The Comparison tab lists changed files, files only on one side and representative exact matches.
- Near-duplicates never count as automatic cleanup.

Folder contained in another:
- Every meaningful file in the smaller folder has been verified at the same relative path in the larger folder.
- The larger folder contains additional content.
- This is a strong review signal, but Downloads Detective does not assume the smaller folder path is unused.

Archives and extracted folders
------------------------------
For a root ZIP and same-stem root folder, Downloads Detective can inspect the ZIP itself.
- If every meaningful ZIP file matches the extracted folder by relative path, size and SHA-256, the row becomes CONFIRMED "Archive fully extracted" and is highlighted green.
- If the ZIP/folder differs, or the archive format cannot currently be inspected natively, the relationship stays REVIEW-only and the explanation says why.
- Verified extracted ZIP size contributes to Potential cleanup, but Downloads Detective still leaves the keep/archive decision to you.

Installer version families
--------------------------
Root-level installer filenames that look like different versions of one product are grouped together. Downloads Detective identifies the highest numeric filename-version candidate and lists the family. Architecture remains part of the family identity, so x86, x64 and ARM64 installers are not mixed together. This is filename-based evidence only: older installers are never automatically declared safe to remove.

Potential cleanup and selected size
-----------------------------------
Potential cleanup includes only strong signals: verified duplicate copies, verified fully-extracted ZIP archives and stale incomplete downloads.

When you select rows, the status bar shows:
- Selected: number of rows
- Size: de-duplicated size represented by the selected rows
- Reclaimable: de-duplicated cleanup opportunity when one can be calculated

Recycle confirmed duplicate copies
----------------------------------
Choose the copy to keep. The cleanup dialog now lets you choose the verification level before recycling:
- Full byte-for-byte re-verification (default/recommended): hashes the keep copy and each duplicate again immediately before the Recycle Bin action. Safest, but can take time for huge folders/videos.
- Fast tree/size safety check: verifies the folder tree/file lengths (or file length for a loose file) without re-reading every byte. This is much faster, but a same-size content change could be missed.

Fast mode is therefore an explicit trade-off, not a silent optimisation. The final confirmation repeats the choice. No permanent-delete command exists; duplicate cleanup always uses the Windows Recycle Bin. The app rescans after a successful cleanup so the visible findings reflect the current Downloads folder.

Filename variants
-----------------
The Filename variants tab groups browser-style names such as report.pdf, report (1).pdf and report (2).pdf. Matching names do not imply matching content; this is a clutter clue, not an exact-duplicate claim.

Naming Assistant
----------------
The desktop Naming Assistant can watch one Downloads folder while Downloads Detective is open or running in optional tray background mode.
- Ask once: choose the target filename the first time; later copies use it automatically.
- Auto replace: repeated browser-style names use the clean target automatically.
Previous targets are staged for rollback and sent to Recycle Bin only after replacement succeeds.

Browser Companion (optional)
----------------------------
Open Settings > Browser Companion & Background.
- Extension status tells you whether Chrome/Edge has actually contacted Downloads Detective.
- Native host status tells you whether registration exists and whether the stable host passes its self-test.
- Click Set up Chrome… or Set up Edge… for guided setup.

Downloads Detective installs the verified self-contained BrowserHost and extension files into a stable LocalAppData folder. Chrome/Edge still require one explicit approval for an unpacked extension. Setup tries to open the Extensions page automatically, but Chromium browsers can block external navigation to chrome:// / edge:// pages. The UI therefore shows the exact route: type chrome://extensions/ (or edge://extensions/) in the browser address bar, turn on Developer mode in the top-right, click Load unpacked, and select the folder Downloads Detective opens.

Once connected, Browser Companion can choose the clean filename before the browser commits the download, keeping browser history aligned with the real file. Ask Once rules are website-aware.

Move a completed browser download
---------------------------------
Open the Downloads Detective extension from the browser toolbar and choose Move original… beside the file. Pick a destination and Downloads Detective moves the original out of Downloads rather than leaving a second copy. Chrome's own Downloads-tray drag is browser-controlled and may copy on Windows.

Background mode
---------------
Settings > Browser Companion & background… can keep Downloads Detective in the system tray after the main window closes. Start with Windows is optional.

Undo / restore
--------------
Ctrl+Z or Actions > Undo last move/rename restores the most recent eligible safe Move/Rename if the original path is still free. Activity History also offers Undo selected move/rename. Files sent to Recycle Bin can be restored from Windows Recycle Bin.

Safety
------
- No permanent-delete command exists.
- Exact duplicate identity uses SHA-256 verification.
- Full duplicate re-verification remains the default before recycling; skipping it requires an explicit user choice and still performs a tree/size safety check.
- Near-duplicate and contained-folder relationships remain review-only.
- Replacement uses rollback staging.
- Reparse-point items/directories are guarded and archive verification does not traverse them.
- Browser rollback staging is hidden from normal scan results.
- Activity History records filesystem actions.
