diff --git a/README.md b/README.md
index 3661370..5a8249b 100644
--- 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
```
-
-
-
-explainthisrepo .
-explainthisrepo ./path/to/directory
-explainthisrepo ./path/to/file.py
-explainthisrepo owner/repo/path/to/file.py
-explainthisrepo owner/repo/path/to/directory
-
-
-
-
-Or without install:
+#### .NET
```bash
-npx explainthisrepo owner/repo
+dotnet tool install -g ExplainThisRepo
```
-
-
-
-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
-
-
-
-
-### 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:
-
-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
-```
-
+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
new file mode 100644
index 0000000..bdcacfc
--- /dev/null
+++ 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
+```
+
+
+
+
+explainthisrepo .
+explainthisrepo ./path/to/directory
+explainthisrepo ./path/to/file.py
+explainthisrepo owner/repo/path/to/file.py
+explainthisrepo owner/repo/path/to/directory
+
+
+
+
+Or without install:
+
+```bash
+npx explainthisrepo owner/repo
+```
+
+
+
+
+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
+
+
+
+
+### 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
+```
diff --git a/docs/TERMUX.md b/docs/TERMUX.md
new file mode 100644
index 0000000..a236477
--- /dev/null
+++ b/docs/TERMUX.md
@@ -0,0 +1,42 @@
+# Termux (Android) setup notes
+
+ExplainThisRepo supports running inside the Termux environments on Android devices
+
+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)
+
+If you do not want to modify PATH, you can run ExplainThisRepo as a module:
+
+```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
+```
\ No newline at end of file