====================================================
FlowChain User Manual
====================================================

FlowChain is a Windows clipboard/copy-paste helper desktop app. It captures
multi-line text, lets you select it line by line, and sends each line as
synthesized keyboard input into whichever window you last focused. It's
well suited to repeating boilerplate text, or any other repetitive typing
task into another application.

Built entirely on the Python standard library and the Windows API (ctypes)
— no extra runtime or library installation is required.


----------------------------------------------------
1. Installation and Placement
----------------------------------------------------

  1. Right-click the downloaded ZIP and select "Extract All." Do not run
     FlowChain.exe directly from inside the ZIP.
  2. Move the entire extracted folder to a writable local location, for
     example: C:\Users\<user>\Documents\FlowChain
  3. Keep FlowChain.exe, the lang folder, and the other bundled files
     together. Do not move only the exe.
  4. Double-click FlowChain.exe to start the app.

  Do not place FlowChain under Program Files, Windows, System32, the root
  of C:\, a read-only folder, or a temporary folder. Network drives and
  cloud-synchronized folders are also discouraged because disconnects or
  sync conflicts can damage the settings or data files. Exit FlowChain
  before moving its folder.


----------------------------------------------------
2. Main Features
----------------------------------------------------

* Capture and send
  Captures the text you selected in another app, splits it into a list by
  newline (or any delimiter you choose), and sends the row you pick into
  that app's input field.

* Multiple tabs (up to 10)
  Manage separate lists across TAB_1 through TAB_10. Tab names can be
  renamed.

* Edge dock
  Docks the window flush against the right edge of the screen and
  collapses it into a thin bar. Click to expand/collapse.

* Target lock
  The "Lock" button pins the current send target window, so clicking
  around in other windows won't change where FlowChain sends to.

* Continuous Send [Pro only]
  Automatically sends items from the top of the list at a configurable
  interval.
  The per-row safety limit is configurable (default: 5,000 characters).
  Over-limit rows block startup; rows of 2,000+ characters show a count,
  longest length, and minimum time estimate. Stop also cancels the active row.

* Broadcast Send [Pro only]
  Right-click a row and choose "Broadcast Send..." to send it to several
  windows at once (e.g. the same prompt to Claude, ChatGPT, and Gemini for
  comparison). A picker lists other visible top-level windows; pick as
  many as you like and click "Send to Selected". FlowChain switches focus
  to each window in turn and sends there, the same as a normal Send.
  Secret masking and the dangerous-command warning both still apply
  (checked once, not per-window). If sending to a window fails partway
  through, the status bar reports how many succeeded and how many didn't.

* Token estimate
  Right-click a row and choose "Token estimate..." for a rough,
  model-agnostic character-based estimate of both the selected row and
  the whole tab (CJK text is counted close to 1 character per token;
  other scripts at roughly 4 characters per token). This is a ballpark
  figure for local reference only, not tied to any specific model's
  actual tokenizer.

* Skip rows
  Put "!" at the beginning of a row to advance without sending it. Leading
  whitespace is ignored. Change the marker under Settings > Skip-line prefix.
  Enable "After send, advance past skipped rows" to jump directly to the next
  sendable row after a successful send (default: OFF).

* Wait rows (AutoSend only)
  A skip row of the form "!wait 5" (5 = seconds, 0.1-3600, decimals allowed
  like "!wait 2.5") pauses AutoSend for that many seconds before continuing
  to the next row, showing a countdown in the status bar. Useful for
  waiting on a device reboot or a short, predictable AI response time. It
  has no effect on manual Send -- it is skipped like any other row there.
  Older FlowChain versions treat it as an ordinary skip row (no wait), so
  files using it stay forward-compatible.

  A skip row of the form "!wait copy" pauses AutoSend indefinitely instead
  of for a fixed duration, resuming as soon as the clipboard changes (e.g.
  you copy the AI's reply to review it) or you press Stop. Handy when a
  reply's length varies too much for a fixed wait to be reliable.

* AUTO ENTER
  Automatically presses Enter or Tab right after each send — handy for
  chat apps or forms where you need to submit after every line.

* Dangerous-command warning [Pro only]
  Before sending a row that looks destructive (rm -rf, DROP TABLE, git push
  --force, shutdown, etc.), FlowChain asks for confirmation. During
  Continuous Send it stops automatically instead of popping up a dialog, and
  shows the reason in the status bar. You can add your own patterns (one
  regex per line) in a danger_patterns.txt file placed next to FlowChain.ini;
  when present it completely replaces the built-in pattern list. Toggle this
  under Settings > General.

* Secret masking [Pro only]
  Before sending, FlowChain scans the row for things that look like API
  keys, tokens, or private key blocks and replaces them with placeholders
  like [MASKED-1] — only the placeholder is actually sent/typed, and the
  real value never touches the send log. When you later capture the
  reply (which naturally echoes the placeholder back), FlowChain restores
  it to the real value automatically. The mapping lives in memory only —
  it's never saved to disk and is gone on restart or when you use Settings
  > General > "Clear masked secrets now". You can add your own patterns
  (one regex per line) in a secret_patterns.txt file next to
  FlowChain.ini, which completely replaces the built-in pattern list.
  Toggle this under Settings > General.

* Prompt/response log [Pro only]
  When enabled (Settings > General), FlowChain remembers the text of every
  row you send with the "Send" button. The next time you use the
  "Capture" button (not auto-watch, not insert-at-cursor), that captured
  text is paired with the pending prompt and added to an in-memory log —
  matching the normal workflow of send a prompt, then capture the AI's
  reply back in. File > "Export prompt/response log..." saves the whole
  log as a Markdown report (each pair in its own fenced code blocks).
  The log only lives in memory for the current session and is not
  persisted to disk on its own. Settings > General > "Clear prompt/
  response log now" empties it immediately without disabling the
  feature, useful if the log has grown large or contains something you
  no longer want held in memory.

* Auto-capture clipboard changes [Pro only]
  Automatically captures new items whenever the clipboard content
  changes.

* Configurable item delimiter
  Choose Newline, Comma, Tab, or Semicolon (the free tier only offers
  Newline and Tab).

* AI-output cleanup on capture (Settings > General > Capture cleanup)
  Independent toggles applied while capturing, auto-watching, or
  inserting clipboard text (not to file imports, which are left as-is):
  "Extract fenced code blocks only" keeps just the content inside ``` ```
  fences (fence markers and language tags stripped); "Strip list markers"
  removes a leading "1. "/"1) "/"- "/"* "/"• " from each line; "Strip
  prompt symbols" removes a leading "$ " or "> ". "Split multiple code
  blocks into separate items" changes fence handling so each fenced block
  becomes its own item (keeping its internal line breaks) instead of all
  fence contents being joined and then re-split by the item delimiter --
  handy when a reply contains several separate code blocks (e.g. multiple
  files) that you want to send one at a time. "Validate and format JSON"
  checks any captured text (or, combined with the fence-splitting toggle
  above, each fenced block) that looks like a JSON object/array: valid
  JSON is pretty-printed and kept as a single item; JSON-shaped text that
  fails to parse is left as-is with a warning explaining why, so a
  truncated or malformed AI-generated config doesn't slip in silently.
  (YAML isn't validated -- this app has no required third-party
  dependencies, and a real YAML parser isn't in the standard library.)

* Find & Replace (Edit menu)
  Search (Ctrl+F) and bulk-replace (Ctrl+H) text within the current tab.
  A "Regular expression" checkbox in both dialogs [Pro only] switches from
  plain substring matching to a regex pattern; capture groups can be
  referenced in the replacement text as \1, \2, etc. An invalid pattern is
  reported in the status bar without changing anything.

* Undo / Redo (Edit menu)
  Per-tab edit history you can step backward and forward through
  (Ctrl+Z / Ctrl+Y).

* Fill template variables (Edit menu)
  Fill in every {{variable}} placeholder found in the current tab's items
  at once.

* Export / Import (File menu)
  Export or import the current tab, or all tabs at once, as text files.
  You can also export a log of everything that's been sent this session,
  and (if the prompt/response log is enabled) a Markdown report of
  paired prompts and replies.

* Snippets / prompt library (File menu) [Pro only]
  Save the current tab's items as a named, reusable snippet. Saved snippets
  appear in the same menu — clicking one appends its items to the end of
  the current tab. "Manage..." opens a dialog to rename, reorder, or delete
  saved snippets. Handy for command sets or prompt chains you send often.

* Custom global hotkeys
  Change the Capture/Send shortcuts to any global hotkey combination that
  works even while another app has focus (defaults: Ctrl+Alt+C /
  Ctrl+Alt+V).

* Configurable paste shortcut
  Register and switch between multiple paste key combinations used to
  send text into the target app (e.g. Ctrl+V) — useful for apps like
  TeraTerm that use a different shortcut for paste.

* Update check
  Checks GitHub for a newer release at most once every 24 hours (5 seconds
  after startup). If one is found, the status bar shows a notice and
  Settings > Check for updates turns into a clickable link to the release
  page. No automatic download — this is notification only. Skipped
  entirely for Microsoft Store installs, since the Store delivers updates
  itself. Turn it off under Settings > General.

* 7-language UI
  English, 日本語, 简体中文, Español, 한국어, Português (Brasil), Deutsch.
  Switch anytime from Settings > Language — no restart needed.

* System tray / Windows startup
  Minimize to the system tray on minimize or on close, and optionally
  launch automatically when Windows starts.

* Single-instance guard
  Warns you and refuses to start a second copy if FlowChain is already
  running.


----------------------------------------------------
3. Basic Usage
----------------------------------------------------

  1. Select the text you want to send in the source app.
  2. Capture it with the "Capture" button, or the capture hotkey
     (default Ctrl+Alt+C).
  3. Pick the row you want to send from the resulting list (split by
     line).
  4. Click into the target app's input field once to focus it.
  5. Send it with the "Send" button, Enter, double-click, or the send
     hotkey (default Ctrl+Alt+V).

  Selection automatically moves to the next row after sending. Sent rows
  are shown slightly greyed out, but you can right-click and choose
  "Mark as unsent" to resend them.


----------------------------------------------------
4. Settings Menu Reference
----------------------------------------------------

  Settings > General
    Language                    Switch UI language (7 languages)
    Start with Windows          Launch automatically at Windows startup
    Auto-capture clipboard      Enable clipboard auto-capture (Pro)
    Capture cleanup             AI-output cleanup toggles (fences, list
                                 markers, prompt symbols, fences-as-items,
                                 JSON validate/format)
    Warn on dangerous commands  Confirm before sending destructive rows (Pro)
    Mask secrets before sending  Replace API keys/tokens with placeholders (Pro)
    Clear masked secrets now   Forget the current masked-secret mapping
    Record prompt/response pairs  Log Send+Capture pairs for export (Pro)
    Check for updates automatically  Notify when a newer release is out
    Edge dock                   Enable docking to the right screen edge

  Settings > Window and tray
    Minimize to tray            Minimize to the system tray
    Minimize to tray on close   Minimize to tray instead of closing (x)
    Minimize now                Immediately place FlowChain in the tray

  Settings > Sending
    Send method                 Clipboard paste vs. keystroke typing
    Chat mode                   With keystroke typing, send newlines inside
                                 an item as Shift+Enter instead of Enter, so
                                 a multi-line item isn't submitted early by a
                                 chat app's "Enter sends the message"
                                 handler. Has no effect on clipboard paste,
                                 which was already safe. AUTO ENTER still
                                 submits the message once the whole item has
                                 been typed.
    Paste shortcut              Manage paste key-combination presets
    Item delimiter              Delimiter used to split captured text
    AUTO ENTER key              Key sent automatically after each send
    AUTO ENTER delay            Delay before the automatic key is sent

  Settings > AutoSend
    Continuous send interval    Interval for Continuous Send (Pro)
    AutoSend max characters     Per-row long-text safety limit (default: 5,000)
    Skip-line prefix            Change the skip marker/string (default: !)
    Advance past skipped rows   Select the next sendable row after sending (default: OFF)

  Settings > Hotkeys            Change the global capture/send hotkeys
  Settings > Settings files     Save or load a settings profile
  Settings > Upgrade to Pro     Purchase the Pro upgrade
  Help > About FlowChain        Show version information


----------------------------------------------------
5. Item Right-Click Menu
----------------------------------------------------

  Send                  Send the selected row
  Broadcast Send...      Send the selected row to several windows at once (Pro)
  Edit                  Edit the selected row's text
  Token estimate...      Show a rough token-count estimate
  Mark as unsent         Clear the "sent" indicator
  Move up / Move down    Reorder the row (Alt+Up / Alt+Down also work)
  Insert clipboard here  Insert the current clipboard content here
  Delete                 Delete the selected row

  Ctrl+V while the item list has focus pastes directly too: it replays
  rows you cut with Ctrl+X if any are pending, otherwise it inserts
  whatever text is currently on the OS clipboard at the cursor row —
  the same result as "Insert clipboard here" above, without opening the
  right-click menu.


----------------------------------------------------
6. Free vs. Pro
----------------------------------------------------

  Feature            | Free                | Pro
  -------------------|---------------------|------------------------
  Tabs                | Up to 2             | All 10
  Continuous Send     | Not available       | Available
  Item delimiter      | Newline, Tab only   | Newline, Comma, Tab, Semicolon
  Clipboard auto-watch | Not available       | Available
  Dangerous-command warning | Not available  | Available
  Secret masking       | Not available       | Available
  Regex find/replace   | Not available       | Available
  Snippet library       | Not available       | Available
  Broadcast Send        | Not available       | Available
  Prompt/response log   | Not available       | Available
  Ad banner            | Shown              | Hidden

  The free tier shows an ad banner at the bottom of the window. Pro is a
  one-time in-app purchase that removes all of the restrictions above.


----------------------------------------------------
7. Saved Files
----------------------------------------------------

  On first launch, FlowChain creates the following files next to
  FlowChain.exe:

  FlowChain.dat   Per-tab item lists, selection, and sent-status
  FlowChain.ini   Hotkeys, typing delay, item/character limits, tray
                  settings, window position/size, and dock state
  FlowChainSnippets.json   Saved snippets (Pro), created only once you
                  save your first snippet
  danger_patterns.txt   Optional custom danger-check patterns (Pro),
                  one regex per line — only read if you create it yourself
  secret_patterns.txt   Optional custom secret-masking patterns (Pro),
                  one regex per line — only read if you create it yourself.
                  The masked-secret mapping itself is never written to disk.

  %APPDATA% is never used. Since settings and data are saved in this
  folder, avoid placing it under Program Files or anywhere else with
  restricted write access.


----------------------------------------------------
8. Publisher Verification (if you see a SmartScreen warning)
----------------------------------------------------

  On systems with Smart App Control or similar enabled, Windows may warn
  that the publisher of this exe can't be verified.

  Download FlowChain only from its official GitHub release page and verify
  the published SHA-256 checksum before running it. A signature alone does
  not guarantee that SmartScreen will suppress every warning.


----------------------------------------------------
9. Version History
----------------------------------------------------

[Version 1.9.2]
  - Added a floating tab preview that follows the pointer while a tab is
    dragged, with a short lift-and-fade animation

[Version 1.9.1]
- Completed localized labels for recently reorganized settings menus.
- Added automatic validation for translation formatting placeholders.

[Version 1.9.0]
  - Added Reset all tabs to the File menu
  - Added an irreversible-action confirmation before clearing every tab's
    contents, name, send state, text transforms, and undo/redo history

[Version 1.8.1]
  - Fixed default tab labels so TAB_1, TAB_2, and other generated names
    visibly move with their tab contents during drag-and-drop

[Version 1.8.0]
  - Added drag-and-drop tab reordering on the tab bar
  - Preserved each moved tab's commands, active selection, and undo/redo
    history when moving it across multiple positions
  - Kept drag-and-drop reordering within the available two-tab area in the
    free ADS edition; Pro can reorder all tabs

[Version 1.7.0]
  - Added whole-tab text editing for revising a list in an editor-style
    dialog and applying it back to the tab
  - Added right-click clipboard paste directly into the list below the
    focused row
  - Changed text insertion so new items are added below the focused row
    when possible instead of always appending
  - Added tab move controls for reordering task tabs

[Version 1.4.2]
  - Fixed Microsoft Store add-on purchase ID handling
  - Started the Store purchase dialog on the UI thread and associated it
    with the FlowChain window
  - Prevented duplicate purchase dialogs and stale entitlement refreshes
  - Hardened MSIX identity, architecture, and private-file validation

[Version 1.4.1]
  - Fixed edition isolation so an editable INI value can no longer unlock
    Pro features in the ADS edition
  - Added strict public/private repository boundary checks
  - Consolidated language resources and added semantic menu tests
  - Added embedded Windows file/product version information and a verified
    sign-before-package release flow

[Version 1.1.0]
  - Added custom global hotkey configuration (Capture/Send hotkeys can
    now be freely reassigned)
  - Fixed toolbar button labels not updating correctly after changing a
    hotkey
  - Strengthened and completed non-Japanese translations
  - Fixed choppy edge-dock expand animation
  - Fixed the window briefly spilling onto the neighboring monitor when
    expanding

[Version 1.0.0]
  - Added Find and Find & Replace to a new Edit menu
  - Added real per-tab Undo/Redo
  - Added a File menu (Save, export/import all tabs, export send log)
  - Added template-variable ({variable}) bulk fill-in
  - Redesigned the About dialog with an icon and a clearer layout
  - Fixed blank-line paragraph breaks being lost on capture/insert
  - Fixed IME (Japanese/Chinese/Korean input) composition font size in
    the Find/Replace dialogs and elsewhere
  - Switched the Microsoft Store submission build to native Nuitka
    compilation

[Version 0.2.0]
  - Added a new Edit menu with Find, Find & Replace, and Undo/Redo
  - Moved paste-shortcut registration into Settings, now captured via an
    actual key press instead of typing it out
  - Added a new File menu (Save, reorganized Export/Import)
  - Polished the dock's rounded corners and toolbar layout

[Version 0.1.0]  (Initial release)
  - Core capture / row-select / send workflow
  - 10-tab management, right-click reordering (Alt+Up/Down)
  - Text file export/import
  - AUTO ENTER (automatic Enter/Tab after send)
  - Clipboard auto-capture watch mode
  - Continuous auto-send with a configurable interval
  - Configurable item delimiter (newline, comma, tab, semicolon)
  - Multiple registrable paste shortcuts
  - Edge dock (expand/collapse)
  - Target lock
  - System tray residency, Windows startup registration, single-instance
    guard
  - Introduced the Free/Pro feature-tier model (ads, tab count,
    Continuous Send, etc.)
  - 7-language UI (Japanese, English, Simplified Chinese, Spanish,
    Korean, Brazilian Portuguese, German)
  - Added the About dialog


====================================================
Publisher: edgehawk
====================================================
