Update the README

README.md

@@ -19,48 +19,49 @@
 ## Table of Contents
 1. [Introduction](#introduction)
 2. [Quick Demo](#quick-demo)
-3. [Why FlowHook?](#why-flowhook)
-4. [Installation](#installation)
-5. [Command Reference & Usage](#command-reference--usage)
+3. [Installation](#installation)
+4. [Command Reference & Usage](#command-reference--usage)
+5. [Limitations](#limitations)
+6. [Contributing](#contributing)
 
 
 ### Introduction
 
-FlowHook is an open-source CLI tool that can automate build processes by watching filesystem events and executing build commands automatically. It is designed to be simple, efficient, and easy to use. It enables you to define your build commands using a simple CLI interface. It supports multiple build commands. And it also enables you to hook other set of commands to be triggered after a successful build or a failed build.
-
-It can watch your directory for changes and execute build commands automatically when changes are detected.
+Flowhook is a lightweight C++ file-watcher CLI using Linux inotify. It allows you to define build commands, branch on success/failure, log your build history to a log file and persist watch state across reboots.
 
 ### Quick Demo
 
 [![asciinema demo](https://asciinema.org/a/Wc2xprecUM1YnUK0.svg)](https://asciinema.org/a/Wc2xprecUM1YnUK0)
 
 *Click the player above to watch a full 3-minute walkthrough of FlowHook tracking file modifications and running build commands automatically including the hook feature.*
 
-
-### Why FlowHook?
-
-FlowHook started out of personal necessity and a desire to look under the hood. A few months ago, I began diving deep into C++ and exploring systems programming. While falling in love with low-level control, I quickly hit a massive developer bottleneck: the constant, frustrating friction of having to manually re-compile and execute code every single time I made a minor file modification just to see if my changes worked. 
-
-While heavy, pre-existing file-watching frameworks exist, I decided to build FlowHook as a raw learning tool to solve this exact pain point. As the project evolved, my focus shifted toward tailoring the tool to handle the specific real-world workflow issues I face every night, shaping it into something I actually want to use every day. 
-
-What began as a simple automation script grew into a highly optimized, zero-bloat systems utility. Because it operates close to the iron and leverages the Linux kernel’s native `inotify` subsystem, it monitors deep project directories with near-zero CPU overhead and a virtually invisible memory footprint. 
-
 ### What Makes it Different?
 While there are other file watchers out there, FlowHook was designed with a few core strengths that are difficult to find out-of-the-box in popular alternatives:
 
-* **True Persistence:** FlowHook configurations don't evaporate. Your active watch environments and tasks are securely serialized to disk. If your system fully shuts down or reboots, FlowHook recovers its exact state gracefully on reload without locking up on stale paths. Once you set up your system you only need to run the `flowhook run` command whenever you want to start monitoring your project and start a session.
-* **Multi-Project Task Orchestration:** It isn't restricted to a single folder. A single instance can keep track of completely separate projects, mapping out individual boundaries and firing off independent hook configurations concurrently.
-* **Contextual Branching (`on_success` / `on_failure`):** Instead of blindly executing a single catch-all command string on save, FlowHook intrinsically tracks execution exit states. This allows you to uniquely fork separate execution paths—like running an extensive test suite only if the compilation passes, or sending a desktop notification the exact millisecond a build breaks.
+* **True Persistence:** FlowHook configurations are saved to a config file, giving it true persistence. Once you set up your project configurations you only need to run the `flowhook run` command whenever you want to start monitoring your project and run your commands at file change.
+* **Contextual Branching (`on_success` / `on_failure`):** It allows you to attach different commands to run based on the exit state of the previous command, so you can run different commands depending on whether the build succeeded or failed. Use cases include running different test suites depending on the build outcome, or sending desktop notifications based on the build result.
 * **Language Agnostic:** Though engineered in native C++, FlowHook is entirely toolchain-agnostic. Whether you are compiling C++, watching TypeScript builds, restarting a Go backend, or running Python scripts, it hooks into any CLI pipeline seamlessly.
-* **Session Tracking:** FlowHook keeps track of your active sessions, and logs information about each of your sessions, into a log file called `<YOUR_PROJECT_NAME>-flowhook.log` right in your project directory. So you can easily review the history of your sessions and your build history including the terminal output and several other informations, and debug any issues that arise at any time.
+* **Logs Everything:** FlowHook keeps track of your active sessions, and logs information about each of your sessions, into a log file called `<YOUR_PROJECT_NAME>-flowhook.log` right in your project directory. So you can easily review the history of your sessions and your build history including the terminal output and several other informations. Use cases include debugging build issues, tracking build history, and monitoring build outcomes.
 
 ### Installation
 
 #### Option 1
 
 This is the easiest way to get started with FlowHook.
 
-1. You can grab the latest release from the [GitHub releases page](https://github.com/etcoder-642/FlowHook/releases/latest). Steps to download the binary release can be found in the release page.
+1. Grab the latest release from the [GitHub releases page](https://github.com/etcoder-642/FlowHook/releases/latest).
+2. Unzip the downloaded file.
+```bash
+unzip flowhook.zip 
+```
+3. Grant execute permissions to the `flowhook` binary.
+```bash
+chmod +x flowhook
+```
+4. Move the `flowhook` binary to a directory in your `PATH` (e.g. `/usr/local/bin`).
+```bash
+sudo mv flowhook /usr/local/bin/
+```
 
 #### Option 2
 
@@ -114,23 +115,25 @@ flowhook init
 ```bash
 flowhook add --command "make" --on-success "./run_tests" --on-failure "echo 'Fix the build!'"
 ```
-3. Prevent heavy transient directories from overloading tracking tables
+3. Ignore build artifacts and transient directories from being tracked by FlowHook
 ```bash
 flowhook add --ignored-path "build/" --ignored-pattern "*.o"
 ```
-4. Spin up the background thread filewatcher engine
+4. Spin up the background thread filewatcher
 ```bash
 flowhook run
 ```
 
 ### Global Flags
 These flags can be appended to the base flowhook command from anywhere:
 
-`-h`, `--help` — Displays structural help layouts and options for any command or subcommand.
+`-h`, `--help` — Displays help information for the base flowhook command.
+
+`--version` — Prints the version of the installed flowhook engine.
 
-`--version` — Prints the active engine version layout (0.0.0) and immediately exits.
+`--verbose` — Enables verbose logging output. *it is not global flag and must be used with a base flowhook subcommand. But all subcommands support it.*
 
-`--verbose` — Enables verbose logging output.
+`--debug` — Enables debug logging output. This is useful for troubleshooting and seeing detailed log output. *it is not global flag and must be used with a base flowhook subcommand. But all subcommands support it.*
 
 ### Subcommands
 
@@ -145,31 +148,34 @@ Options:
   `--task TEXT`[OPTIONAL] — enables you to name your flowhook instance a unique name. If not provided the filename of your current directory will be taken as name. 
 
 #### 2. add
+To register a property to your flowhook instance, use the `add` subcommand.
 
 Usage: `flowhook add [options]`
 
 Options:
 
-`--command "<cmd>"` — The base target compilation or execution string to trigger on file change.
+`--command "<cmd>"` — The base target command to be executed on file change.
+
+`--path "<path>"` — enables you to specify a path any directory or file from any where from your machine to be watched for file changes. *If it's a directory, all files within it until the depth limit is reached will be watched recursively.*
 
-`--on-success "<cmd>"` — Hook execution path to fork immediately if the base target command returns exit code 0.
+`--on-success "<cmd>"` — Hook a separate command for execution if the base target command returns exit code 0.
 
-`--on-failure "<cmd>"` — Hook execution path to fork immediately if the base target command returns a non-zero exit code.
+`--on-failure "<cmd>"` — Hook a separate command for execution if the base target command returns a non-zero exit code.
 
-`--ignored-path "<path>"` — Tells the internal filewatcher module to explicitly skip registering inotify bounds on this directory.
+`--ignored-path "<path>"` — register a directory to be ignored by the filewatcher.
 
-`--ignored-pattern "<glob>"` — Skips filing tracking updates for files matching specific extensions (e.g., *.tmp, *.o).
+`--ignored-pattern "<glob>"` — register a file pattern to be ignored by the filewatcher. (e.g., `*.tmp`, `*.o`)
 
 #### 3. list
-Dumps an immediate structural breakdown of the currently registered configuration data into your terminal.
+To list all registered tasks, paths, commands, and ignored patterns, in your flowhook instance in the current directory, use the `list` subcommand.
 
 Usage: `flowhook list [options]`
 
 Flags:
 
   `--tasks` — lists all registered tasks and their associated paths in your machine.
 
-  `--paths` — lists all registered paths and watched paths in the working directory.
+  `--paths` — lists all registered paths and watched paths in the current directory.
 
   `--commands` — lists all build commands registered in the current directory.
 
@@ -180,22 +186,36 @@ Flags:
   `--on-failure` — lists all on failure commands to run in the current directory.
 
 #### 4. remove
-Drops a specified path boundary, target match pattern, or hook configuration from the active registry.
+To remove a registered task, path, command, or ignored pattern, use the `remove` subcommand.
 
 Usage: `flowhook remove [options]`
 
+*if no options are provided, the `remove` subcommand will remove the flowhook configuration from the current directory, with a confirmation dialog.
+
 Options:
 
-`-f` — Bypasses structural verification checks to force immediate state eviction.
+`-f` — Bypasses verification checks to force immediate removal of the flowhook configuration in the current directory.
+
+`--command "<cmd>"` — removes a base target command from the flowhook configuration.
+
+`--path "<path>"` — removes a path from the flowhook configuration.
+
+`--on-success "<cmd>"` — removes a separate command for execution if the base target command returns exit code 0.
+
+`--on-failure "<cmd>"` — removes a separate command for execution if the base target command returns a non-zero exit code.
+
+`--ignored-path "<path>"` — removes a directory to be ignored by the filewatcher.
+
+`--ignored-pattern "<glob>"` — removes a file pattern to be ignored by the filewatcher. (e.g., `*.tmp`, `*.o`)
 
 #### 5. set
-Tweaks global engine performance constants and environmental execution behaviors.
+To change different settings in the flowhook configuration, use the `set` subcommand.
 
 Usage: `flowhook set [options]`
 
 Options:
 
-`--depth <int>` — Adjusts recursive folder watch limits. Accepts integers mapping from 0 (shallow directory tracking) up to 10.
+`--depth <int>` — Adjusts recursive folder watch limits. Accepts integers mapping from 0(shallow tracking) up to 10(deep recursive tracking).
 
 Flag:
 
@@ -206,23 +226,41 @@ It checks for the status set by the `set` command.
 
 Usage: `flowhook check`
 Options: 
-  `--depth`  - Adjusts recursive folder watch limits.
+  `--depth`  - outputs the recursive folder watch limits set for the flowhook configuration in the current directory.
   `--active`  - checks if current flowhook instance in the current working directory is labeled active.
   `--deactive`  - checks if current flowhook instance in the current working directory is labeled deactive.
 
 #### 7. run
-Spins up the underlying filewatcher background-thread, mounts native kernel inotify tracking hooks across the working directory, and starts orchestrating loops.
+Spins up the underlying filewatcher background-thread. Mounts registered commands and hooks for execution.
 
 Usage: `flowhook run`
 
 Flags:
 
- `--quiet` — Silences non-essential lifecycle output streams, funneling thread-safe logs strictly to background buffers instead of flooding stdout.
+ `--quiet` — Silences non-essential build terminal output streams, funneling terminal logs strictly to the log file instead of flooding stdout.
 
  `--all` - Runs all registered tasks across the entire machine.
  `--active` - Runs all tasks that are labeled as active.
 
-Your complete layout is officially complete.
+## Limitations
+
+FlowHook is early and has some known gaps:
+
+- **Linux only.** Relies directly on the kernel's `inotify` subsystem. No macOS or Windows support. Planned in the near term.
+- **Sequential command execution.** Commands run one at a time, not concurrently. A thread pool for concurrent execution is planned.
+- **No write-ahead logging (WAL).** Config writes and log writes aren't crash-safe. A failure mid-write can corrupt the config file, losing all registered projects. Same risk applies to session logs.
+- **No daemon/service mode.** `flowhook run` is a foreground process; use `nohup`, `tmux`, or a systemd unit if you need it to survive terminal closure.
+
+These are known gaps, not surprises. Issues and PRs addressing any of them are welcome.
+
+## Contributing
+FlowHook is early-stage and contributions are genuinely welcome, from bug fixes to feature ideas.
+
+- Found a bug? [Open an issue](https://github.com/etcoder-642/FlowHook/issues).
+- Have a feature in mind? Open an issue to discuss before submitting a large PR.
+- **PRs should target the `dev` branch, not `main`.** `main` is reserved for tagged releases. I merge from `dev` myself once changes are reviewed and versioned.
+
+No formal contribution guide yet. For now, fork, branch off `dev`, and open a PR against `dev`.
 
 ## Author