Explorer-Workbench/docs/Documentation.md

# Explorer Workbench

Personal file management workbench for Windows. The goal is to make **working with files** faster — not to replace the filesystem, and not to silently change Windows configuration.

Mental model:

> Open Explorer Workbench → see files → manage files → search immediately → analyze storage.

Windows remains the source of truth. Removing a location from Workbench removes Workbench’s index data for it. It does **not** disconnect a network drive, unlink OneDrive, or change Explorer settings.

Version documented here: **0.1** (schema 9). This file is the user guide. Edit it in any text editor; Explorer Workbench reloads it when you open **Help → Documentation**.

---

## What it is (and is not)

Workbench **does**:

- Browse live folders (local, removable, network, cloud mounts)
- Index locations you choose, then search and analyze them
- Queue copy, move, recycle, rename, archive, convert, sync, and organize work
- Overlay Git and cloud status without becoming a Git client or a sync engine

Workbench **does not**:

- Two-way sync
- Hydrate online-only cloud files just to look at them
- Change Windows drive mappings or cloud client folders
- Replace Git (no stash, branch UI, mergetool, or credential dialog)

Specialized tools still do specialized jobs. 7-Zip compresses. FFmpeg converts a few media kinds. Git reports status, shows diffs, commits selected files, resolves conflicts, and runs fetch, pull, and push. Workbench orchestrates.

---

## First launch

1. The window starts `Explorer.Host.exe` if it is not already running, then connects over a named pipe. Locations fill in a moment later — Workbench does not wait for slow network shares.
2. Browsing works with an empty index.
3. Folder sizes, search, duplicates, and storage analysis need an index. Use the banner **Build index**, **Tools → Locations → Index this location**, or the toolbar **Index** control.
4. Data lives under `%LocalAppData%\ExplorerWorkbench\` — never beside the executable.
5. Closing the window leaves the host running (indexing and the queue). A tray icon **Explorer Workbench host** can open the window again or **Quit background host**. **File → Stop background host…** does the same from the window.

| Path | Contents |
| --- | --- |
| `%LocalAppData%\ExplorerWorkbench\index.db` | Index, queue, profiles |
| `%LocalAppData%\ExplorerWorkbench\logs\` | Rolling logs |
| `%LocalAppData%\ExplorerWorkbench\ui-preferences.txt` | Theme, layout, tool paths, organize destinations, favorite folders, saved name patterns, Move to history |

---

## Window layout

- **Title bar** — Explorer Workbench; minimize / maximize / close.
- **Menu** — File (including Stop background host), View, Tools, Settings, Help. Tools is grouped: Storage, Locations, File Operations (including Archives and Convert), Automation, Development, Recycle Bin.
- **Toolbar** — navigation, view mode, search.
- **Tree** — Favorites, Home, This PC, Network, Cloud (Network/Cloud grouping and tree synchronization are in Settings → Navigation).
- **Folder pane** — breadcrumb bar (click the empty space, or `Ctrl+L` / `Alt+D`, to type a path), then details, list, or preview. Split pane is optional.
- **Status bar** — item count and size for the active folder, or for the current selection; Git badge; queue.
- **Queue** — compact status; expand for the full File Operations Queue.

### Tabs and panes

| Action | How |
| --- | --- |
| New tab | File → New tab, or `Ctrl+T` |
| Close tab | File → Close tab, or `Ctrl+W` |
| Split pane | File → Split pane |
| Details / List / Preview | View menu or toolbar |
| Type a path | Click empty space in the tab breadcrumb bar, or `Ctrl+L` / `Alt+D` |
| Refresh | View → Refresh, or `F5` |

Tabs, split panes, and the folder shown in each pane are restored the next time you open Workbench.

---

## Locations

### Favorites

Pinned folders of your choosing, at the top of the tree. Add a folder with **Add to Favorites** on the folder or tree context menu, or drop a folder onto the Favorites root. Remove it with **Remove from Favorites**. Unpinning only removes the pin — it does not delete files, forget a location, or change the index.

Favorites are stored in `ui-preferences.txt`. A pin that points at a missing folder still appears, marked Offline, so you can unpin it.

The folder pane always shows the real filesystem path. Breadcrumbs stay the same. The locations tree is separate: by default it keeps the branch you are already in. Opening a folder under This PC, Home, Network, or Cloud does not switch the tree to Favorites just because that folder is also pinned. If you opened the folder from a Favorite, the tree stays under Favorites. **Settings → Navigation → Prefer Favorites when synchronizing the locations tree** selects a matching Favorite pin instead.

### Home

Documents, Downloads, Pictures, Videos, and Music from Windows known folders. They have their own root, not under This PC. Folders that do not exist on this PC are omitted.

### This PC

Local NTFS volumes and removable disks. Capacity and free space show next to size where Windows reports them.

### Network

Add a UNC path with **Tools → Locations → Add network…** (`\\server\share`). Mapped Windows drive letters can be imported when Workbench discovers them. Forgetting a Workbench location does **not** disconnect the Windows mapping.

After a Windows start, shares can show **Offline** until they answer. Opening a folder or a file on the share marks it online in the tree; sleeping NAS boxes may take a second or two.

### Cloud

OneDrive, Google Drive, and Nextcloud appear when you add their **mounted Windows folders** (**Tools → Locations → Add OneDrive…** / **Google Drive…** / **Nextcloud…**). Workbench browses those paths with Win32 like any other folder. Plugins only overlay status, pin/dehydrate actions, and quota. Cloud folders stay ordinary locations — they are not a separate “cloud filesystem.”

Online-only placeholders are **not** hydrated to compute size, search content, hash duplicates, or pack archives. Status text on the item tells you when a file is online-only.

### Recycle Bin

Open it from **Tools → Recycle Bin**. Workbench talks to the real Windows Recycle Bin. Emptying it is a queued operation. `$RECYCLE.BIN` folders on volumes are hidden from normal browsing.

### Remove vs restore

- **Remove from Explorer** forgets the Workbench location and its index rows.
- Windows resources stay. You can import them again from discovery.

---

## Browsing and file management

The open folder is always the live filesystem when the location is online. Index data fills in folder sizes, search, and analysis.

Large folders appear as soon as names are known — the previous folder stays on screen until the first new name arrives. Size, date, and type from the directory listing show with the row. **Details** also has Date created, Git, and Cloud. Git is blank for clean tracked files; otherwise Modified, Staged, Untracked, Unmerged, or a nested-repo badge. Cloud is blank unless the overlay has a state (Online-only, Local, Pinned, Syncing, Error). Free space is shown only on This PC (and other listings that actually have volume free space). Cloud status, indexed folder totals, and Git fill in shortly after — blank cells mean that extra metadata has not arrived yet, not that the file is empty. Opening another folder cancels leftover work from the previous one. The status bar shows how many items are in the active folder and their known size; with a selection it switches to how many are selected and the size of that selection. Folder sizes appear in the total once the index has them.

Right-click a file or folder to get Workbench commands plus extra Windows items that fit in the compact menu (PDF24, 7-Zip, and similar). **Open in Notepad++** and **Open in Cursor** are Workbench entries next to **Open terminal here**. Open, Cut, Copy, Delete, and Rename stay Workbench’s own entries so they are not listed twice. Listing those items does not download online-only cloud files; running one of them is an explicit open and may hydrate.

**Preview** shows a wrapping thumbnail grid. Only the tiles on screen (plus a small prefetch) are decoded, on background threads. Other files keep a generic icon until you scroll to them. Online-only cloud files are never opened just to make a thumbnail. Returning to a folder reuses thumbnails that are still in memory.

Sorting by name or type happens once the listing is in. Sorting by size waits until indexed folder totals are applied, so rows do not jump on every update. Clicking a column sorts immediately with whatever is already known.

Hidden files follow Settings → Navigation. Protected system locations (`System Volume Information`, Recovery, pagefile, and similar) are hidden unless you turn them on. Recycle Bin folders stay hidden. Access-denied folders show as access denied — never as 0 bytes.

| Shortcut | Action |
| --- | --- |
| `Alt+Left` / Back | Back |
| `Alt+Right` | Forward |
| `Alt+Up` | Up |
| `F5` | Refresh |
| `Enter` | Open |
| `F2` | Rename (single item, immediate) |
| `Ctrl+A` | Select all |
| `Ctrl+C` / `Ctrl+X` / `Ctrl+V` | Copy / Cut / Paste |
| `Delete` | Recycle (queued) |
| `Escape` | Cancel rubber-band selection |
| `Ctrl+T` / `Ctrl+W` | New tab / Close tab |

Drag an empty area of the folder list to rubber-band select, as in File Explorer. The rectangle selects every row it touches in Details and List, and every tile it intersects in Preview. `Ctrl` adds to the current selection; `Escape` restores the previous one. Right-drag selects, then opens the context menu.

Drag and drop copies by default. Hold `Shift` to move. Right-drag of selected items offers a menu.

Hidden files follow Settings → Navigation. Protected system locations (`System Volume Information`, Recovery, pagefile, and similar) are hidden unless you turn them on. Recycle Bin folders stay hidden. Access-denied folders show as access denied — never as 0 bytes.

---

## Index and search

Indexing is **user-triggered**, then kept current in the background:

- Local NTFS: USN journal when Windows allows it; otherwise folder reconcile + watcher
- Network: scan + watcher (best effort)
- Archives: optional (Settings → Indexing → include archive contents)
- Folder sizes in Details come from the index. Opening a folder reconciles **that folder only**, then probes the largest or visible child folders (child count vs index). A mismatch queues a targeted verify of that child — not a walk of C:\. Navigating away cancels further probes. Idle maintenance still verifies whole local drives.
- After the PC has been idle (Settings → Indexing), the background host checks local indexed drives for folders whose contents no longer match the index. A full rescan still happens only when a drive is marked out of date or has not been indexed for 7 days.
- Before Delete, Workbench checks that the path still exists and refreshes that folder in the index. Leftovers under Program Files can still fail if Windows needs administrator rights — that is separate from the stale size.
- Idle maintenance: when the PC has been idle (Settings → Indexing), the background host may hash duplicates, recapture history, and rescan stale **local** indexes. Copy, move, delete, explicit scans, and sync you started are not idle work and keep running. Cloud files are never hydrated. Network, cloud, and removable locations are not scanned just because the PC is idle.

Default excludes include Windows, recycle bins, `node_modules`, `.git`, and similar. Inaccessible paths are skipped.

Search uses the index: name/glob plus size, type, and date filters. Results are paged (500, hard cap 10 000). Offline volumes stay searchable from the last index; the live folder listing still needs the volume.

Archive hits can look like:

`\\NAS\Archive\2019-backup.7z\Projects\README.md`

even when that NAS is currently offline — if the archive was indexed earlier.

---

## Storage analysis

**Tools → Storage → Storage analysis** (or the toolbar). WinDirStat-style trees, biggest folders/files, by type, by source. Figures come from the index, so build the index first.

**Tools → Storage → Run background maintenance now** runs the same idle-maintenance pipeline immediately (still skipped while a copy/move/delete is running). The status bar may show Idle maintenance, Scanning a location, or Paused because user is active.

---

## Development tools

**Tools → Development → Host activity…** opens a live monitor of the background host: maintenance, indexing jobs, hashing, transfers, and a rolling activity log. It refreshes about every 1.5 seconds while open and also reacts to push events; closing it stops the polling.

**Tools → Development → Database…** opens a general SQLite viewer. It starts on the Workbench index (`%LocalAppData%\ExplorerWorkbench\index.db`) in read-only mode while the host holds the write lock. Use **Open file…** for any other `.db`, and choose write mode when the file is not locked. You can browse tables, run SQL, and — when writable — edit cells, insert rows, and delete rows.

## Duplicates

**Tools → Storage → Duplicates**. Groups come from the **index** (hashed in the background: size → partial hash → full hash only when needed), not from a live walk of the disk. The list fills from the index first (largest groups at the top); missing copies are dropped afterwards without blocking the window. A finished full scan of the drive also marks missing trees deleted; cancelling a scan does not. Unmarked groups have no class label. After you mark a group, Workbench shows:

| Class | Meaning |
| --- | --- |
| Accidental | Same content, no known reason |
| Synchronized | Created by Folder Sync |
| Intentional | You marked them |
| Hardlink | Same file id on the same volume |
| Backup | Reserved; not auto-tagged yet |

Intentional and sync copies are hidden by default. Hardlinks are not wasted space.

---

## File Operations Queue

Almost every change goes through the queue instead of happening silently.

Supported operations today: copy, move, recycle, permanent delete, rename, empty Recycle Bin, extract, compress, add to archive, verify archive, convert.

The queue:

- Runs **one operation at a time**
- Can pause / resume / pause all
- Lets you reorder, remove, retry, and clear finished items
- Survives Workbench restarts
- Waits when the destination is unreachable (network share, USB) and continues when it returns
- Records append-only history
- Fails locked files so you can retry

Auto-clear when done is a setting. Failed items stay until you dismiss or retry them.

**Undo** exists for completed **rename batches**. Copy and move are not undone from the queue in this build.

---

## Batch rename

**Tools → File Operations → Batch rename…** (select items first). F2 stays a single immediate rename.

Workflow: configure → preview → validate → queue.

Rules: search/replace, regex, prefix, suffix, counter (with padding), case, extension. An optional **name pattern** can replace the current name using placeholders: `{Artist}`, `{Title}`, `{Album}`, `{Track}`, `{Year}`, `{Genre}`, `{CreatedDate}`, `{TakenDate}`, `{ModifiedDate}`, `{Width}`, `{Height}`, `{Name}`, `{Extension}`, `{Parent}`, `{Project}`, `{Counter}`. Dates accept a format (`{TakenDate:yyyyMMdd}`). `{CreatedDate}` uses EXIF Date Taken when that was already read; `{TakenDate}` is the token that reads photo metadata. `{Project}` is the Git repository folder, or the parent folder if the file is not in a repo. **Save pattern** stores a custom pattern in `ui-preferences.txt` (built-in patterns stay in the list: `{Artist} - {Title}`, `{Track:00} - {Title}`, `{TakenDate}_{Name}`, `{CreatedDate}_{Name}`, `{Project}_{Name}`). Collisions and illegal Windows names are caught before enqueue. Completed batches can be undone (**Tools → File Operations → Undo last rename batch**).

**Tags…** (select files first) is the Tag&Rename-style editor. **Filename → tags** fills Artist/Title/… from the current names using the same pattern. **Tags → filename** builds new names from tags. **Queue tags** writes ID3 on audio and EXIF (title, comment, creator, date taken) on photos through the File Operations Queue; **Queue rename** queues the new names. Online-only cloud files are skipped so they are not downloaded.

---

## Move to

**Tools → File Operations → Move to…** or **Move to…** on the item context menu (select items first).

Not a plain “move into this folder”. The destination is a **pattern**. Placeholders expand per file, missing folders are created, then the move is queued.

| Token | Meaning |
| --- | --- |
| `%filename%` | Name including extension |
| `%filename_noext%` | Name without extension |
| `%ext%` | Extension without the dot |
| `%year%` / `%month%` | Last-write time (`2024` / `08`) |
| `%parent%` | Parent folder name |
| `%source_drive%` | Drive (`D:`) or UNC share (`\\10.0.0.31\media`) |

`{filename_noext}` and the other `{…}` forms work the same.

Plex-style movies: `\\10.0.0.31\media\movies\%filename_noext%` creates `movies\Inception\` and places `Inception.mkv` inside it. If the last segment is `%filename%` or `%ext%`, the pattern is the full destination file path.

Type the path in the text box (or **Browse…**), then click a token to insert it at the caret. **Recent** lists saved patterns; the `\\host\share\…` row is only an example and is rejected if you queue it. **Queue** and **Save** store real patterns in `ui-preferences.txt` (`move-to=`).

If a UNC share or mapped drive is disconnected, Workbench tries to reconnect it (same credentials, no extra prompt). Jobs that still cannot reach the destination wait in the queue; **Retry** re-probes and reconnects. Online-only cloud files are skipped.

---

## Archives

Needs **7-Zip** on the machine (Settings → File Operations can point at `7z.exe`; otherwise Program Files and PATH). 7-Zip is not bundled.

| Action | Menu |
| --- | --- |
| Extract here / Extract to… | Tools → File Operations → Archives, or context menu |
| Compress to ZIP / 7z | Tools → File Operations → Archives, or context menu |
| Add to archive… | Tools → File Operations → Archives |
| Verify archive | Tools → File Operations → Archives |

Jobs go through the queue. Online-only cloud archives are refused so Workbench will not hydrate them. Formats include ZIP, 7z, RAR, TAR and related containers through 7-Zip.

---

## Convert

Needs **`ffmpeg.exe`** on the machine. FFmpeg is usually a zip, not an installer: unpack a Windows build and either put `ffmpeg.exe` on PATH, under `Program Files\ffmpeg\bin\`, or point Settings → File Operations at the file. `ffprobe` / `ffplay` are not required. FFmpeg is not bundled. This is not HandBrake — a few conversions only.

| Kind | Output |
| --- | --- |
| Video to H.264 MP4 | `.mp4` next to the source, or in a folder you pick |
| Extract audio | AAC in `.m4a` |
| HEIC to JPEG | `.jpg` (depends on the FFmpeg build having a HEIC decoder) |

**Tools → File Operations → Convert…** or **Convert…** on the item context menu. Select files or a folder, pick a kind and destination, preview names, then Queue. Each file is one queue job on the background host. Online-only cloud files are skipped. Existing names get a unique suffix so nothing is overwritten. Source last-write time is copied onto the output when that is possible.

---

## Folder sync

**Tools → Automation → Folder sync…** — **one-way** only.

| Mode | Behavior |
| --- | --- |
| Copy / Update | Add and overwrite from source. Never deletes. Destination-newer files are skipped with a warning. |
| Mirror | Also deletes destination items that are not in the source. Deletes stay in the preview until you Queue. Mirror AutoRun is disabled. |

Copy / Update can AutoRun when the destination volume becomes available (USB, share). Drive letters may change; Workbench stores volume identity. Excludes are one glob per line.

Files copied by sync are tagged as synchronized duplicates.

---

## Operation profiles

**Tools → Automation → Operation profiles…** — named recipes that **plan** work, then enqueue it. Steps never touch the filesystem themselves.

Toggles (not a free-form graph): Copy, Rename, Compress, Convert, require a clean Git working tree. Excludes are globs, one per line.

Built-in recipes (seeded when the list is empty):

1. **Archive folder** — require clean Git, compress 7z, exclude `.git` / `bin` / `obj` / `.vs`
2. **Copy to destination** — copy; AutoRun when the destination volume connects
3. **Convert videos to MP4** — FFmpeg H.264 MP4 into the destination folder

Run from the window, from **Run profile** on the context menu (always previews first), or by dropping files onto a profile. AutoRun is Copy-only (no rename, no compress, no convert) and fires on unreachable → reachable, not on a timer while already online.

Dirty or missing Git, missing 7-Zip, missing FFmpeg, or an unreachable destination stops the plan. Nothing is queued.

Not in this build: SHA-256, recycle source after success, GPU tuner, trim editor, scheduled or folder-watcher triggers.

---

## Organize folder

**Tools → File Operations → Organize folder…** or **Organize this folder…** on a directory.

Classification **suggests** moves. Nothing moves until you Preview and Queue.

| Category | Typical destination |
| --- | --- |
| Photos / Video / Audio / Documents | Windows Pictures, Videos, Music, Documents |
| Installers | Folder you choose (for example Software) |
| Archives | Folder you choose |
| Git repositories | Folder you choose (Development) |
| Unknown, system data, backups, build output | Left in place |

Build output names (`node_modules`, `bin`, `obj`, `.vs`, and similar) are never moved. Online-only cloud items are skipped. Old installers (older than one year) still propose a move and show a warning. Destinations may sit *inside* the source folder (Downloads → Downloads\Software). Destinations are remembered in preferences.

Organize uses the **indexed category** when one exists (including ZIP contents that are mostly photos, and **Classify as…** overrides). Extension heuristics fill in the rest.

Never auto-reorganizes. A light magic-byte peek for unknown extensions runs only during idle maintenance on local files — never on online-only cloud items.

---

## Classification

The index stores a category on each entry (Photos, Video, Documents, Archive, and so on) plus a short reason.

- Details shows a **Category** column (tooltip has the reason)
- Search accepts `category:photos` or the category dropdown
- Storage analysis has **By category** next to **By file type**
- Context menu **Classify as…** writes a user override that later scans do not replace

ZIP/7z files stay Archive until their contents are indexed; idle maintenance then promotes them when a category dominates.

---

## Git

Workbench detects repositories and shows a badge (branch, modified, untracked, ahead/behind, merging/rebasing). In **Details**, the **Git** column is per file: blank when the file matches HEAD, otherwise Modified, Staged, Untracked, Unmerged, or Staged · Modified. Folders with dirty children show Modified or Untracked. A nested repository folder shows a compact repo badge. **Tools → Development** (and the folder context menu) offers **View changes…**, **Commit…**, **Fetch**, **Pull (fast-forward)**, **Pull (merge)**, **Push**, **Open terminal here**, **Open in Cursor**, and **Open in Notepad++** when a folder is in a repository.

**View changes** lists staged, unstaged, untracked, and unmerged paths from `git status`. Double-click opens a unified **diff** (`git diff` / `git diff --cached`). **Open in Cursor** opens the file. Online-only cloud files are not opened or diffed (that would download them). Stage, unstage, and discard call the matching `git` commands. Discard asks first.

**Commit** asks for a message and which files to include. Unmerged paths, online-only cloud files, and folders are skipped. A merge, rebase, cherry-pick, or revert in progress blocks a normal commit — use **Continue** or **Abort**. Workbench runs `git add` then `git commit --only` for the checked paths, so other staged files stay staged.

**Merge** is conflict resolution, not a mergetool: **Use ours**, **Use theirs**, **Mark resolved**, then **Continue** (`git commit --no-edit` / `rebase --continue`). **Abort** restores the previous state. Incoming rebase/cherry-pick/revert from a terminal can be finished the same way.

**Pull (fast-forward)** is `git pull --ff-only --no-rebase`. If that cannot fast-forward, Workbench offers **Pull (merge)** (`git pull --no-rebase`) or a terminal. Fetch and push are the matching `git` commands. There is no stash, branch UI, mergetool, or credential dialog (`GIT_TERMINAL_PROMPT=0`).

Missing `git.exe` means no badge and no Git actions. Path can be set in Settings → Advanced. Git is not bundled. Profiles can require a clean working tree.

---

## Cloud overlays

When a cloud folder is added:

- Status on items (Details **Cloud** column, and next to the name in List): Online-only, Local, Pinned, Syncing, Error
- **Always keep on this device** / **Free up space** when the provider supports pin/dehydrate
- Quota in capacity/free space where the provider reports it

Workbench never starts a cloud vendor’s own two-way sync. It never hydrates a file as a side effect of browse, size, search, hash, archive, or convert.

---

## Settings

**Settings** opens a window with categories on the left. The last category you opened is remembered until you quit Workbench. Empty categories are omitted.

| Category | Options |
| --- | --- |
| General | Start Explorer.Host.exe at Windows sign-in (current-user Startup, no administrator rights) |
| Appearance | Dark / Light theme |
| Navigation | Group network under Network; group cloud under Cloud (independent); prefer Favorites when synchronizing the locations tree (off by default); show hidden files; show protected system locations |
| File Operations | Auto-clear queue when done; path to 7-Zip; path to ffmpeg.exe |
| Indexing | Include archive contents in the index; automatically index removable drives when they appear; enable idle background maintenance; idle threshold (5 / 10 / 30 minutes); only run expensive maintenance on AC power |
| Advanced | Path to git.exe |

These options change what Workbench shows and indexes. They do not change Windows Explorer settings. Layout, favorite pins, organize destinations, and open tabs are stored in `ui-preferences.txt` but are not edited here.

---

## Help

| Item | What you get |
| --- | --- |
| Documentation | This guide, shown inside Workbench |
| About | Version, data folder, log folder |

The source of this guide is `docs/Documentation.md` in the project (or `Documentation.md` next to the executable). Edit the Markdown in any editor, then reopen this window. A copy is also embedded in the app if no file is found.

Press `F1` to open Documentation.

---

## What is not in this build

Left open on purpose:

- Two-way sync and conflict resolution UI
- Undo for copy/move
- Concurrent copies across different disks
- GPU / trim / filter conversion
- Multi-PC search, sharing, encrypted vaults
- Robocopy as a second transfer engine
- Scheduled profiles and folder-watcher triggers
- Full EXIF / ffprobe classification
- Duplicate “backup copy” auto-tagging

---

## Definition of done

Explorer Workbench is never finished. A feature is useful when it improves the actual workflow of the person using it.