feat: restructure project and update documentation

src/docs/api/$.md

@@ -0,0 +1,101 @@
+# The Reactive Core: `$( )`
+
+The `$` function is the heart of **SigPro**. It is a **Unified Reactive Constructor** that handles state, derivations, and side effects through a single, consistent interface.
+
+## 1. The Constructor: `$( input )`
+
+Depending on what you pass into `$( )`, SigPro creates a different type of reactive primitive:
+
+| Input Type | Result | Internal Behavior |
+| :--- | :--- | :--- |
+| **Value** (String, Number, Object...) | **Signal** | Creates a piece of mutable state. |
+| **Function** | **Computed / Effect** | Creates a derived value that tracks dependencies. |
+
+---
+
+## 2. Signal (State)
+
+A **Signal** is a "box" that holds a value. It provides a getter/setter function to interact with that value.
+
+* **When to use:** For data that changes over time (counters, user input, toggle states, API data).
+* **Syntax:** `const $state = $(initialValue);`
+
+### Example:
+```javascript
+const $name = $("Alice");
+
+// Read the value (Getter)
+console.log($name()); // "Alice"
+
+// Update the value (Setter)
+$name("Bob"); 
+
+// Update based on previous value
+$name(current => current + " Smith");
+```
+
+---
+
+## 3. Computed (Derived State)
+
+When you pass a **function** to `$( )` that **returns a value**, SigPro creates a **Computed Signal**. It automatically tracks which signals are used inside it and re-runs only when they change.
+
+* **When to use:** For values that depend on other signals (totals, filtered lists, formatted strings).
+* **Syntax:** `const $derived = $(() => logic);`
+
+### Example:
+```javascript
+const $price = $(100);
+const $qty = $(2);
+
+// Automatically tracks $price and $qty
+const $total = $(() => $price() * $qty());
+
+console.log($total()); // 200
+
+$qty(3); // $total updates to 300 automatically
+```
+
+---
+
+## 4. Effects (Side Effects)
+
+An **Effect** is a function passed to `$( )` that **does not return a value** (or returns `undefined`). SigPro treats this as a subscription that performs an action whenever its dependencies change.
+
+* **When to use:** For DOM manipulations, logging, or syncing with external APIs (LocalStorage, Fetch).
+* **Syntax:** `$(() => { action });`
+
+### Example:
+```javascript
+const $theme = $("light");
+
+// This effect runs every time $theme changes
+$(() => {
+  document.body.className = $theme();
+  console.log("Theme updated to:", $theme());
+});
+
+$theme("dark"); // Logs: Theme updated to: dark
+```
+
+---
+
+## 5. Summary Table: Usage Guide
+
+| Primitive | Logic Type | Returns Value? | Typical Use Case |
+| :--- | :--- | :--- | :--- |
+| **Signal** | Static | Yes (Mutable) | `const $user = $("Guest")` |
+| **Computed** | Read-only | Yes (Automatic) | `const $isLoggedIn = $(() => $user() !== "Guest")` |
+| **Effect** | Imperative | No | `$(() => localStorage.setItem('user', $user()))` |
+
+
+
+---
+
+## 💡 Pro Tip: Naming Convention
+In SigPro, we use the **`$` prefix** (e.g., `$count`) for variables that hold a reactive function. This makes it easy to distinguish between a standard variable and a reactive one at a glance:
+
+```javascript
+let count = 0;   // Static
+const $count = $(0); // Reactive (Function)
+```