From aef382c208ff1e02e2b427f45bef12f967547f8b Mon Sep 17 00:00:00 2001
From: vipul674 <vipulponugoti@gmail.com>
Date: Mon, 22 Jun 2026 22:32:18 +0530
Subject: [PATCH] docs: add Flow Launcher plugin documentation (closes #447)

---
 docs/plugins/README.md        | 10 ++++
 docs/plugins/flow-launcher.md | 89 +++++++++++++++++++++++++++++++++++
 docs/plugins/toc.yml          |  2 +
 3 files changed, 101 insertions(+)
 create mode 100644 docs/plugins/flow-launcher.md

diff --git a/docs/plugins/README.md b/docs/plugins/README.md
index 85fdbec7..e045b1fe 100644
--- a/docs/plugins/README.md
+++ b/docs/plugins/README.md
@@ -93,6 +93,7 @@ Deep-merges TOML settings into `%USERPROFILE%\.rustup\settings.toml`.
 | `autohotkey` | Manages an AutoHotkey v2 bootstrap script and WinHome-owned settings block. | `config_provider` | [Details](#autohotkey) |
 | `espanso`    | Manages Espanso text expansion rules in `base.yml`.                         | `config_provider` | [Details](#espanso)    |
 | `everything` | Manages Everything search application configuration.                        | `config_provider` | [Details](#everything) |
+| `flow-launcher` | Manages Flow Launcher desktop search settings in `Settings.json`.       | `config_provider` | [Details](#flow-launcher) |
 | `greenshot`  | Manages Greenshot screenshot utility settings in `Greenshot.ini`.           | `config_provider` | [Details](./greenshot.md) |
 | `keepassxc`  | Manages KeePassXC INI settings.                                             | `config_provider` | [Details](#keepassxc)  |
 | `powertoys`  | Manages PowerToys general settings and supported module settings.           | `config_provider` | [Details](#powertoys)  |
@@ -532,6 +533,15 @@ Config key: `extensions.everything`
 
 Manages supported Everything configuration settings through WinHome.
 
+<a id="flow-launcher"></a>
+
+#### flow-launcher
+
+Config key: `extensions.flow-launcher`
+
+Deep-merges settings into `%APPDATA%\FlowLauncher\Settings\Settings.json`. See
+[full docs](flow-launcher.md).
+
 <a id="keepassxc"></a>
 
 #### keepassxc
diff --git a/docs/plugins/flow-launcher.md b/docs/plugins/flow-launcher.md
new file mode 100644
index 00000000..3c880c77
--- /dev/null
+++ b/docs/plugins/flow-launcher.md
@@ -0,0 +1,89 @@
+# Flow Launcher Plugin
+
+## Overview
+
+The Flow Launcher plugin manages settings for [Flow Launcher](https://www.flowlauncher.com/) — a
+desktop search utility for Windows. It reads and writes directly to the Flow Launcher
+`Settings.json` file, giving WinHome control over hotkeys, search options, plugin configuration,
+and theme settings.
+
+## Prerequisites
+
+- Flow Launcher installed
+- Windows only (uses `%APPDATA%`)
+
+## Configuration Schema
+
+| Key | Purpose |
+| --- | ------- |
+| Hotkey | Global activation shortcut |
+| Theme | UI theme name |
+| SearchPluginsEnabled | Enable/disable plugin search results |
+| ColorScheme | Accent color scheme |
+| AutoUpdates | Enable automatic updates |
+| Plugins | Nested map of per-plugin settings |
+
+The full set of supported keys is defined by Flow Launcher's `Settings.json` schema, which follows
+a flat or nested key-value structure. The plugin deep-merges any keys provided under
+`extensions.flow-launcher.settings` into the existing settings file.
+
+## Usage Examples
+
+### Basic hotkey and theme
+
+```yaml
+extensions:
+  flow-launcher:
+    settings:
+      Hotkey: "Alt+Space"
+      Theme: "Dark"
+      ColorScheme: "System"
+```
+
+### Enable/disable plugin search
+
+```yaml
+extensions:
+  flow-launcher:
+    settings:
+      SearchPluginsEnabled: false
+      AutoUpdates: true
+```
+
+### Per-plugin settings
+
+```yaml
+extensions:
+  flow-launcher:
+    settings:
+      Hotkey: "Ctrl+Alt+K"
+      Theme: "Light"
+      Plugins:
+        Flow.Launcher.Plugin.Calculator:
+          Precision: 4
+        Flow.Launcher.Plugin.WebSearch:
+          DefaultBrowser: true
+```
+
+## Verification Steps
+
+1. Run WinHome apply and confirm no errors:
+
+   ```bash
+   winhome apply
+   ```
+
+2. Open Flow Launcher (default hotkey) and verify the settings took effect.
+
+3. Inspect the settings file directly:
+
+   ```bash
+   type "%APPDATA%\FlowLauncher\Settings\Settings.json"
+   ```
+
+## Notes / Caveats
+
+- Only Windows is supported (relies on `%APPDATA%`).
+- The plugin uses atomic writes via `tempfile.mkstemp()` + `os.replace()` to prevent corruption.
+- Plugins settings are deep-merged, so existing per-plugin configuration is preserved when only
+  updating specific plugin keys.
diff --git a/docs/plugins/toc.yml b/docs/plugins/toc.yml
index a9cc840d..e29f1b45 100644
--- a/docs/plugins/toc.yml
+++ b/docs/plugins/toc.yml
@@ -24,6 +24,8 @@
   href: gh-dash.md
 - name: Gh
   href: gh.md
+- name: Flow Launcher
+  href: flow-launcher.md
 - name: Mise
   href: mise.md
 - name: Npm