Add a dev doc for option modifiers

Author: harendra-kumar

docs/Developer/option-modifiers.md

@@ -0,0 +1,71 @@
+# Option Modifiers
+
+Instead of exposing internal record structures, this library
+uses **Option Modifiers**: functions of type `Config -> Config`
+(endomorphisms) that are composed to build a final configuration.
+
+## Advantages
+
+* **Clean Composition:** Use the standard `.` operator to chain multiple
+options together seamlessly.
+* **Encapsulation:** The internal record structure and field names
+remain hidden, preventing breaking changes if the implementation shifts.
+* **Order Independence:** Unlike positional arguments, the order of
+modifiers in a chain does not affect the final result (unless a specific
+option is overridden).
+* **Unified Interface:** Removes the need for record syntax or multiple
+constructor patterns. There is only one way to specify options: through
+functions.
+* **Bundling:** Common configurations can be pre-composed into a single
+named modifier (e.g., `standardRecursive = withRecursive FollowTopLink .
+withForce True`).
+* **Discipline:** By limiting the "surface area" of the API, we reduce
+the possibility of misuse or invalid state transitions.
+
+## Disadvantages
+
+* **Discovery:** Users cannot simply "see" the available options via a
+record definition; they must rely on module documentation.
+
+* **Introspection:** It is difficult to inspect a composed modifier
+chain to see what it "contains" before applying it to a base
+configuration.
+
+## Modifiers and Setters
+
+We use the prefix `with` for option modifiers (e.g., `withRecursive`,
+`withForce`).
+
+**Why `with`?**
+Unlike `set`, which implies an imperative "action" or a binary toggle,
+`with` conveys a functional transformation. It suggests that the
+resulting operation will be performed *with* a specific property or
+value, regardless of the previous state.
+
+## Expressing All Possible Values
+
+A modifier must be **total**. It should not merely "toggle" a default;
+it must allow the user to explicitly define the desired state.
+
+If a user receives a pre-composed bundle of modifiers, they may not know
+the current state of a specific option. To ensure predictable behavior,
+the modifier must allow them to force a value (e.g., `withVerbose True`
+or `withVerbose False`), ensuring the final config matches their intent
+regardless of the input chain.
+
+## Reset to Default
+
+While the base configuration starts with library defaults, we provide
+`resetOption` functions (e.g., `resetRecursive`).
+
+These are useful when you want to "neutralize" an option within a
+specific composition. For example, if you have a `standardConfig` bundle
+that includes recursion, but for one specific call you want to ensure it
+is disabled, you can simply append `. resetRecursive` to the chain.
+
+## Summary
+
+By using composed endomorphisms, we provide a declarative DSL for
+filesystem operations. This approach balances the flexibility of a
+record with the safety and elegance of functional composition, covering
+all use cases while maintaining a strict, predictable API.