Flow

.agents/AGENTS.md

@@ -0,0 +1 @@
+../AGENTS.md

.github/pull_request_template.md

@@ -1,57 +1,50 @@
-## Description
+<!--
+Thank you for contributing to rclone-manager!
 
-<!-- Briefly describe your changes -->
+Please discuss anything more than a trivial fix in an issue FIRST - see the
+"Linked issue" section below. Then fill in the sections below to help us review.
+-->
 
-## Related Issue
+#### What does this change do?
 
-<!-- Link to the issue this PR addresses (if any) -->
-Closes #
+<!-- Describe the change here. -->
+
+#### Linked issue
 
-## Type of Change
+<!--
+Put `Closes #1234` here if this closes an issue, or `#1234` to link without closing.
 
-<!-- Mark the relevant option with an "x" -->
+IMPORTANT: Anything beyond a trivial fix (typo, doc tweak, small obvious bug fix)
+should be discussed and agreed in an issue BEFORE you open a pull request.
+Pull requests for larger changes that have not been discussed in an issue first
+may be closed. This saves everyone's time if the change needs a different approach
+or isn't a good fit.
+-->
+
+Closes #
+
+#### Type of Change
 
 - [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
 - [ ] ✨ New feature (non-breaking change that adds functionality)
 - [ ] 💥 Breaking change (fix or feature that would cause existing functionality to change)
 - [ ] 📚 Documentation update
-- [ ] 🌍 Translation (new language or translation update)
-- [ ] 🔧 Refactoring (code change that neither fixes a bug nor adds a feature)
-- [ ] 🧪 Tests (adding or updating tests)
-
-## Changes Made
-
-<!-- List the main changes -->
-
-- 
-- 
-- 
-
-## Testing Performed
-
-<!-- Describe how you tested your changes -->
-
-- [ ] Tested on Linux
-- [ ] Tested on macOS
-- [ ] Tested on Windows
-- [ ] Tested on Android
-- [ ] Tested in Headless / Web mode
-- [ ] Tested in development mode (`npm run tauri dev`)
-
-## Screenshots / Recordings
-
-<!-- If applicable, add screenshots to help explain your changes -->
-
-## Checklist
+- [ ] 🌍 Translation (i18n) update
+- [ ] 🔧 Maintenance / Refactoring
 
-<!-- Mark completed items with an "x" -->
+#### Platform & Target Testing
 
-- [ ] My code follows the project's code style
-- [ ] I have run `npm run lint:all` and fixed any issues
-- [ ] I have updated the documentation if needed
-- [ ] My changes don't introduce any new warnings
-- [ ] I have tested my changes thoroughly
+- [ ] Desktop (Linux / macOS / Windows)
+- [ ] Portable mode
+- [ ] Headless / Web Server mode
+- [ ] Mobile (Android)
 
-## Additional Notes
+#### Checklist
 
-<!-- Any other information that reviewers should know -->
+- [ ] This change is trivial **OR** it has been discussed and agreed in the linked issue.
+- [ ] I have read the [contribution guidelines](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+- [ ] **(If I used AI tools to help write this code)** I have read and understood the AI-assisted contributions guidance in [AGENTS.md](AGENTS.md), and I have compiled, linted, tested, and take full ownership of this change myself.
+- [ ] I have run frontend lints (`npx eslint "**/*.{ts,html}"` & `npx prettier --check "**/*.{ts,html,scss,json}"`) or `npm run fix:all`.
+- [ ] I have run backend Clippy & formatting checks (`cargo clippy` and `cargo fmt -- --check` in `src-tauri`).
+- [ ] I have added tests or updated documentation where appropriate.
+- [ ] This Pull Request is ready for review.

.github/workflows/ci.yml

@@ -98,6 +98,7 @@ jobs:
         working-directory: src-tauri
 
       - name: Run Clippy (Mobile)
+        if: matrix.os == 'ubuntu-22.04'
         run: cargo clippy --features mobile --no-default-features -- -D warnings
         working-directory: src-tauri
 

AGENTS.md

@@ -0,0 +1,155 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (e.g. Antigravity, Claude Code, Gemini CLI, Cursor, and similar tools) when working with code in this repository.
+
+Rclone Manager welcomes AI-assisted contributions, but the expectation is that you, the human submitter, understand every line you propose and have compiled, linted, and tested it against real code — not just generated it. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+---
+
+## Project Overview
+
+`rclone-manager` is a cross-platform GUI and web server application for managing [Rclone](https://rclone.org).
+
+- **Frontend**: Angular (v22+), TypeScript, SCSS, RxJS, Angular Material.
+- **Backend**: Rust, Tauri v2 (`src-tauri`), `librclone` C-FFI / Go integration.
+
+---
+
+## General Notes & AI Guidelines
+
+1. **Keep Changes Minimal & Elegant**: Work to make the smallest, most effective change possible. Avoid unneeded refactoring, re-ordering of imports, or restyling surrounding code.
+2. **Backwards Compatibility**: PRs should preserve existing behavior across desktop, web server (headless), and mobile targets.
+3. **Verify Before Proposing**: AI agents must run build, lint, and formatting verification commands before declaring success. **Frontend changes must produce a warning-free build** (see §Build, Test & Lint Commands).
+4. **Automated Testing & Test Coverage (CRITICAL)**:
+   - Just like upstream Rclone and best practices, whenever adding or refactoring business logic, services, utilities, parsers, or mappings, AI agents **MUST** write or update accompanying automated unit tests.
+   - **Frontend**: Unit tests (`*.spec.ts`) are placed in the same directory alongside their corresponding implementation files.
+   - **Backend**: Rust unit tests (`#[cfg(test)]`) are placed inside source files or under test modules.
+   - Verify tests cover both normal operation and edge cases (null inputs, empty values, special characters, error paths).
+
+---
+
+## Essential Code Quality & UI Rules
+
+1. **Tooltip Usage Rule (CRITICAL)**
+   - **DO NOT** use Angular Material Tooltips (`matTooltip`, `MatTooltipModule`).
+   - **ALWAYS** use native HTML `title` attributes for tooltips (e.g., `<button title="Refresh list">...</button>`).
+
+2. **Angular Architecture**
+   - Follow existing service and component patterns.
+   - Use `inject()` for dependency injection where applicable.
+   - Keep translation keys organized and run `npm run audit:i18n` when adding user-facing text.
+
+3. **Angular Material**
+   - Do not use `appearence` in the material form components (inputs, selects, textareas). Use them as default.
+
+4. **URL Opener Links (CRITICAL)**
+   - **ALWAYS** use standard HTML `<a>` tags with `href` attributes for opening URLs (e.g., `<a href="https://..." target="_blank" rel="noopener noreferrer">...</a>` or `<a matButton="filled" [href]="url" target="_blank">...</a>`).
+   - **DO NOT** use `<button>` elements or click handlers to open external web links. `OpenerService` runs a global link interceptor that captures all `<a>` tags with external protocols (http/https/mailto) and opens them safely in the default system browser or new tab.
+
+5. **Menu Component Usage Rule (CRITICAL)**
+   - **DO NOT** use Angular Material Menus (`mat-menu`, `MatMenuModule`, `matMenuTriggerFor`).
+   - **ALWAYS** use CDK Menu (`@angular/cdk/menu`, `CdkMenuModule`, `[cdkMenuTriggerFor]`, `cdkMenu`, `cdkMenuItem`) styled with `.material-context-menu` and `.menu-item` classes.
+
+6. **Internationalization & Backend Error Architecture (CRITICAL)**
+   - **Unified Resource Directory**: All translation files reside in `resources/i18n/{lang}/` (`main.json`, `rclone.json`, `rclone-providers.json`). Do not split or duplicate translation files across other directories.
+   - **Frontend Static Asset Serving**: Angular loads translations via `MultiFileLoader` from static assets (`assets/i18n/...` mapped in `angular.json`).
+   - **Backend Minimal Memory Footprint**: The Rust backend (`src-tauri/src/utils/i18n.rs`) only reads `main.json` and caches only keys needed for OS integrations (`tray`, `notification`, `powerInhibitor`, `alerts`).
+   - **Language-Agnostic Backend Errors**: Rust code must **never** pre-translate error messages. Always use `localized_error!("backendErrors.<category>.<key>", ...)` or `localized_success!("backendSuccess.<category>.<key>", ...)`, producing structured `{ key, params }` JSON or raw keys for `BackendTranslationService` on the frontend.
+
+7. **Platform & Tauri Target Abstraction (CRITICAL)**
+   - **TauriBaseService & `this.isTauri`**:
+     - All backend-communicating services should extend `TauriBaseService`.
+     - Inside classes extending `TauriBaseService`, **always** use the inherited `this.isTauri` property (`!isHeadlessMode()`) rather than re-importing or calling `isHeadlessMode()`.
+     - In standalone components/functions where inheritance is not used, import and call `isHeadlessMode()` from `api-client.service`.
+     - **NEVER** use redundant double-checks like `!this.isTauri || isHeadlessMode()` or call native Tauri APIs without guarding with `this.isTauri`.
+
+8. **Automated Unit Testing & Spec Maintenance**
+   - New utility functions, data transformers, flag parsers, state machines, and business services should always have corresponding unit test suites.
+   - Ensure tests cover both happy paths and edge cases (e.g. empty strings, null values, invalid inputs, error handling).
+
+---
+
+## CI & Automated Workflows ([.github/workflows/](.github/workflows/))
+
+All changes proposed by AI agents must pass the checks enforced by our GitHub Actions workflows:
+
+- **[.github/workflows/ci.yml](.github/workflows/ci.yml)**: Continuous Integration pipeline verifying TypeScript/Angular lints, Prettier formatting, and Rust Clippy compilation across all target features.
+- **[.github/workflows/docker-build-push.yml](.github/workflows/docker-build-push.yml)**: Multi-architecture Docker container build for headless web-server deployment.
+- **[.github/workflows/release-\*.yml](.github/workflows/)**: Cross-platform release workflows (Linux, Windows, macOS, Android, Portable, Headless).
+
+---
+
+## Build, Test & Lint Commands
+
+The commands below mirror the exact validation checks executed in [.github/workflows/ci.yml](.github/workflows/ci.yml).
+
+### 1. Frontend (Angular / TypeScript)
+
+```bash
+# Build the frontend — must complete with ZERO warnings
+ng build
+
+# Lint TypeScript and HTML files
+npx eslint "**/*.{ts,html}"
+
+# Check Prettier formatting
+npx prettier --check "**/*.{ts,html,scss,json}"
+
+# Format frontend code
+npx prettier --write "**/*.{ts,html,scss,json}"
+
+# Auto-fix lint & formatting issues across project
+npm run fix:all
+
+# Run frontend unit tests
+npm run test:ci
+```
+
+> **Frontend Build Rule (CRITICAL)**:
+> After any frontend change, run `ng build` and verify the output contains **no warnings**.
+> Warnings (e.g., unused imports, deprecated APIs, template binding issues) must be treated as build failures and fixed before declaring the task complete.
+
+### 2. Backend (Rust / Tauri)
+
+All Cargo commands are executed from the `src-tauri` directory.
+
+> **Note on `LIBRCLONE_SKIP_LINK_CHECK`**:
+> When `librclone.a` / Go toolchain is not compiled locally, set `export LIBRCLONE_SKIP_LINK_CHECK=1` so Clippy can type-check Rust without linking errors.
+
+```bash
+# 1. Clippy check - Desktop target
+cd src-tauri && cargo clippy --features desktop --no-default-features -- -D warnings
+
+# 2. Clippy check - Web Server target
+mkdir -p dist/rclone-manager/browser
+cd src-tauri && TAURI_CONFIG=$(cat ./tauri.conf.headless.json) cargo clippy --features web-server --no-default-features -- -D warnings
+
+# 3. Clippy check - Mobile target
+cd src-tauri && cargo clippy --features mobile --no-default-features -- -D warnings
+
+# 4. Rust formatting check
+cd src-tauri && cargo fmt -- --check
+
+# 5. Run backend unit tests
+cd src-tauri && cargo test --features desktop --no-default-features
+```
+
+### 3. Local Development
+
+```bash
+# Launch Tauri dev server
+npm run tauri dev
+
+# Feature-specific dev modes
+npm run dev:portable
+npm run dev:headless
+```
+
+---
+
+## Utility Scripts
+
+- `npm run sync:endpoints`: Update endpoint definitions from rclone schemas.
+- `npm run sync:providers`: Sync rclone provider configurations.
+- `npm run sync:flags`: Sync rclone CLI flag definitions.
+- `npm run audit:i18n`: Verify missing translation keys.

CHANGELOG.md

@@ -7,11 +7,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [Unreleased]
 
 ### Added
+- **Flow Overlay & Automation Hub**: Added a dedicated Flow overlay system accessible from the sidebar navigation for streamlined automation, Quick Run execution, and template management. Workflow editor is planned to be added in a future release.
+- **Quick Run Execution & Management System**:
+  - **One-Click Operation Execution**: Launch predefined or custom Rclone operations (Sync, Copy, Move, Mount, Serve, Bisync, Check, etc.) with a single click.
+  - **Real-Time Job Tracking & State Reflection**: Live progress indicators, execution status, and dynamic state updates on Quick Run cards with instant stop/cancellation controls.
+  - **Comprehensive Quick Run Editor**: Easily configure source/destination paths, operation parameters, advanced Rclone flags, and execution preferences.
+  - **CLI Command Import**: Import full CLI command strings (e.g. `rclone copy /src /dst --dry-run --bwlimit 10M`) directly into Quick Run configs and Remote configurations with automatic flag parsing and mapping.
+  - **Card Organization & Tagging**: Organize, tag, search, reorder, duplicate, and manage Quick Runs across custom categories.
+- **Modular Dashboard Overview Panels & Layout Management**: Refactored the dashboard overview into customizable modular panels (System Overview, Disk Usage, Remotes, Mounts, Serves, Operations) with sticky headers and centralized layout customization controls (drag-and-drop ordering and visibility toggles) directly in the header toolbar.
+- **Dedicated Remote Deletion Confirmation Modal**: Added a safety-first confirmation dialog for deleting remotes with clear warnings and dependency awareness.
+- **System Sleep/Shutdown Intercept**: Added OS-level power inhibitor integration on Linux (systemd logind), Windows (ShutdownBlockReasonCreate), and macOS (IOPMAssertionCreateWithName). The application now prevents the system from sleeping or shutting down while active file transfer operations are in progress.
 - **Android Storage Access Framework (SAF) Integration**: Added comprehensive Storage Access Framework (SAF) support for Android devices. #273
   - **SAF Remote & Tree Picker**: Allows selecting and authorizing local directories, SD cards, and USB OTG drives via native Android SAF tree picker intents (`ACTION_OPEN_DOCUMENT_TREE`).
   - **Android DocumentsProvider**: Added `RcloneDocumentsProvider` to expose mounted Rclone remotes to external Android apps and system file pickers.
   - **SAF VFS Mount Bridge**: Integrated a SAF VFS mount bridge enabling in-process virtual filesystem access for Android storage providers.
   - **Android Background Keep-Alive & Boot Receiver**: Added `RcloneKeepAliveService` for persistent background mounts and `ResumeUploadsBootReceiver` for boot initialization on Android.
+- **Template Management**: Added support for managing and using templates. Added in Quick run editor and Remote Config Modal. Releated #260.
+- **Subdirectory-Scoped Real-time Monitoring & File Watcher**: Added an option to synchronize only modified subdirectories instead of scanning the full root tree when triggered by real-time file monitoring events.
+  - **Scoped Sync Targets**: Computes scoped source and destination targets from detected filesystem changes and dispatches targeted batch operations.
+- **Monochrome & Theme-Aware System Tray Icon Management**: Added configurable tray icon theme options (Color, System Auto Monochrome, Monochrome Light, Monochrome Dark) in Preferences -> General. Automatically adapts tray icons to desktop dark/light themes with real-time reactive updates. Closes #286.
+
+### Changed
+- **CLI Import & Flag Mapping Optimization**: Optimized the CLI command parser and import workflow across Quick Run Editor and Remote Config modals. Enhanced tokenizer with intelligent hyphenated argument recognition (e.g. `--suffix -bak`, `--min-age -1d`), multi-operation flag resolution (preserving shared copy/sync flags such as `--backup-dir`, `--track-renames`, `--checksum`), inline bash comment stripping, unified path parsing, and zero-allocation key normalizations in the backend.
+- **Backend Command Bridge & Error Handling**: Migrated backend Tauri command invocations to a standardized bridge macro system with centralized error mapping and structured localization payloads.
+- **Non-Blocking CLI Flags & Automatic Flat Option Mapping**: Updated JSON editor to treat CLI-style arguments (e.g. `--value-of-rclone`, `--bwlimit`) as non-blocking warnings instead of hard validation errors. The backend payload builder now automatically normalizes CLI flags into snake_case flat options (`value_of_rclone`, `bwlimit`) across all Quick Runs, Profiles, and operations.
+- **Native Rclone OAuth Endpoint Integration**: Dropped external Rclone OAuth authorization management in favor of native Rclone OAuth endpoint support (`rclone v1.75+`). Also supports remote Rclone instances.
+- **Minimum Supported Rclone Version**: Updated minimum supported Rclone version to `1.75.0`.
+
+### Removed
+- **Legacy Migrations & Legacy Config Support**: Removed legacy keyring credentials migration, legacy 7z/zip 1.0.0 backup format restore, legacy config conversion maps, legacy settings flattening migrators, legacy UI warning banners, and the `sevenz-rust2` crate dependency. Standard `.rcman` backup restore and preview remain fully supported.
+
+### Fixed
+- **File Browser Freeze & Missing Drives on Wakeup / Stale Mounts**: Fixed an issue where encountering hung or unresponsive drives (e.g. stale WinFsp mounts, disconnected network shares, sleeping HDDs on Windows) or waking up from sleep/systray caused the File Browser sidebar and sync settings drive selectors to freeze and drop both local and cloud remote lists. Disk enumeration in the Rust backend is now non-blocking with timeout protection and graceful root fallback, while frontend remote loading operates independently via `Promise.allSettled`. Fixes #263
+- **Job Stats Group Retention on Finish / Stop**: Fixed an issue where stopping or completing an operation immediately deleted the accounting stats group in rclone memory, causing UI check results, transfer metrics, and error summaries to disappear prematurely. Stats groups are now preserved in rclone memory while the job remains in the job list and are only deleted when the job is actually deleted from the cache, with new operations pre-clearing their group stats before execution. Fixes #211
+- **Docker Entrypoint Privilege Dropping & Supplementary Groups (`PGIDS`)**: Fixed permission denied errors (`EACCES`) when accessing ZFS datasets or directories formatted with NFSv4 ACLs in Docker by replacing `gosu` with `setpriv` in `entrypoint.sh`. Added support for the `PGIDS` environment variable to propagate supplementary group IDs to the daemon process. Fixes #282
+- Fix dynamic reloading of remotes list on rclone configuration and backend settings changes.
+- **Reactive System Theme Updates**: Fixed system theme detection and state synchronization by eliminating blocking CLI subprocess checks in favor of WebKit's native `matchMedia` color-scheme event listeners.
 
 ## [0.3.1] - 2026-07-27