docs: user and developer docs, repo cleanup

.github/workflows/release.yml

@@ -31,6 +31,9 @@ on:
       - 'docs/**'
       - 'LICENSE'
       - '.github/ISSUE_TEMPLATE/**'
+      # Tests cannot change the installer either.
+      - 'test/**'
+      - 'e2e/**'
   pull_request:
     paths:
       - '.github/workflows/release.yml'

CLAUDE.md

@@ -1,26 +1,30 @@
 # Filesmith
 
-A desktop **file toolkit**: drop files and run operations — convert, compress, resize,
-upscale, remove background, PDF tools (extract text, PDF→images, compress) and archive
-tools (repack CBZ/CBR/CB7/CBT, extract, archive↔PDF) — across images, video, audio,
-PDFs, documents and archives, with batch queues, thumbnails, and live progress.
+A desktop **file toolkit**: drop files and run operations (convert, compress, resize, upscale,
+remove background, generate, PDF tools, archive repack/extract, archive to/from PDF) across
+images, video, audio, PDFs, documents and archives, with batch queues, thumbnails and live
+progress. The same engine runs as the `filesmith` CLI and in the in-app console.
+
+Docs: user docs in `docs/` (getting-started, operations, models, cli), developer overview in
+`docs/architecture.md`, kept mockups in `docs/mockups/README.md`. Old upgrade plans and the
+dependency audit: `C:\Users\Admin\Documents\Claude\research\filesmith\`.
 
 ## What it is
 
 Electron + TypeScript desktop app. Renderer is React + TypeScript + Vite + Tailwind v4.
 The heavy lifting is done by external CLI tools (ffmpeg, ImageMagick, mutool, CaesiumCLT,
-7-Zip, Real-ESRGAN, rembg); the app orchestrates them. Writing RAR/CBR is the one
-operation that needs a tool we cannot bundle (WinRAR's Rar.exe), so it is detected at
-runtime and the target is greyed out when absent. Windows-first, unsigned installer via
-GitHub Releases (mirrors the sibling RCMM project's distribution).
+7-Zip, Real-ESRGAN, LibreOffice, Ghostscript, rembg); the app orchestrates them. Writing
+RAR/CBR is the one operation that needs a tool we cannot bundle (WinRAR's Rar.exe), so it is
+detected at runtime and the target is greyed out when absent. Windows-first, unsigned
+installer via GitHub Releases (mirrors the sibling RCMM project's distribution).
 
 Origin: the operations are ported from RCMM's audited `rcmm-convert/compress/upscale/removebg`
 PowerShell scripts (`../RCMM/manager/src/RCMM/`), lifted into a real GUI app.
 
-## Design process — READ THIS
+## Design process (READ THIS)
 
 Navigation is VERB-first: the rail is Convert / Compress / Resize / Upscale /
-Remove BG / Generate / Tools, each owning one queue that may hold several
+Remove BG / Generate / PDF Tools, each owning one queue that may hold several
 convert groups at once. A selection never spans two convert groups, because one
 options panel can only describe one target set. See `src/shared/tabs.ts`.
 
@@ -29,6 +33,8 @@ strict monochrome. Rules and feedback trail: `docs/design/redesign-direction.md`
 
 **View sizes (2026-10-05):** `docs/mockups/view-zoom/04-explorer-style.html`; spec `docs/superpowers/specs/2026-10-05-view-sizes-design.md`.
 
+**Console (2026-10-06):** `docs/mockups/console/01-bottom-panel.html`; spec `docs/superpowers/specs/2026-10-06-console-design.md`.
+
 **The look is designed collaboratively with the owner. Make NO visual assumptions.**
 Before building or restyling any UI, present mockups (self-contained browser HTML, like the
 RCMM Show/Hide exploration), offer options, and iterate to explicit sign-off. This covers
@@ -39,73 +45,69 @@ experience. The renderer implements the signed-off terminal design (rules in
 literal. New screens still go through mockups first. Engineering/plumbing (main process, tool modules, IPC, tests, packaging) moves fast
 without design ceremony.
 
-## Scope (v1, built in phases)
-
-1. **Images core** — convert, compress, resize.
-2. **AI images** — upscale (Real-ESRGAN), remove background (rembg). Heavy tools are
-   downloaded on first use into `%APPDATA%/Filesmith/tools`.
-3. **Media + PDF** — video/audio convert & compress (ffmpeg), PDF extract-text / images /
-   compress (mutool).
+## Tools and dependencies
 
-Dependencies: bundle the core tools (ffmpeg, ImageMagick, mutool, CaesiumCLT, 7-Zip) in
-`resources/bin` so images/PDF work offline out of the box; fetch the AI tools on demand.
-
-Each phase is its own checkpoint — confirm scope before starting the next.
+Bundled (offline): ffmpeg, ImageMagick, mutool, CaesiumCLT, 7-Zip in `resources/bin`, plus
+`resources/libreoffice`, `resources/ghostscript` and `resources/realesrgan` (all gitignored,
+staged by `scripts/fetch-binaries.mjs`). Installed on demand with uv into `%APPDATA%\Filesmith`:
+rembg, PiD, spandrel. Never bundled: WinRAR.
 
 ## Project layout
 
+Short map; details in `docs/architecture.md`.
+
 ```
 src/
-  main/        Node/Electron main process — the engine
-    index.ts        app + window bootstrap
-    tools/{convert,compress,resize,upscale,removebg,pdf,archive}.ts — one per operation
-    (planned) toolResolver.ts  find bundled/PATH binaries; on-demand AI-tool download
-    (planned) jobQueue.ts      batch queue: spawn, stream progress, cancel
-    (planned) output.ts        collision-safe output naming (ported from RCMM Get-UniqueOutPath)
-    (planned) ipc.ts           renderer <-> engine wiring
-    console/        in-app console: catalog, CLI runner (fork, staged cancel), cd
-  preload/     contextBridge — the typed `window.filesmith` API
-  renderer/    React UI: shell/ (title bar, sidebar, status bar), queue/ (files table),
-               inspector/ (Options, Preview, Info), options/ (one settings file per verb),
-               views/ (Generate, Tools, Completed, Settings), ui/ (primitives), icons/, theme/ (tokens, CSS)
-               console/ (bottom panel: output model, history, completion list)
-  shared/      types.ts — Job, ToolId, FileKind, Options, progress events
-               tabs.ts  — the VERB-first navigation model (rail tabs + Tools cards)
-  cli/         the filesmith command line: parse, plan, run, report
-resources/bin/ bundled CLI binaries (gitignored; fetched by scripts, packed by electron-builder)
-resources/cli/ PATH shims + path.ps1
-resources/skill/ Claude Code skill
+  main/        Electron main process and the engine
+    index.ts, ipc.ts, jobQueue.ts, output.ts, toolResolver.ts, session.ts, env.ts, boot.ts
+    tools/       one module per operation (convert, compress, resize, upscale, removebg, pdf,
+                 archive) + registry, plan, estimate, readiness
+    console/     in-app console: catalog, validation, forked CLI runs (staged cancel), cd
+    generate/ comfy/ pid/ rembg/ registry/ net/
+                 Generate, ComfyUI + spandrel, PiD, rembg, model registry, downloads
+  preload/     contextBridge: the typed `window.filesmith` API
+  renderer/src/
+    components/  shell/ queue/ inspector/ options/ views/ console/ ui/ icons/
+    theme/       tokens and CSS
+  shared/      types, tabs.ts (VERB-first navigation), per-verb option models, console line
+  cli/         the filesmith command line: parse, plan, run, report; commands/
+resources/     cli/ (PATH shims + path.ps1), skill/ (Claude Code skill), registry/,
+               pid/ and spandrel/ (Python sidecars)
+e2e/           Playwright specs      test/  Vitest      scripts/  fetch, verify, pin tools
 ```
 
 ## Build, test, run
 
-- `npm run dev` — launch the app (electron-vite dev, HMR).
-- `npm run build` — build main/preload/renderer to `out/`.
-- `npm run typecheck` — node + web tsc project checks.
-- `npm test` — Vitest unit tests (arg-builders, format catalogs, output collision-safety).
-- `npm run lint` / `npm run format` — eslint (flat config) / prettier.
-- `npm run package` — electron-vite build + electron-builder NSIS installer to `dist/`.
-- `npm run test:e2e` — Playwright end-to-end (launches the built app via `_electron`; run
+- `npm run dev` - launch the app (electron-vite dev, HMR).
+- `npm run build` - build main/preload/renderer to `out/`.
+- `npm run typecheck` - node + web tsc project checks.
+- `npm test` - Vitest unit tests (arg-builders, format catalogs, output collision-safety).
+- `npm run lint` / `npm run format` - eslint (flat config) / prettier.
+- `npm run package` - electron-vite build + electron-builder NSIS installer to `dist/`.
+- `npm run test:e2e` - Playwright end-to-end (launches the built app via `_electron`; run
   `npm run build` first). Covers the preload/IPC/engine chain unit tests can't reach.
+  `FILESMITH_SHOTS=1` also refreshes the tracked `impl-*` shots in `docs/mockups`.
 - `npm run cli -- <args>` runs the command line from `out/main/cli.js` (build first). Reference:
   `docs/cli.md`. The engine never imports `electron`; it reads paths from `src/main/env.ts`.
 - Releases: push to main runs `.github/workflows/release.yml` (gates, then requires a NEW
   `package.json` version, builds with `fetch-binaries --pinned`, publishes `v<version>`). Bump the
   version in the PR. Tool versions + SHA-256 live in `scripts/pinned-tools.mjs`; PRs touching
-  the release machinery get a dry-run installer artifact.
+  the release machinery get a dry-run installer artifact. Pushes that only touch `**.md`,
+  `docs/**` or `LICENSE` do not release.
 
 ## Conventions
 
-- TypeScript strict. Main-process code is Node; renderer is browser — keep the boundary clean
+- TypeScript strict. Main-process code is Node; renderer is browser. Keep the boundary clean
   (all privileged work in main, exposed via the typed preload bridge; renderer never touches
   `fs`/`child_process`).
 - Tool modules own their own format catalog + argument builder and are independently testable.
-- Never overwrite a user's source or an existing output file — always resolve a collision-free
-  name (`name (converted).ext`, ` (2)`, unique dirs). This is a hard rule ported from RCMM.
+- Never overwrite a user's source or an existing output file. Always resolve a collision-free
+  name (`name.ext`, then `name (converted).ext`, `name (converted 2).ext`; folders get ` (2)`).
+  This is a hard rule ported from RCMM.
 - No secrets in the repo; unsigned build is expected.
 
 ## Working with the owner
 
-Feature/fix work is tracked as GitHub issues → branch → PR (per global rules). README-only
-changes commit directly. Anything touching the **look** goes through the mockup-driven design
-process above — always.
+Feature/fix work is tracked as GitHub issues → branch → PR (per global rules). Every change,
+README and docs included, goes through a PR. Anything touching the **look** goes through the
+mockup-driven design process above, always.

README.md

@@ -4,6 +4,25 @@
 [![Latest release](https://img.shields.io/github/v/release/Maxaubert/Filesmith?style=flat-square&color=5b5bd6&cacheSeconds=1800)](https://github.com/Maxaubert/Filesmith/releases/latest)
 [![Downloads](https://img.shields.io/github/downloads/Maxaubert/Filesmith/total?style=flat-square&color=5b5bd6&cacheSeconds=1800)](https://github.com/Maxaubert/Filesmith/releases)
 [![Windows](https://img.shields.io/badge/Windows-10%20%7C%2011-0078D4?style=flat-square)](https://github.com/Maxaubert/Filesmith/releases/latest)
-[![Built with](https://img.shields.io/badge/Electron%20·%20React%20·%20TypeScript-2b2e3a?style=flat-square)](https://github.com/Maxaubert/Filesmith)
+[![Built with](https://img.shields.io/badge/Electron%20·%20React%20·%20TypeScript-2b2e3a?style=flat-square)](docs/architecture.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-22b364?style=flat-square)](LICENSE)
 </div>
+
+Filesmith is a Windows desktop toolkit for everyday file jobs: convert, compress, resize, upscale,
+remove backgrounds, generate images, and work with PDFs and archives. Drop in a batch of files, pick
+the options and run it. Outputs go next to the sources by default and never overwrite anything. The same
+engine is available as the `filesmith` command line, from a built-in console or any terminal.
+
+![Filesmith converting a batch of images, with one job running](docs/screenshots/convert.png)
+
+## Docs
+
+- [Getting started](docs/getting-started.md): install, the main screen, your first job
+- [Operations](docs/operations.md): what each operation does and its options
+- [Models](docs/models.md): Upscale and Generate models, ComfyUI
+- [Command line](docs/cli.md): the `filesmith` CLI and the in-app console
+- [Architecture](docs/architecture.md): for developers, how the app is built, tested and shipped
+
+## License
+
+[MIT](LICENSE)