# MyFileExplorer — AI support knowledge base
Generated from `scripts/ai-support-manifest.json`. Do not edit this file by hand.
Rebuild with `npm run docs:support`.
| | |
| --- | --- |
| **Application** | MyFileExplorer |
| **Package version** | 0.22.0 |
| **Repository** | https://github.com/dobrado76/MyFileExplorer |
| **Issues** | https://github.com/dobrado76/MyFileExplorer/issues |
| **Releases** | https://github.com/dobrado76/MyFileExplorer/releases/latest |
| **License** | GPL-3.0 — https://github.com/dobrado76/MyFileExplorer/blob/main/LICENSE |
Links in this file jump to another section of this file. A link that leaves the project is a full https URL.
A **Version:** 0.21.0 line inside a section is when that page was last stamped, not the running build. The running build is Settings → About. This package is 0.22.0. The newest changelog section is 0.22.0 (2026-10-23). There is no 0.21.1 or 0.21.2 section. Do not invent one.
If the overview (README, advantages, business note, product spec) disagrees with the reference, FAQ, configuration, troubleshooting, or that topic's feature guide, follow the feature guide and the reference.
## Contents
1. [Instructions for AI assistants](#src-docs-support-llm-instructions-md)
2. [Symptom index](#src-docs-support-symptom-index-md)
3. Source documents, in order:
- [docs/product.md](#src-docs-product-md)
- [docs/getting-started.md](#src-docs-getting-started-md)
- [docs/configuration.md](#src-docs-configuration-md)
- [docs/reference.md](#src-docs-reference-md)
- [docs/troubleshooting.md](#src-docs-troubleshooting-md)
- [docs/FAQ.md](#src-docs-faq-md)
- [docs/roadmap.md](#src-docs-roadmap-md)
- [docs/PREVIEW.md](#src-docs-preview-md)
- [docs/PREVIEW_EXTENSIONS.md](#src-docs-preview-extensions-md)
- [docs/SEARCH.md](#src-docs-search-md)
- [docs/SLIDESHOW.md](#src-docs-slideshow-md)
- [docs/ADS.md](#src-docs-ads-md)
- [docs/FOLDER_STATISTICS.md](#src-docs-folder-statistics-md)
- [docs/PAIRED_FOLDERS.md](#src-docs-paired-folders-md)
- [docs/MEDIA_METADATA.md](#src-docs-media-metadata-md)
- [docs/USER_METADATA.md](#src-docs-user-metadata-md)
- [docs/SCRIPTS.md](#src-docs-scripts-md)
- [docs/AI_CHAT.md](#src-docs-ai-chat-md)
- [docs/GIT.md](#src-docs-git-md)
- [docs/VIRTUAL_FOLDERS.md](#src-docs-virtual-folders-md)
- [docs/VIRTUAL_FOLDER_PROJECTION.md](#src-docs-virtual-folder-projection-md)
- [docs/NETWORKS.md](#src-docs-networks-md)
- [docs/REMOTE_FTP.md](#src-docs-remote-ftp-md)
- [docs/POWER_RENAME.md](#src-docs-power-rename-md)
- [docs/UNDELETE.md](#src-docs-undelete-md)
- [docs/WINDOWS_SHELL_REDIRECT.md](#src-docs-windows-shell-redirect-md)
- [docs/LINUX.md](#src-docs-linux-md)
- [docs/PROJECT_FORMAT.md](#src-docs-project-format-md)
- [docs/SECURITY.md](#src-docs-security-md)
- [docs/INTEGRATION.md](#src-docs-integration-md)
- [README.md](#src-readme-md)
- [docs/README.md](#src-docs-readme-md)
- [docs/PRODUCT_SPEC.md](#src-docs-product-spec-md)
- [docs/ADVANTAGES.md](#src-docs-advantages-md)
- [docs/BUSINESS_UVP.md](#src-docs-business-uvp-md)
---
:` can read them. Guide: [USER_METADATA.md](#src-docs-user-metadata-md).
` / `` via `mfe-media://` (`mediaUrl`) — protocol must answer **byte-range** requests (`206` + `Content-Range`); a plain full-body `200` is not enough for Chromium media
- Video: `.mp4`, `.m4v`, `.webm`, `.mkv`, `.avi`, `.divx`, `.flv`, `.rmvb`, `.rm`, `.mov`, `.wmv`, `.mpg`, `.mpeg` — player/strip plus parsed tags/format when present (`group: 'video'`; empty fields omitted). Embedded artwork is not used as the video still (frame posters stay separate).
- Audio: `.mp3`, `.wav`, `.flac`, `.ogg`, `.m4a`, `.aac`, `.wma`, `.opus` — player plus parsed tags/format (`group: 'audio'`) and embedded cover when present (`posterUrl`, cached under `userData/audio-covers/`)
- **Async tags:** `preview:get` returns `mediaUrl` without waiting on `music-metadata`. The renderer starts `preview:getMediaMeta` in parallel and paints as soon as `preview:get` returns (brief wait only if tags are already back). Video tag parse uses **header duration only** (no whole-file scan). A slow or failed parse must not leave the preview spinner up; fields merge in when they arrive.
- Playback depends on Chromium’s codecs. **H.264 + AAC** in MP4/M4V/MOV usually works. **HEVC (H.265)** uses the **OS decoder** (`PlatformHEVCDecoderSupport`) — Windows: HEVC Video Extensions. **AV1 / VP9** when Chromium supports them. **AC-3 / DTS** → Open with default app (or Rich player when enabled).
- **No ffmpeg remux for Preview playback** (locks the file for rename/move/delete). Default: `.mkv` / `.ts` / `.m2ts` / `.wmv` / `.avi` / … → **Open with default app** (optional still/strip). Settings → Preview: **Autoplay media in preview** (`previewVideoAutoplay`, default off); **Rich player (mpv)** (`previewRichPlayerMpv`, default **off**, D33) — when on, places a bundled/PATH `mpv` as an **owned borderless overlay** for containers **without** a Chromium `mediaUrl` (`npm run tools:fetch-mpv`, pinned in `scripts/mpv-pin.json`); Open with default app stays as fallback. **Click on the video picture** play/pauses like Chromium `` (OSC stays clickable; window caption / chrome do not toggle). **Double-click / Open** stops Rich Player and holds in-pane AV for that path so mpv cannot pull MFE above VLC/etc.; AV resumes when the selection changes. MP4/M4V/WebM/MOV never hand off to mpv.
- **`.avi` / `.divx` / `.rmvb` / `.rm`**: with Rich player **off**, no Chromium player — animate `!VIDTHUMB_CACHE` strip frames when present, plus **Open with default app** (D33). With Rich player **on**, try mpv in-pane. Tag metadata still listed when parseable. `.divx` is an AVI/RIFF file with a DivX codec. `.rmvb` / `.rm` are RealMedia.
- On decode error for otherwise playable types (Chromium path): short message + open-with-default-app button (and poster if available) — **no** automatic mpv fallthrough
/…` so relative links resolve (D7 — no `file://`)
- Renderer uses a **sandboxed iframe** (no scripts); TOC click → `preview:chmTopic`
- TOC from `.hhc` sitemap (cap ~4000 nodes); folders start **collapsed**; `../` Locals omitted; default topic from `.hhp` or first HTML topic
- Large files (>256 MiB) skipped with a warning — use **Open** for the system help viewer
- Best-effort: odd encodings, broken links, or ActiveX-era pages may degrade; scripts do not run
---
` via byte-range `mfe-media://`. Optional autoplay: Settings → Preview → **Autoplay media in preview**.
Also shows **parsed metadata** (ID3 / Vorbis / etc. via `music-metadata`): duration, bitrate, sample rate, channels, codec/container, title/artist/album, track/disc, genre, year, composers & credits, BPM/key, copyright, ISRC, MusicBrainz IDs, comments/lyrics (truncated), and **embedded cover art** when present. Empty fields omitted.
| Ext | Notes |
| --- | ----- |
| `mp3` | MPEG audio + ID3 tags / cover. |
| `wav` | PCM / common WAV (+ tags when present). |
| `flac` | Lossless + Vorbis comments / picture blocks. |
| `ogg` | Ogg container (Vorbis/Opus depending on Chromium). |
| `m4a` | AAC in MP4 audio (+ iTunes/MP4 atoms). |
| `aac` | Raw / ADTS AAC when Chromium accepts it. |
| `wma` | Best-effort; may need Open with default app. |
| `opus` | Opus audio. |
---
` via byte-range `mfe-media://` when Chromium can play the container/codecs. Optional autoplay (same setting as audio). Opt-in **Rich player (mpv)** (D33, default off) plays non-Chromium containers in-pane; otherwise **Open with default app**. No ffmpeg remux for Preview.
Also shows **parsed metadata** underneath when present (same `music-metadata` path as audio): duration, bitrate, dimensions/fps when known, codecs/container, title/artist/album and other tags. Empty fields omitted.
| Ext | Behavior |
| --- | -------- |
| `mp4` / `m4v` | Direct play for H.264/AAC; **HEVC** when the OS decoder is available (Windows: HEVC Video Extensions); AV1 when Chromium supports it. Rich player does **not** take over on decode failure. |
| `webm` | Direct play for VP8/VP9/AV1 + Opus/Vorbis when Chromium supports them. Rich player does **not** take over on decode failure. |
| `mov` | Direct play when codecs allow (same H.264 / HEVC / AAC rules as MP4). Rich player does **not** take over on decode failure. |
| `mkv` / `ts` / `m2ts` / `wmv` / `asf` / `mpg` / `mpeg` / `flv` | Default: **Open with default app** (optional still). With **Rich player (mpv)** on: in-pane mpv. No ffmpeg remux for Preview. |
| `avi` | Default: **strip-only** + **Open with default app** (D33). Rich player on: in-pane mpv. Metadata still listed when parseable. |
| `divx` | Same as AVI (RIFF/AVI container, DivX codec). |
| `rmvb` / `rm` | RealMedia. Default: strip-only + Open with default app. Rich player on: try mpv. |
Icon-view video strips (`!VIDTHUMB_CACHE`) are separate from the preview pane; see [PREVIEW.md](#src-docs-preview-md).
---
c` |
| Modifiers | `case:`, `path:` / `nopath:`, `file:` / `folder:`, `regex:`, `ww:` |
| Functions | `size:>1mb`, `size:large`, `dm:today`, `dc:thisweek`, `da:today` / `dateaccessed:`, `ext:jpg;png`, `parent:`, `infolder:`, `startwith:`, `endwith:`, `len:`, `empty:`, `count:` — `dc:` = created (birthtime), `dm:` = modified, `da:` = last accessed; missing times fail closed (no mtime stand-in) |
| Macros | `pic:`, `video:`, `audio:`, `doc:`, `exe:`, `zip:` |
| Path tokens | `d:`, `d:\folder\` |
| Advanced | `attrib:h`, `dupe:`, `sizedupe:`, `child:`, `childcount:`, `depth:` |
| Content (slow) | `content:`, `utf8content:` — unindexed scan of name/path hits only; hard size/time caps; banner (D15) |
| Notes (D61) | `note:`, `hasnote:`, `notestatus:`, `todo:` / `todo:buy` — read-only ADS `mfe_note` (does not change host times). Current-folder walk is complete; indexed uses notes saved in this app. `!hasnote:` excludes items that have a note. |
| ADS streams (D38) | `stream:Name`, `stream:Name=value` (text substring), `hasstream:` / `hasads:`; aliases `ads:`. `!stream:Name` / `!hasstream:`. Read-only; value match skips streams > 64 KiB. |
| User metadata (D70) | Opt-in (`settings.userMetadata.enabled`). `meta.:`, `hasmeta:`, … when enabled and a set applies. Spec: [USER_METADATA.md](#src-docs-user-metadata-md). |
Toolbar toggles (persisted): **Match path**, **Match case**, **Whole word**, **Regex**. Type chips map to macros.
Legacy plain substring + `*`/`?` globs still work when no operators are used. A **basic name query** (no recognized operators) matches the **name** only — it never returns the whole corpus. Unknown `word:value` tokens are treated as literal name text, not as operators.
---
`. Settings `adsFieldColumns` only stores streams the user added via **...**.
- Cell: same text preview as the ADS Manager Value column (single-line text; `[...]` if multiline, binary, or larger than 64 KiB; blank if the stream is missing). Reads `path:name:$DATA` only — does not list every stream unless the names column is also visible.
Do **not** enumerate ADS inside `fs:list` — that would slow every browse.
**Search:** `stream:Name`, `stream:Name=value` (text substring), `hasstream:` / `hasads:` (aliases `ads:`). Exclude with `!stream:Name` / `!hasstream:`. Power Search → **Metadata** → **ADS stream**. Read-only; value match skips streams larger than 64 KiB. See [SEARCH.md](#src-docs-search-md).
### Context menu
**Alternate streams…** on a single file or the current folder opens the ADS Manager for that path.
` columns) |
| `showFolderStatistics` | When true (default), Details shows calculated folder Size / Files / Folders columns from ADS |
| `folderStatsTreemapMaxLeaves` | Max file tiles in the space map (100–50000, default **50000**). Changing does not rewrite ADS until the next Calculate |
| `folderStatsSkipPaths` | Paths omitted after Skip folder / Skip all during Calculate (manage in Settings → Behavior) |
Column visibility / order live with the rest of the Details layout in settings (see [PROJECT_FORMAT.md](#src-docs-project-format-md)).
selectedRowIds: Set
visibleStatuses: Set
stale: boolean
}
```
Do not persist complete result rows in `session.json`. A comparison is an ephemeral snapshot. Persisting only the last-used options is acceptable through `settingsSchema`.
---
· items`
Right strip:
`Compared root: · items`
Both strips share:
- Comparison method summary.
- `Results may be stale` warning when applicable.
- Recompare action.
- Exit action may remain centre-rail only to reduce duplication.
pairCompare:result({ sessionId }): Promise
pairCompare:progress event
pairCompare:buildPlan(request): Promise
pairCompare:revalidatePlan({ planId }): Promise
pairCompare:executePlan({ planId, approvedDecisions }): Promise
pairCompare:dispose({ sessionId }): Promise
```
For large comparisons, do not send an unbounded result as thousands of individual IPC calls. Return batches or one compact result payload after progress events. Consider pagination/windowing only if result serialization becomes measurably problematic.
All inputs and outputs require Zod schemas consistent with the existing architecture.
/` instead of next to the `.mp4`. **Consolidate subtitles** walks from the selection (show, season, or library folder):
1. In each folder that has a sibling `Subs` / `Subtitles` / `Subtitle` / `Sub` (any case), match each video to `Subs//` or a flat `Subs/*.srt`.
2. Copy the first English-tagged subtitle (`.srt` before `.ass` / `.vtt` / …). If nothing is tagged English, use the only subtitle (or the only `.srt`) in that folder.
3. Write `{video stem}.srt` (or the picked extension) beside the video. Existing dest files are left alone.
4. After a folder-level run, send the Subs tree to the Recycle Bin (not a permanent delete). Selecting only some videos copies those matches and leaves Subs in place.
Confirm before it runs. Remotes are skipped. Walk cap is 20 000 folders; Subs trees are not walked as further roots.
---
`, catalog). Never renamed or reused. Not written as the `mfe_meta` value key. |
| **`key`** | `field_rating` | Stable name stored in `mfe_meta` and used by Power Search (`meta.field_rating:…`). |
| **`name`** | `Review state` | Display label (Settings, dialog, column headers). Freely renameable. |
Each **choice / multi-choice / icon-tags option** likewise has an opaque **`id`**, a query **`key`**, and a display **`label`**. `mfe_meta` stores option **keys** (for example `awaiting_review`), not labels. Renaming a label does not disconnect values. Changing a field or option **key** leaves streams already written under the previous key (Hygiene can reconnect them). A confirmation warns that raw typed queries may need updates. Structured Power Search stores opaque ids and regenerates the current keys when emitting queries.
Older streams that still use `mf_…` / `mo_…` tokens are read as before. The next metadata save rewrites that item with query keys.
**Cross-set keys:** the same field `key` may appear in multiple sets **only when field types are identical**. Raw `meta.:` queries OR across every compatible field sharing that key. Choice option keys map to the union of matching option ids. Types that disagree cannot be saved.
**Catalog safety:** field / set / binding arrays soft-parse — one invalid definition does not wipe the rest of the catalog.
---
:`).
Choice, multi-choice, and icon-tag **options** can be reordered (↑/↓) in the Metadata manager; that order is display order.
`. Empty cells stay **blank** (no dash placeholders). **All field types** are editable in-column:
- boolean — click cycle (clear when not required)
- choice — option menu
- multi-choice — checkbox dropdown (toggle commits immediately)
- date / text / number — inline edit
- icon tags — glyph toggles
- link — Open / Reveal when filled; click-to-edit when empty
- **Bulk Metadata…** (multi-select): per field **Leave** (default) / **Set** / **Clear**; Clear omitted when `required`. “varies” when values differ. Save writes only Set/Clear keys (`Clear` → null). **Clear all** still wipes the whole stream. Required: **Set** needs a non-empty value; **Leave** allowed for legacy empties.
- **In-folder facets** (toolbar): when a set resolves for the cwd, filter chips for boolean / choice / icon tags / multi-choice (session-only; cleared when leaving the folder). Distinct from Power Search and the name eye filter.
- **Icon badge**: at most one field per set with `showOnIcon` overlays a short label (boolean/choice) or first on icon-tag glyph on the row icon (does not replace D62 custom item icons).
- **Item editors** (preview / Metadata…): files use the **parent** folder’s binding. Folders use a binding on **themselves** first; if none, they inherit the **parent** folder’s binding. A non-recursive assignment means **items directly contained in this folder** (list rows), not “metadata on the directory object only.” Opening that child does not apply the set to *its* contents unless the child has its own assignment (or a recursive ancestor). UI label: **Items in this folder only**.
- **Cwd / columns / Assign set**: still resolve the folder path itself (exact, else longest recursive ancestor).
- Single-item Metadata… seeds `defaultValue` when the item has no value for that field (user still must Save); Save rejects empty required fields.
---
```
Payload: `{ setId, setName, fields, items: [{ path, values }] }`. Deleted when the process exits (same lifecycle as `--input-list`). See [SCRIPTS.md](#src-docs-scripts-md).
---
` | Folder mode | Absolute folder to operate on |
| `--recursive` | Folder mode, optional | Walk subfolders (you still decide what that means) |
| `--input-list ` | Selection mode | UTF-8 text file, one absolute path per line (empty lines ignored) |
| `--dry-run` | Optional | Print what would change; exit 0; **do not write or delete** |
| `-- [value]` | When you defined parameters | See [Parameters](#src-docs-scripts-md--parameters) |
**Environment (selection + user metadata):** when Settings → Metadata is enabled and every selected path resolves to the **same** metadata set, the runner also writes a temp JSON and sets `MFE_META_MANIFEST` to that path. Shape:
```json
{
"setId": "ms_…",
"setName": "Project",
"fields": [ /* catalog fields for that set */ ],
"items": [{ "path": "D:\\…\\file.txt", "values": { "mf_…": "…" } }]
}
```
The file is deleted when the process exits (same lifecycle as `--input-list`). Scripts that do not need metadata can ignore the env var. `values` here use catalog field ids. The on-disk `mfe_meta` stream uses each field’s query key (`field_rating`), which is what other programs should search for.
**Folder:**
```text
script --root "D:\Photos\2026" [--recursive] [--dry-run] [--param …]
```
**Selection:**
```text
script --input-list "C:\Users\…\AppData\Local\Temp\mfe-….txt" [--dry-run] [--param …]
```
**Global:**
```text
script [--dry-run] [--param …]
```
Generate / Modify with AI uses the same target. If Target is **Global**, the model is told not to emit `--root` or `--input-list`.
Treat unknown flags as errors. Write progress to **stdout**; errors to **stderr**. Do not open a GUI prompt — the Run window is the console.
` (or `pwsh`) |
| Python | `python ` or `py -3 ` — **Python 3.x only** |
| cmd | `cmd.exe /d /s /c ` |
| bash | `bash ` |
Interpreters are detected on PATH. Optional absolute overrides: **Settings → Scripting and AI → Script runner**. A missing interpreter is an error on Run, not a silent fallback to `cmd /c`.
**Python 2.x is not supported.** Generated and hand-written scripts are Python 3 (`print(…, file=sys.stderr)`, `argparse`, etc.). If Run fails with `SyntaxError` on `file=`, the machine’s `python` on PATH is 2.7 — install Python 3, or set the Script runner override to `py` / a Python 3 `python.exe`. The app does not ship a Python runtime.
PowerShell’s `param($Root)` does **not** bind `--root`. Parse `$args` (examples below). Python should use `argparse`.
---
.`. Later runs are local. If the display name is already used, Save appends ` (2)`, ` (3)`, … (same idea as Explorer). The library list is never sent to AI.
.`, not the name.
3. Save. Later runs are **local** — generating again is optional. A name that already exists becomes `Name (2)` (the model is not told your library).
Also:
- Generate / Modify / Ask AI to Fix show a dialog overlay (indeterminate bar + elapsed) while waiting.
- Local vs cloud indicator. Cloud first-use copy: task/script may go to the provider; **files do not**.
- **Modify with AI…** opens this dialog with the current name, description, language, source, and folder/selection flags. **Modify** sends current source plus **Modify instruction**, or **Task** if that field is empty. **Regenerate** always uses Task (new draft).
- **Ask AI to Fix** (after a non-zero exit) asks first and lists the payload (source, exit code, stderr, OS/runtime). Optional path redaction. Never auto-sent.
Prompt ideas that work well (because the model never sees your disk):
- “Folder script: list files larger than --min-mb megabytes. Support --recursive and --dry-run (dry-run only prints).”
- “Selection script: copy selected files to --dest (folder param). Skip existing names unless --overwrite. Dry-run prints planned copies.”
- “PowerShell: report folders that contain no images (jpg/png/webp). Recursive. Read-only.”
Vague prompts (“make my photos better”) produce vague scripts. Name the CLI flags you want.
No provider → **Open AI Settings**, not a hard error on the runner. Hand-written scripts always work.
---
.ps1 | .py | .cmd | .sh
backups\.prev
```
---
` / `` start automatically on select (default `false`). Settings → Preview.
- `hideNameExtensions`: extensions (no leading dot) whose “.ext” is omitted from file-view/search **labels** only (default `["lnk"]`). Does not hide files from the listing; rename/tooltips still use the real name.
- `showFolderStatistics`: when true (default), Details shows Size / Files / Folders from Calculate Statistics ADS.
- `folderStatsTreemapMaxLeaves`: max file tiles in the folder space map (100–50000, default **50000**). Written into `FolderStatsPreview.maxLeaves` on Calculate (D66).
- `folderStatsSkipPaths`: absolute paths skipped after Calculate Skip folder / Skip all.
- `searchExcludeDirNames`: search/index exclude patterns (view-filter language — folder names, file names, `.tmp` / `*.log`, wildcards, or an absolute path)
- `searchIndexedOnly`: toolbar **indexed** search toggle (default `false` = current folder walk; `true` = indexed roots only)
- `layoutsAutoSave`: when switching named layouts, overwrite the layout the live workspace was last applied from or saved as (default **true**; D25).
- `layouts`: named workspace snapshots (D25) — main window `{ id, name, updatedAt, activeTabIndex, splitters, viewLayout, paneTabIndexes, paneSplitCols, paneSplitRows, pairCompareVisibleStatuses?, mainWindow?, tabs }` plus `windows[]` for each secondary explorer window `{ frame: { x, y, width, height, maximized }, activeTabIndex, tabs }`. `tabs` entries are `{ path, title, icon, viewMode, sort, rootPath, treeExpanded, dropShortcut?, dropTransfer? }`. Cap 50. Applying replaces the live workspace and closes floats that are not in the snapshot (not added to Reopen closed window). Older layouts with no `windows` / `mainWindow` restore the main window’s tabs only and do not move that window. Optional `pairCompareVisibleStatuses` restores the paired-folders compare filter (D69). `paneTabIndexes` are indices into the main window’s `tabs` (or null). `icon` is `{ name, color }`, `{ kind: 'custom', id, showLabel, sizePx }` (D54; PNG stays in `tab-icons/`), or `null` (D32). `dropShortcut` is a normalized chord string (e.g. `Ctrl+1`) or `null`; `dropTransfer` is `auto` \| `move` \| `copy` (default `auto`) — keyboard transfer into that tab’s folder (D32). `mainWindow` is the same frame shape as `windows[].frame`.
- `templates`: new-file templates (D57) — `{ id, name, suggestedStem, inputName, sourceFile }` (`name` = menu + default stem; `inputName` = original picked file; stored copy is `Templates/{sourceFile}`). Cap 40. Order in the array is the menu order.
- `quickLaunch`: toolbar apps (D63) — `{ id, name, path, args, show: 'icon' \| 'label' \| 'both', iconSizePx (12–48, default 24), iconKind: 'shell' \| 'custom' \| 'lucide', iconId?, lucideName?, lucideColor }`. Cap 24. Custom PNGs are `quick-launch/{iconId}.png` (not in Settings export).
- `folderViews`: per-folder view overrides (D22); orthogonal to layouts
- `indexedRoots`: absolute paths marked for indexing (also stored/mirrored in SQLite for query joins)
- `defaultNewTabPath`: empty → This PC / known folder of choice at implement time
- `mediaMetadata`: opt-in movie/TV metadata (D50). `{ enabled` (default false), `coverHeightPx` (56–240, default 120), `showEpisodeIconLabels` (default true — icon tiles use `SxxExx` + episode title; false = filename), `mixFilesAndFolders` (default false — Folders first; on = media-container **icon/thumbnail** listings ignore Folders first; List/Details follow Behavior → Folders first), `tmdbApiKey`, `omdbApiKey`, `internetSource` (`tmdb` \| `omdb`), `plexUrl`, `plexToken`, `plexDataDir`, `libraryFilters` (array of `{ path, watched, genre }` — last Watched/Genre toolbar choice per media-library folder; max 200) }. Streams on the media file/folder: `media_metadata` (JSON, including optional `watched`; `source` may be `plex` \| `tmdb` \| `omdb` \| `manual`), `media_metadata_thumbnail` (cover bytes, not on episode files). Folder flag: `media_metadata_container` on the library parent and the title folder — not under `userData`. Guide: [MEDIA_METADATA.md](#src-docs-media-metadata-md).
- **Item notes / icons (D61 / D62)** are **not** settings — they live on the file or folder as NTFS ADS `mfe_note` (JSON), `mfe_icon` (JSON), and `mfe_icon_img` (PNG). Host timestamps are restored after every write/delete. Search reads `mfe_note` only. A small `item_notes` catalog in `search-index.sqlite` (userData) speeds indexed `todo:` / `hasnote:` after a note is saved. Not under browsed folders.
- `userMetadata`: D70 — `{ enabled` (default **false**), `sets[]`, `bindings[]` }. Values on the file/folder as NTFS ADS `mfe_meta`. Guide: [USER_METADATA.md](#src-docs-user-metadata-md).
- `scripts` / `ai`: D51 — `scripts.enabled` (default **false**, hides Scripts chrome), runner overrides, first-run ack + OpenAI-compatible provider metadata (no API keys). Geometry: `scriptManagerBounds`, `scriptGenerateBounds`, `scriptRunnerBounds`, `scriptQueueBounds` (stripped on export). In-session sequential run queue + minimize-to-status-bar. Guide: [SCRIPTS.md](#src-docs-scripts-md).
- `git`: D64 — `{ enabled` (default **false**), `executablePath`, overlay/toolbar/column toggles, `showIgnored`, `refreshDebounceMs`, large-repo threshold, `diffTool` / `externalClient` templates, … }. Temps under `userData/git-scratch`. Guide: [GIT.md](#src-docs-git-md).
---
` / `-r` | Folder → new/focus tab on that folder. File → tab on parent folder **and select the file**. `.mfevirtual` → reveal the document in its parent. |
| `--open ` / `-o` | Open path as a folder tab (files open their parent, no selection). `.mfevirtual` → navigate into the Virtual Folder collection. |
| Bare absolute path | Same as `--reveal`, except `.mfevirtual` opens the collection (same as `--open`). |
If MyFileExplorer is already running, the second process exits immediately and the first window focuses and handles the path.
**Installed path (typical):**
```text
%LOCALAPPDATA%\Programs\MyFileExplorer\MyFileExplorer.exe
```
**PowerShell example from another app:**
```powershell
$exe = Join-Path $env:LOCALAPPDATA "Programs\MyFileExplorer\MyFileExplorer.exe"
Start-Process -FilePath $exe -ArgumentList @('--reveal', $fullPath)
```
**Node / Electron example:**
```js
import { spawn } from 'node:child_process'
import { join } from 'node:path'
const exe = join(process.env.LOCALAPPDATA, 'Programs', 'MyFileExplorer', 'MyFileExplorer.exe')
spawn(exe, ['--reveal', targetPath], { detached: true, stdio: 'ignore' }).unref()
```
:` — **[docs/USER_METADATA.md](#src-docs-user-metadata-md)**
**Move files without the drama**
- Status-bar progress + **Cancel** on long copy/move/trash/delete
- **Continue-then-review** — finish every auto-ok item, then one grouped review (Skip / Keep both / Replace / Keep most recent / Retry)
- Side-by-side conflict compare (thumbs, size, dates) when a name already exists
- In-app Recycle Bin (restore / empty) — never forced into system Explorer
- Undo / redo for the ops you expect (Ctrl+Z / Ctrl+Y)
- Drag out to other apps; right-drag for Copy / Move / **Create shortcuts here**
- **Open Command Line here** (cmd or PowerShell from Settings; Shift = Administrator)
- **Paste a screenshot / URL / text** as a new file; **From Template** for stubs you reuse
- **Create link…** — symlink, hard link, or junction
- **Grouped Quick access** — color and collapse pin groups in the tree
**Run anything on the folder in front of you**
- **Universal script runner** (D51, **off by default**) — Settings → Scripting and AI → Enable scripting. Then PowerShell, **Python 3** (not 2.x), cmd, or bash against the current folder, selection, or **global** (its own toolbar button when one exists, no folder needed). Live output, Stop, dry-run. Saved scripts live under app data and show up on the context menu like built-in verbs.
- Optional **AI** (same settings page) writes or repairs source from a task description — **files and paths are never sent**. Later runs are local. Guide: **[docs/SCRIPTS.md](#src-docs-scripts-md)**
- **Virtual Folders** — portable `.mfevirtual` collections of path references (not copies); optional **OS projection** on Windows so Explorer sees the same tree — **[docs/VIRTUAL_FOLDERS.md](#src-docs-virtual-folders-md)** · **[docs/VIRTUAL_FOLDER_PROJECTION.md](#src-docs-virtual-folder-projection-md)**
- **Git-aware browsing** (D64, **off by default**) — Settings → Git → Enable for status overlays, toolbar Commit/Pull/Push, and context Git actions. Uses your installed `git`; never stores credentials. Guide: **[docs/GIT.md](#src-docs-git-md)**
**Find things on purpose**
- **Everything-inspired search** — opt-in folder roots + optional drive index (NTFS USN), as-you-type, operators (`size:`, `ext:`, `pic:`, …), **Power Search** visual builder, content scan, filters/bookmarks
- Search is a **tab location** (Back/Forward); each tab keeps its own results; delete/move drops stale hits
- Search hits use the **same** file view as a normal folder
- Built to stay smooth in folders with tens of thousands of files
**Comfort**
- Dark / light / custom theme, font size
- **Curated context menu** — hide/reorder built-ins, Discover static shell verbs, custom file/folder commands (all in settings export)
- Per-folder view overrides, view filters, Details columns for media & generation fields
- Optional **slideshow / categorizer** for media libraries (manual crop). **Camera looks** add grain, color, and blur on the show only — off until you turn them on, and they do not change the file
- NTFS **Alternate Data Streams** manager + optional Details column; **Calculate Statistics** for folder counts **and** a WinDirStat-style space map in preview (D66)
- Drive Properties **USN…** — view / enable / resize the NTFS change journal (delete is a full-volume scan; do not use it casually)
- **Undelete** — opt-in tab-bar icon (Settings → Appearance, off by default) for classic NTFS MFT recover after permanent delete (not Recycle Bin Restore)
- Optional “disable hardware acceleration” when you need the GPU for training
---
:` stay hidden until enabled (D70). Guide: [USER_METADATA.md](#src-docs-user-metadata-md) |
| Git | **Enable Git integration** (off by default). Executable / Test. Overlays, folder indicators, toolbar, status column, ahead/behind, ignored, refresh debounce, large-repo threshold, external diff tool. Guide: [GIT.md](#src-docs-git-md) (D64) |
| Scripting and AI | **Enable scripting** (off by default — hides toolbar Scripts and context Scripts). Interpreter path overrides. Nested **Enable AI** (off = no outbound AI HTTP). OpenAI-compatible providers (base URL, model, key in `safeStorage`). Test / Refresh models; model fields are dropdowns from `GET /v1/models` (cached). Privacy: never send paths/listings/contents. Guide: [SCRIPTS.md](#src-docs-scripts-md) (D51) |
| Slideshow | **Enable slideshow UI** (hides toolbar / folder Start when off; this section stays). Delay, order, loop, **Include subfolders** (default on). **Camera looks** (off until enabled — frequency, path filter, **Camera looks…** window; display-only, files unchanged). Categorizer **Mapping Manager…**. Guide: [SLIDESHOW.md](#src-docs-slideshow-md) (D37 / D76) |
| Advanced | Clear shell-icon + thumb cache; **disable hardware acceleration** (restart; frees GPU VRAM for training); optional localhost search HTTP API |
| About | App version; GitHub repository link; **Folder or URL** / **Check for update** / **What's new** (GitHub release notes) / Update; **Export…** / **Import…** (D45) — portable JSON of all prefs including **context-menu customization** (built-in hide/order, Discover catalog + enabled, Custom commands), slideshow categorizer map, remembered Network hosts + remote connection metadata (not passwords / window/dialog geometry) |
---
` actually plays. |
| **Drag-out to other apps** | Left-drag exports real paths (CF_HDROP) to Photoshop, mail, chat, etc., while in-app folder drops and right-drag menus still work. |
| **Smart clipboard paste** | When the clipboard is a screenshot, text, a URL, or HTML (not files), Paste creates a file in the current folder. **Paste Special** picks format. A URL becomes a `.url` shortcut — never downloaded. Explorer pastes nothing useful for a screenshot in a folder. |
| **New-file templates** | New / Add → **From Template** copies a stub from the app Templates folder. Pretty name = menu label and default filename. Cap 40. Stored under app data, not next to your files. |
| **Compress / Extract ZIP** | Context menu packs a file, folder, or multi-selection into a sibling `.zip`, and **Extract All…** unpacks archives into a sibling folder — progress + Cancel, zip-slip safe. |
| **ZIP contents preview** | Select a `.zip` and see an expand/collapse file tree in the preview pane (inspect before extract) — Explorer’s preview rarely shows a useful archive tree. |
| **Unity package preview** | Select a `.unitypackage` and see the packaged `Assets/…` tree (GUID folders mapped via `pathname`) without extracting. |
| **CHM help preview** | Select a `.chm` for Contents + topic HTML in the preview pane (decompile under userData; no scripts in the iframe). |
---
:`. Project-local schemas without a proprietary DB. Guide: [USER_METADATA.md](#src-docs-user-metadata-md). |
| **Hide extensions in names (display-only)** | e.g. hide `.lnk` in the list without filtering files away. |
| **“Extra large icons only”** | Content thumbs without filename clutter when a preview exists. |
| **Disable hardware acceleration** | Settings option to free GPU VRAM (e.g. while training) — Explorer has no such control. |
| **No junk written into browsed folders** | App state, templates, tab icons, thumb caches, image originals, search DB, and the **script library** live under `%APPDATA%\MyFileExplorer` only. Notes and item icons are NTFS streams on the item itself — not a sidecar in the directory. Video strips use an existing `!VIDTHUMB_CACHE` convention when you generate them. |
---