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 8). 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, sync, and organize work
- Overlay Git and cloud status without becoming a Git client or a sync engine

Workbench **does not**:

- Two-way sync
- Convert media (no FFmpeg in this build)
- 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. Git reports status, shows diffs, commits selected files, resolves conflicts, and runs fetch, pull, and push. Workbench orchestrates.

---

## First launch

The window opens immediately. Locations fill in a moment later — Workbench does not wait for slow network shares or a second instance locking the index.
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.

| 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 |

---

## Window layout

- **Title bar** — Explorer Workbench; minimize / maximize / close.
- **Menu** — File, View, Tools, Settings, Help. Tools is grouped: Storage, Locations, File Operations (including Archives), Automation, Development, Recycle Bin.
- **Toolbar** — path, navigation, view mode, search, storage, queue summary.
- **Tree** — This PC, Network, Cloud (grouping is optional in Settings).
- **Folder pane** — details, list, or preview. Split pane is optional.
- **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 |
| Refresh | View → Refresh, or `F5` |

---

## Locations

### 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.

### 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. Size, date, and type from the directory listing show with the row. Cloud status, indexed folder totals, and Git badges 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.

**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. 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+C` / `Ctrl+X` / `Ctrl+V` | Copy / Cut / Paste |
| `Delete` | Recycle (queued) |
| `Ctrl+T` / `Ctrl+W` | New tab / Close tab |

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

Hidden files follow Settings. 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 → include archive contents)

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.

---

## Duplicates

**Tools → Storage → Duplicates**. Groups are hashed in the background (size → partial hash → full hash only when needed). Workbench distinguishes:

| 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.

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. Collisions and illegal Windows names are caught before enqueue. Completed batches can be undone (**Tools → File Operations → Undo last rename batch**).

Metadata placeholders such as `{CreatedDate}` or `{Width}` are not implemented yet. `{Counter}` and `{Extension}` work.

---

## Archives

Needs **7-Zip** on the machine (Settings 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.

---

## 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, 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

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) and fires on unreachable → reachable, not on a timer while already online.

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

Not in this build: SHA-256, recycle source after success, FFmpeg, 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.

Never auto-reorganizes. No MIME/content sniffing (that would hydrate cloud files).

---

## Git

Workbench detects repositories and shows a badge (branch, modified, untracked, ahead/behind, merging/rebasing). **Tools → Development** (and the folder context menu) offers **View changes…**, **Commit…**, **Fetch**, **Pull (fast-forward)**, **Pull (merge)**, **Push**, **Open terminal here**, and **Open in Cursor** 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. Git is not bundled. Profiles can require a clean working tree.

---

## Cloud overlays

When a cloud folder is added:

- Status text on items (available / online-only / syncing)
- **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, or archive.

---

## Settings

**Settings** in the menu:

- Dark / Light theme
- Group network under Network; group cloud under Cloud (independent)
- Show hidden files
- Show protected system locations
- Auto-clear queue when done
- Include archive contents in the index
- Path to 7-Zip
- Path to git.exe

These options change what Workbench shows and indexes. They do not change Windows Explorer settings.

---

## 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
- FFmpeg / media conversion
- Multi-PC search, sharing, encrypted vaults
- Robocopy as a second transfer engine
- Scheduled profiles and folder-watcher triggers
- MIME/EXIF classification
- Duplicate “backup copy” auto-tagging
- Rename placeholders from EXIF or dates

---

## Definition of done

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