JacksonFergusonDev
diff --git a/‎README.md‎
Lines changed: 44 additions & 23 deletions b/‎README.md‎
Lines changed: 44 additions & 23 deletions
diff --git a/‎src/README.md‎
Lines changed: 24 additions & 20 deletions b/‎src/README.md‎
Lines changed: 24 additions & 20 deletions
@@ -12,7 +12,8 @@
 >
 > **Git Pulsar decouples them. It is a background daemon that provides high-frequency, out-of-band state capture, ensuring your work is immutable and recoverable without polluting your project history.**
 
-### 📡 The Mission: Decoupling Signal from Noise
+## 📡 The Mission: Decoupling Signal from Noise
+
 In a typical workflow, developers are forced to make "WIP" commits just to switch machines or save their progress. This introduces **entropy** into the commit log, requiring complex interactive rebases to clean up later.
 
 **Git Pulsar** treats the working directory state as a continuous stream of data. It captures this "noise" in a dedicated namespace (`refs/heads/wip/...`), keeping your primary branch purely focused on "signal" (logical units of work).
@@ -28,21 +29,24 @@ In a typical workflow, developers are forced to make "WIP" commits just to switc
 
 ---
 
-### ⚙️ Engineering Philosophy: Non-Blocking Determinism
+## ⚙️ Engineering Philosophy: Non-Blocking Determinism
 
 This system is designed to operate safely alongside standard Git commands without race conditions or index locking.
 
-#### 1. Out-of-Band Indexing (The "Shadow" Index)
+### 1. Out-of-Band Indexing (The "Shadow" Index)
+
 Most autosave tools aggressively run `git add .`, which destroys the user's carefully staged partial commits.
 * **The Invariant:** The user's `.git/index` must never be touched by the daemon.
 * **The Implementation:** Pulsar sets the `GIT_INDEX_FILE` environment variable to a temporary location (`.git/pulsar_index`). It constructs the tree object using low-level plumbing commands (`git write-tree`), bypassing the porcelain entirely. This ensures **Zero-Interference** with your active workflow.
 
-#### 2. Distributed State Reconciliation (The "Zipper" Graph)
+### 2. Distributed State Reconciliation (The "Zipper" Graph)
+
 In a distributed environment (Laptop ↔ Desktop), state drift is inevitable.
 * **The Mechanism:** Pulsar maintains a separate refspec for each machine ID.
 * **The Topology:** When you run `git pulsar finalize`, the engine performs an **Octopus Merge**, traversing the DAG (Directed Acyclic Graph) of all machine streams and squashing them into a single, clean commit on `main`.
 
-#### 3. Fault Tolerance
+### 3. Fault Tolerance
+
 * **The Problem:** Laptops die. SSH connections drop.
 * **The Solution:** By decoupling commits from pushes, Pulsar can capture local state every few minutes while conserving battery by pushing to the remote at a lower frequency (e.g., hourly). This guarantees that the **Mean Time To Recovery (MTTR)** is minimized regardless of network availability or hardware failure.
 
@@ -52,20 +56,22 @@ In a distributed environment (Laptop ↔ Desktop), state drift is inevitable.
 
 * **Decoupled Cycles:** Independent intervals for local commits and remote pushes. Save your battery while staying protected.
 * **Smart Identity:** Automatically detects naming collisions with other devices on the remote, ensuring unique backup streams for every machine.
+* **Roaming Radar:** The background daemon actively polls for topological drift, firing a cross-platform OS notification if another machine leapfrogs your local session so you can `sync` before conflicts arise.
 * **Out-of-Band Indexing:** Backups are stored in a configured namespace (default: `refs/heads/wip/pulsar/...`). Your `git status`, `git branch`, and `git log` remain completely clean.
 * **Distributed Sessions:** Hop between machines. Pulsar tracks sessions per device and lets you `sync` to pick up exactly where you left off.
 * **State-Aware Diagnostics:** The `doctor` command correlates transient log events with active system health to prevent alert fatigue, and proactively scans for pipeline blockers like strict git hooks or broken `systemd` configurations.
 * **Zero-Interference:**
-    * Uses a temporary index so it never messes up your partial `git add`.
-    * Detects if you are rebasing or merging and waits for you to finish.
-    * Prevents accidental upload of large binaries (configurable threshold).
+  * Uses a temporary index so it never messes up your partial `git add`.
+  * Detects if you are rebasing or merging and waits for you to finish.
+  * Prevents accidental upload of large binaries (configurable threshold).
 * **Cascading Config:** Settings are merged from global defaults, `~/.config/git-pulsar/config.toml`, and local `pulsar.toml` or `pyproject.toml` files.
 
 ---
 
 ## 📦 Installation
 
 ### macOS
+
 Install via Homebrew. This automatically manages the background service.
 
 ```bash
@@ -75,6 +81,7 @@ brew services start git-pulsar
 ```
 
 ### Linux / Generic
+
 Install via `uv` (or `pipx`) and use the built-in service manager to register the systemd timer.
 
 ```bash
@@ -90,6 +97,7 @@ git pulsar install-service --interval 300
 Pulsar is designed to feel like a native git command.
 
 ### 1. Initialize & Identify
+
 Navigate to your project. The first time you run Pulsar, it will register the repo, **check for naming collisions**, and start the background protection loop.
 
 ```bash
@@ -99,15 +107,18 @@ git pulsar
 *The daemon will now silently snapshot your work based on your configured intervals.*
 
 ### 2. Configure Your Intensity
+
 Need high-frequency protection for a critical project? Set a preset or fine-tune the intervals in your project root.
 
-**pulsar.toml**
+#### pulsar.toml
+
 ```toml
 [daemon]
 preset = "paranoid"  # 5min commits, 5min pushes
 ```
 
 ### 3. The "Session Handoff" (Sync)
+
 You worked on your **Desktop** all night but forgot to push manually. You open your **Laptop** at class.
 
 ```bash
@@ -116,6 +127,7 @@ git pulsar sync
 *Pulsar checks the remote, finds the newer session from `desktop`, and fast-forwards your working directory to match it.*
 
 ### 4. Restore a File
+
 Mess up a script? Grab the version from your last shadow commit.
 
 ```bash
@@ -124,6 +136,7 @@ git pulsar restore src/main.py
 ```
 
 ### 5. Finalize Your Work
+
 When you are ready to submit or merge to `main`:
 
 ```bash
@@ -143,17 +156,18 @@ git pulsar --env
 
 This bootstraps the current directory with:
 
-- **uv:** Initializes a project with fast package management and Python 3.12+ pinning.
+* **uv:** Initializes a project with fast package management and Python 3.12+ pinning.
 
-- **direnv:** Creates an .envrc for auto-activating virtual environments and hooking into the shell.
+* **direnv:** Creates an .envrc for auto-activating virtual environments and hooking into the shell.
 
-- **VS Code:** Generates a .vscode/settings.json pre-configured to exclude build artifacts and use the local venv.
+* **VS Code:** Generates a .vscode/settings.json pre-configured to exclude build artifacts and use the local venv.
 
 ---
 
 ## 🛠 Command Reference
 
 ### Backup Management
+
 | Command | Description |
 | :--- | :--- |
 | `git pulsar` | **Default.** Registers the current repo and ensures the daemon is watching it. |
@@ -164,6 +178,7 @@ This bootstraps the current directory with:
 | `git pulsar finalize` | Squash-merge all backup streams into `main`. |
 
 ### Repository Control
+
 | Command | Description |
 | :--- | :--- |
 | `git pulsar status` | Show detailed daemon state and repository-specific commit/push history. |
@@ -175,13 +190,15 @@ This bootstraps the current directory with:
 | `git pulsar ignore <glob>` | Add a pattern to `.gitignore` (and untrack it if needed). |
 
 ### Maintenance
+
 | Command | Description |
 | :--- | :--- |
 | `git pulsar doctor` | Run state-aware diagnostics (logs, repo health, drift detection, hook interference) and clean up the registry. |
 | `git pulsar prune` | Delete old backup history (>30 days). Runs automatically weekly. |
 | `git pulsar log` | View recent log history (last 1000 lines) and tail new entries. |
 
 ### Service
+
 | Command | Description |
 | :--- | :--- |
 | `git pulsar install-service` | Register the background daemon (LaunchAgent/Systemd). |
@@ -194,14 +211,16 @@ This bootstraps the current directory with:
 Settings cascade from Global → Local. Local list options (like `ignore`) append to global ones.
 
 ### Options
+
 | Section | Key | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `daemon` | `preset` | `None` | Use `paranoid`, `aggressive`, `balanced`, or `lazy`. |
 | `daemon` | `commit_interval` | `600` | Seconds between local state captures. |
 | `daemon` | `push_interval` | `3600` | Seconds between remote pushes. |
-| `limits` | `large_file_threshold`| `100MB` | Max file size before aborting a backup. |
+| `limits` | `large_file_threshold` | `100MB` | Max file size before aborting a backup. |
 
 ### Example `~/.config/git-pulsar/config.toml`
+
 ```toml
 [daemon]
 preset = "balanced"
@@ -219,26 +238,28 @@ ignore = ["*.tmp", "node_modules/"]
 
 *Focus: Turning the tool from a blind script into a helpful partner that negotiates with you.*
 
-- [ ] **Smart Restore:** Replace hard failures on "dirty" files with a negotiation menu (Overwrite / View Diff / Cancel).
-- [ ] **Pre-Flight Checklists:** Display a summary table of incoming changes (machines, timestamps, file counts) before running destructive commands like `finalize`.
-- [ ] **Active Doctor:** Upgrade `git pulsar doctor` to not just diagnose issues (like stopped daemons), but offer to auto-fix them interactively.
+* [ ] **Smart Restore:** Replace hard failures on "dirty" files with a negotiation menu (Overwrite / View Diff / Cancel).
+* [ ] **Pre-Flight Checklists:** Display a summary table of incoming changes (machines, timestamps, file counts) before running destructive commands like `finalize`.
+* [ ] **Active Doctor:** Upgrade `git pulsar doctor` to not just diagnose issues (like stopped daemons), but offer to auto-fix them interactively.
 
 ### Phase 2: "Deep Thought" (Context & Intelligence)
 
 *Focus: Leveraging data to make the tool feel alive and aware of your workflow.*
 
-- [ ] **Semantic Shadow Logs:** Replace generic "Shadow backup" messages with auto-generated summaries (e.g., `backup: modified daemon.py (+15 lines)`).
-- [x] **Roaming Radar:** Proactively detect if a different machine has pushed newer work to the same branch and notify the user to `sync`.
-- [ ] **Decaying Retention:** Implement "Grandfather-Father-Son" pruning (keep all hourly backups for 24h, then daily summaries) to balance safety with disk space.
+* [ ] **Semantic Shadow Logs:** Replace generic "Shadow backup" messages with auto-generated summaries (e.g., `backup: modified daemon.py (+15 lines)`).
+* [x] **Roaming Radar:** Proactively detect if a different machine has pushed newer work to the same branch and notify the user to `sync`.
+* [ ] **Decaying Retention:** Implement "Grandfather-Father-Son" pruning (keep all hourly backups for 24h, then daily summaries) to balance safety with disk space.
 
 ### Phase 3: The "TUI" Experience (Visuals)
+
 *Focus: Making the invisible backup history tangible and explorable.*
-- [ ] **Time Machine UI:** A terminal-based visual browser for `git pulsar restore` that lets you scroll through file history and view side-by-side diffs.
-- [ ] **Universal Bootstrap:** Expand `git pulsar --env` to support Linux (apt/dnf) environments alongside macOS.
+* [ ] **Time Machine UI:** A terminal-based visual browser for `git pulsar restore` that lets you scroll through file history and view side-by-side diffs.
+* [ ] **Universal Bootstrap:** Expand `git pulsar --env` to support Linux (apt/dnf) environments alongside macOS.
 
 ### Future Horizons
-- [ ] **End-to-End Encryption:** Optional GPG encryption for shadow commits.
-- [ ] **Windows Support:** Native support for PowerShell and Task Scheduler.
+
+* [ ] **End-to-End Encryption:** Optional GPG encryption for shadow commits.
+* [ ] **Windows Support:** Native support for PowerShell and Task Scheduler.
 
 ---
 
 
@@ -5,41 +5,45 @@ The `src/` directory contains the package source code. The architecture strictly
 ## Module Map
 
 ### 1. The Core Loop (State Management)
+
 * **`git_pulsar/daemon.py`**: The background process.
-    * **Role:** The "Heartbeat." It wakes up, checks system constraints (Battery, CPU Load), and triggers the backup logic.
-    * **Logic:** Decouples "Saving" (Commit) from "Publishing" (Push) using independent intervals to optimize for battery life.
-    * **Safety:** Implements `GIT_INDEX_FILE` isolation to ensure it never locks or corrupts the user's active git index.
+  * **Role:** The "Heartbeat." It wakes up, checks system constraints (Battery, CPU Load), and triggers the backup logic.
+  * **Logic:** Decouples "Saving" (Commit) from "Publishing" (Push) using independent intervals to optimize for battery life. Incorporates the "Roaming Radar" to poll for remote drift asynchronously.
+  * **Safety:** Implements `GIT_INDEX_FILE` isolation to ensure it never locks or corrupts the user's active git index.
 * **`git_pulsar/ops.py`**: High-level Business Logic.
-    * **Role:** The "Controller." It orchestrates complex multi-step operations like `finalize` (Octopus Merges) and `restore`.
-    * **Logic:** Calculates the "Zipper Graph" topology to merge shadow commits back into the main branch.
+  * **Role:** The "Controller." It orchestrates complex multi-step operations like `finalize` (Octopus Merges), `restore`, and drift detection.
+  * **Logic:** Calculates the "Zipper Graph" topology to merge shadow commits back into the main branch, and manages atomic file I/O for cross-process state tracking.
 * **`git_pulsar/config.py`**: Configuration Engine.
-    * **Role:** The "Source of Truth."
-    * **Logic:** Implements a cascading hierarchy (Defaults → Global → Local) to merge settings from `~/.config/git-pulsar/config.toml` and project-level `pulsar.toml` or `pyproject.toml`.
+  * **Role:** The "Source of Truth."
+  * **Logic:** Implements a cascading hierarchy (Defaults → Global → Local) to merge settings from `~/.config/git-pulsar/config.toml` and project-level `pulsar.toml` or `pyproject.toml`.
 
 ### 2. The Abstraction Layer (Plumbing)
+
 * **`git_pulsar/git_wrapper.py`**: The Git Interface.
-    * **Role:** A strict wrapper around `subprocess`.
-    * **Philosophy:** **No Porcelain.** This module primarily uses git *plumbing* commands (`write-tree`, `commit-tree`, `update-ref`) rather than user-facing commands (`commit`, `add`) to ensure deterministic behavior.
+  * **Role:** A strict wrapper around `subprocess`.
+  * **Philosophy:** **No Porcelain.** This module primarily uses git *plumbing* commands (`write-tree`, `commit-tree`, `update-ref`) rather than user-facing commands (`commit`, `add`) to ensure deterministic behavior.
 * **`git_pulsar/system.py`**: OS Abstraction.
-    * **Role:** Identity & Environment.
-    * **Logic:** Handles the chaos of cross-platform identity (mapping `IOPlatformUUID` on macOS vs `/etc/machine-id` on Linux) to ensure stable "Roaming Profiles."
+  * **Role:** Identity & Environment.
+  * **Logic:** Handles the chaos of cross-platform identity (mapping `IOPlatformUUID` on macOS vs `/etc/machine-id` on Linux) to ensure stable "Roaming Profiles."
 
 ### 3. Service Management (Lifecycle)
+
 * **`git_pulsar/service.py`**: The Installation Engine.
-    * **Role:** Interface with the host init system.
-    * **Logic:** Generates and registers `systemd` user timers (Linux) or instructions for `launchd` (macOS/Homebrew).
+  * **Role:** Interface with the host init system.
+  * **Logic:** Generates and registers `systemd` user timers (Linux) or instructions for `launchd` (macOS/Homebrew).
 
 ### 4. The Interface
+
 * **`git_pulsar/cli.py`**: The User Entry Point & Diagnostic Engine.
-    * **Role:** Argument parsing, UI rendering, and system health evaluation.
-    * **Logic:** Uses `rich` for terminal visualization. Beyond routing subcommands to `ops.py` and `daemon.py`, it houses the `doctor` logic. It correlates repository state against transient event logs, detects topological drift across distributed sessions, and scans for host-environment pipeline blockers (e.g., strict git hooks, missing `systemd` linger).
+  * **Role:** Argument parsing, UI rendering, and system health evaluation.
+  * **Logic:** Uses `rich` for terminal visualization. Beyond routing subcommands to `ops.py` and `daemon.py`, it presents the `doctor` diagnostics. It correlates repository state against transient event logs, and relies on `ops.py` to evaluate topological drift across distributed sessions and scan for host-environment pipeline blockers (e.g., strict git hooks, missing `systemd` linger).
 
 ---
 
 ## Key Invariants
 
-1.  **Index Isolation:** The `daemon` module MUST ALWAYS set `os.environ["GIT_INDEX_FILE"]` to a temporary path before performing write operations.
-2.  **Zero-Destruction:** The `prune` logic in `ops.py` relies on strictly namespaced refspecs (`refs/heads/wip/pulsar/...`) and never touches standard heads.
-3.  **Identity Stability:** The `system` module guarantees that a Machine ID persists across reboots, preventing "Split Brain" backup histories.
-4.  **Configuration Precedence:** Local project configuration MUST always override global user settings to ensure repo-specific constraints (e.g., large file limits) are respected.
-5.  **State Over Events:** The diagnostic engine (`cli.py`) MUST prioritize current repository and environmental state over historical log events to prevent alert fatigue from self-healing anomalies.
+1. **Index Isolation:** The `daemon` module MUST ALWAYS set `os.environ["GIT_INDEX_FILE"]` to a temporary path before performing write operations.
+2. **Zero-Destruction:** The `prune` logic in `ops.py` relies on strictly namespaced refspecs (`refs/heads/wip/pulsar/...`) and never touches standard heads.
+3. **Identity Stability:** The `system` module guarantees that a Machine ID persists across reboots, preventing "Split Brain" backup histories.
+4. **Configuration Precedence:** Local project configuration MUST always override global user settings to ensure repo-specific constraints (e.g., large file limits) are respected.
+5. **State Over Events:** The diagnostic engine (`cli.py`) MUST prioritize current repository and environmental state over historical log events to prevent alert fatigue from self-healing anomalies.