From a11f9e8a9496e95c83e1c4fb128b5bbafe5d4513 Mon Sep 17 00:00:00 2001
From: Marco D'Aleo <m.daleo404@gmail.com>
Date: Mon, 10 Nov 2025 19:10:34 +0000
Subject: [PATCH] Populate README, add poetry.lock

---
 README.md   | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 poetry.lock |  7 ++++
 2 files changed, 101 insertions(+)
 create mode 100644 poetry.lock

diff --git a/README.md b/README.md
index 123750f..116ffb3 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,95 @@
 # mirro
+
+**mirro** is a tiny safety-first editing wrapper for text files.
+You edit a temporary file, **mirro** detects whether anything changed, and if it did, it saves a backup of the original before writing your changes.
+
+
+## Why mirro?
+
+Well... have you ever been in the _“ugh, I forgot to back this up first”_ situation? 
+
+No?
+
+Stop lying... (:))
+
+**mirro** gives you a built-in safety net:
+
+- never edits the real file directly
+
+- detects whether the edit actually changed content
+
+- creates a timestamped backup only when changes occurred
+
+- clearly labels backups so you know exactly what they came from
+
+- respects the user’s `$EDITOR` when possible
+
+- requires `sudo` only when actually needed
+
+It’s simple, predictable, and hard to misuse.
+
+I mean... the only thing you need to remember is _to use it_.
+
+## How it works
+
+**mirro** reads the original file (or pre-populates new files with a friendly message).
+
+It writes that content into a temporary file.
+
+It launches your `$EDITOR` to edit the temp file.
+
+When the editor closes, **mirro** compares old vs new.
+
+If nothing changed:
+```
+file hasn't changed
+```
+
+If changed:
+```
+file changed; original backed up at: ~/.local/share/mirro/ (or /root/.local/share/mirro/ under sudo)
+```
+
+Backed up files include a header:
+```
+# ---------------------------------------------
+# mirro backup
+# Original file: /path/to/whatever.conf
+# Timestamp: 2025-11-10 17:44:00 UTC
+# ---------------------------------------------
+```
+
+So you never lose track of the original location.
+
+### Backup directory
+
+By default all the backups will be stored at:
+```
+~/.local/share/mirro/
+```
+so under `sudo`:
+```
+/root/.local/share/mirro/
+```
+
+Backups are named like:
+```
+filename.ext.orig.20251110T174400.bak
+```
+
+## Installation
+
+**NOTE**: To use mirro with sudo, the path to mirro must be in the $PATH seen by root.
+Either install mirro as root (preferred), use sudo -E mirro, or add the $PATH to /etc/sudoers using its Defaults secure_path parameter.
+
+Install via PyPI (preferred):
+```
+pip install mirro
+```
+
+Or clone the repo and install locally:
+```
+git clone https://github.com/mdaleo404/mirro.git
+cd mirro/
+poetry install
+```
diff --git a/poetry.lock b/poetry.lock
new file mode 100644
index 0000000..e9d42af
--- /dev/null
+++ b/poetry.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Poetry 1.8.4 and should not be changed by hand.
+package = []
+
+[metadata]
+lock-version = "2.0"
+python-versions = "^3.13"
+content-hash = "f01b553f3895e558c34b4f10542e05acdef39bf0527c8090bd136d914dc73f94"