calchiwo · calchiwo · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/README.md b/README.md
@@ -31,152 +31,57 @@ ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests,
 
 ## Installation
 
-### Option 1: install with pip (Python source version):
+ExplainThisRepo supports multiple installation methods:
 
-Requirements: Python 3.9+
+- pip (Python package)
+- npm (prebuilt native binaries)
+- .NET global tool
+- standalone binaries
+
+### Quick install
+
+#### pip
 
 ```bash
 pip install explainthisrepo
-explainthisrepo owner/repo
-
-# explainthisrepo .
-# explainthisrepo ./path/to/directory
-# explainthisrepo ./path/to/file.py
-# explainthisrepo owner/repo/path/to/file.py
-# explainthisrepo owner/repo/path/to/directory
 ```
 
 Alternatively,
 
 ```bash
 pipx install explainthisrepo
-explainthisrepo owner/repo
-```
-
-After installation, use any of the available commands:
-
-```bash
-explainthisrepo owner/repo
-explain-this-repo owner/repo
-etr owner/repo
 ```
 
-To install support for specific models:
-
-```bash
-pip install explainthisrepo[gemini]
-pip install explainthisrepo[openai]
-pip install explainthisrepo[anthropic]
-pip install explainthisrepo[groq]
-```
-
-Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
-
-### Option 2: Install with npm (prebuilt binary, no Python install required)
-
-Install globally and use forever:
+#### npm
 
 ```bash
 npm install -g explainthisrepo
-explainthisrepo owner/repo
 ```
 
-<details>
-<pre>
-<code>
-explainthisrepo .
-explainthisrepo ./path/to/directory
-explainthisrepo ./path/to/file.py
-explainthisrepo owner/repo/path/to/file.py
-explainthisrepo owner/repo/path/to/directory
-</code>
-</pre>
-</details>
-
-Or without install:
+#### .NET
 
 ```bash
-npx explainthisrepo owner/repo
+dotnet tool install -g ExplainThisRepo
 ```
 
-<details>
-<pre>
-<code>
-npx explainthisrepo .
-npx explainthisrepo ./path/to/directory
-npx explainthisrepo ./path/to/file.py
-npx explainthisrepo owner/repo/path/to/file.py
-npx explainthisrepo owner/repo/path/to/directory
-</code>
-</pre>
-</details>
-
-### Option 3: Install with .NET (C# Global Tool)
-
-Requirements: .NET 8, 9, or 10:
+#### Run
 
 ```bash
-dotnet tool install -g explainthisrepo
 explainthisrepo owner/repo
-
-# dotnet tool install -g explainthisrepo
-# explainthisrepo .
 ```
 
-## How it works
-
-ExplainThisRepo has one core engine and multiple distribution layers.
-
-- Python is the source of truth for analysis, prompts, providers, and output
-- npm ships the Node launcher plus prebuilt native binaries
-- .NET ships the same native binary as a global tool and publishes to NuGet
-- GitHub Releases publish the standalone binaries
-
-The Node and .NET layers are launchers only. They detect the current platform, locate the matching bundled binary, and execute it with the user’s arguments.
-
-The same native binary is what actually performs the work.
-
-## Distribution model
-
-ExplainThisRepo is shipped in multiple ways:
-
-- `pip` for Python users
-- `npm` for Node users
-- `dotnet tool` for .NET users
-- standalone binaries for direct download
-
-All of them run the same core Python engine compiled into native binaries.
-
-### Option 4: Download standalone binary
-
-Prebuilt standalone binaries are available for macOS, Linux, and Windows.
-
-> Standalone binaries require no Python or Node installation and run as a single executable.
-
-Download the latest release: [ExplainThisRepo latest releases](https://github.com/calchiwo/ExplainThisRepo/releases/latest)
-
-Or install directly:
-<details>
-macOS
+After installation, use any of the available commands:
 
 ```bash
-curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo
-chmod +x explainthisrepo
+explainthisrepo owner/repo
+explain-this-repo owner/repo
+etr owner/repo
 ```
 
-Linux
-
-```bash
-curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo
-chmod +x explainthisrepo
-```
+Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
 
-Windows (PowerShell)
 
-```powershell
-curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe
-```
-</details>
+For full installation instructions, platform-specific notes, standalone binaries, Termux support, and advanced setup: [docs/INSTALLATION.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/INSTALLATION.md)
 
 ## Configuration
 
@@ -198,6 +103,15 @@ explainthisrepo init
 
 > For details about how initialization works, see [docs/INIT.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/INIT.md).
 
+To install support for specific models:
+
+```bash
+pip install explainthisrepo[gemini]
+pip install explainthisrepo[openai]
+pip install explainthisrepo[anthropic]
+pip install explainthisrepo[groq]
+```
+
 ## GitHub token Access (Private Repos & Rate Limits)
 
 ExplainThisRepo supports GitHub authentication for:
@@ -534,46 +448,11 @@ Use the `--doctor` flag to verify the environment, network connectivity, and API
 explainthisrepo --doctor
 ```
 
-## Termux (Android) install notes
-
-Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`.
-
-However, it's recommended you install using:
-
-```bash
-pip install --user -U explainthisrepo
-```
-
-Make sure your user bin directory is on your PATH:
-
-```bash
-export PATH="$HOME/.local/bin:$PATH"
-```
-
-> Tip: Add the PATH export to your `~/.bashrc` or `~/.zshrc` so it persists.
-
-### Alternative (No PATH changes)
+## Termux (Android)
 
-If you do not want to modify PATH, you can run ExplainThisRepo as a module:
+ExplainThisRepo supports Termux on Android.
 
-```bash
-python -m explain_this_repo owner/repo
-```
-
-### Gemini support on Termux
-
-Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install:
-
-```bash
-pip install --user -U "explainthisrepo[gemini]"
-```
-
-For mobile environments like Termux where compiling Python dependencies can be slow,
-you can also run ExplainThisRepo using the Node.js version:
-
-```bash
-npx explainthisrepo owner/repo
-```
+For installation notes, PATH setup, Gemini support, and mobile-specific recommendations: see [docs/TERMUX.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/TERMUX.md)
 
 ## Philosophy
 

diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
@@ -0,0 +1,147 @@
+# Installation
+
+### Option 1: install with pip (Python source version):
+
+Requirements: Python 3.9+
+
+```bash
+pip install explainthisrepo
+explainthisrepo owner/repo
+
+# explainthisrepo .
+# explainthisrepo ./path/to/directory
+# explainthisrepo ./path/to/file.py
+# explainthisrepo owner/repo/path/to/file.py
+# explainthisrepo owner/repo/path/to/directory
+```
+
+Alternatively,
+
+```bash
+pipx install explainthisrepo
+explainthisrepo owner/repo
+```
+
+After installation, use any of the available commands:
+
+```bash
+explainthisrepo owner/repo
+explain-this-repo owner/repo
+etr owner/repo
+```
+
+To install support for specific models:
+
+```bash
+pip install explainthisrepo[gemini]
+pip install explainthisrepo[openai]
+pip install explainthisrepo[anthropic]
+pip install explainthisrepo[groq]
+```
+
+Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`, `torvalds/linux`).
+
+### Option 2: Install with npm (prebuilt binary, no Python install required)
+
+Install globally and use forever:
+
+```bash
+npm install -g explainthisrepo
+explainthisrepo owner/repo
+```
+
+<details>
+<pre>
+<code>
+explainthisrepo .
+explainthisrepo ./path/to/directory
+explainthisrepo ./path/to/file.py
+explainthisrepo owner/repo/path/to/file.py
+explainthisrepo owner/repo/path/to/directory
+</code>
+</pre>
+</details>
+
+Or without install:
+
+```bash
+npx explainthisrepo owner/repo
+```
+
+<details>
+<pre>
+<code>
+npx explainthisrepo .
+npx explainthisrepo ./path/to/directory
+npx explainthisrepo ./path/to/file.py
+npx explainthisrepo owner/repo/path/to/file.py
+npx explainthisrepo owner/repo/path/to/directory
+</code>
+</pre>
+</details>
+
+### Option 3: Install with .NET (C# Global Tool)
+
+Requirements: .NET 8, 9, or 10:
+
+```bash
+dotnet tool install -g ExplainThisRepo
+explainthisrepo owner/repo
+
+# dotnet tool install -g ExplainThisRepo
+# explainthisrepo .
+```
+
+## How it works
+
+ExplainThisRepo has one core engine and multiple distribution layers.
+
+- Python is the source of truth for analysis, prompts, providers, and output
+- npm ships the Node launcher plus prebuilt native binaries
+- .NET ships the same native binary as a global tool and publishes to NuGet
+- GitHub Releases publish the standalone binaries
+
+The Node and .NET layers are launchers only. They detect the current platform, locate the matching bundled binary, and execute it with the user’s arguments.
+
+The same native binary is what actually performs the work.
+
+## Distribution model
+
+ExplainThisRepo can be installed in multiple ways:
+
+- `pip` for Python users
+- `npm` for Node users
+- `dotnet tool` for .NET users
+- standalone binaries for direct download
+
+All of them run the same core Python engine compiled into native binaries.
+
+### Option 4: Download standalone binary
+
+Prebuilt standalone binaries are available for macOS, Linux, and Windows.
+
+> Standalone binaries require no Python or Node installation and run as a single executable.
+
+Download the latest release: [ExplainThisRepo latest releases](https://github.com/calchiwo/ExplainThisRepo/releases/latest)
+
+Or install directly:
+
+macOS
+
+```bash
+curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo
+chmod +x explainthisrepo
+```
+
+Linux
+
+```bash
+curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo
+chmod +x explainthisrepo
+```
+
+Windows (PowerShell)
+
+```powershell
+curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe
+```