From 98c2cbd39573bebaa2eb750885af5d38b9280454 Mon Sep 17 00:00:00 2001
From: cairo <cairodevv@gmail.com>
Date: Wed, 4 Mar 2026 12:42:48 +1100
Subject: [PATCH] Create README.md

---
 README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..675b7bf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,94 @@
+# splain
+A command‑line tool that **explains what a shell command will do before you run it**.  
+It parses the command, inspects the filesystem, analyzes flags, pipes, globs, and redirections, and produces a clear, human‑readable explanation — without executing anything.
+
+splain acts as a safety net for your terminal, a teaching tool for shell newcomers, and a static analyzer for complex commands.
+
+---
+
+## ✨ Features
+
+- Natural‑language explanations of shell commands  
+- Filesystem simulation to detect deletes, overwrites, moves, and copies  
+- Globbing, variable expansion, pipes, and redirection analysis  
+- Deep analyzers for common commands (`rm`, `cp`, `mv`, `tar`, `grep`, `find`, etc.)  
+- Man‑page extraction for unknown commands  
+- Risk detection for destructive patterns  
+- JSON output mode for editor or script integration  
+- Zero execution — splain never runs the command  
+
+---
+
+## 🧠 Why splain exists
+
+Shell commands are powerful but easy to misread or misunderstand. A single typo can delete the wrong directory or overwrite important files. splain helps you understand commands before trusting them.
+
+It’s useful for:
+
+- learning shell commands  
+- reviewing scripts  
+- preventing mistakes  
+- understanding pipelines  
+- auditing third‑party tools  
+
+---
+
+## 🔍 How it works
+
+### Parsing
+splain parses the command into a structured representation:
+
+- program  
+- flags  
+- arguments  
+- pipes  
+- redirections  
+- globs  
+- subshells  
+- environment variables  
+
+### Filesystem inspection
+splain checks:
+
+- whether paths exist  
+- whether they’re files, directories, or symlinks  
+- permissions  
+- potential overwrites  
+- how many files a recursive command would affect  
+
+### Command analyzers
+For well‑known commands, splain includes deep semantic analyzers:
+
+- rm  
+- cp  
+- mv  
+- mkdir  
+- rmdir  
+- chmod  
+- chown  
+- tar  
+- grep  
+- find  
+- head / tail  
+- cat  
+- echo  
+
+### Unknown commands
+If splain doesn’t recognize a command, it still explains:
+
+- flag meanings (from man pages)  
+- argument types  
+- redirections  
+- pipes  
+- potential file writes or overwrites  
+
+### Explanation generation
+The structured analysis is turned into readable text or JSON.
+
+---
+
+## 🚀 Usage
+
+### Basic example
+```bash
+splain rm -rf ~/Downloads