explainthisrepo 0.25.3 → 0.26.0

package/README.md

@@ -1,6 +1,6 @@
 # ExplainThisRepo
 
-_The fastest way to understand any codebase in plain English using real project signals. Not blind AI summarization._
+_The fastest way to understand any codebase in plain English using real project signals. Not blind AI guessing._
 
 ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests, dependencies graph, file structure and high-signal files producing a clear, structured `EXPLAIN.md` that explains what the codebase actually does and how it is organized in plain English.
 
@@ -18,16 +18,19 @@ ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests,
 
 - Understand any GitHub repository in seconds
 - Derives architectural summaries from repository structure and code signals.
-Not blind AI summarization.
-- Deterministic repo signal extractor that feeds LLMs correctly
+Not blind AI guessing
+- Deterministic repo signal extractor that feeds LLMs correctly. Signals first. LLM second
 - Translates complex code structures into plain English
 - Speeds up understanding of unfamiliar codebases
 - Solves the "**garbage in, garbage out**" problem specifically for codebases
 - Extract architecture signals from configs, entrypoints, and manifests
-- Works with GitHub repositories, local directories, private repositories, individual files and monorepos
+- System map that shows you where to start, what matters and what to ignore
+- Works with GitHub repositories, Local repositories, GitHub directories, local directories, GitHub files and local files 
+- Supports private repositories and monorepos
 - Zero-cloning and remote analysis
-- Outputs the explanation to an `EXPLAIN.md` file in your current directory, prints it directly in the terminal, or a specified output file (`.txt`, `.pdf`, `.docx`)
+- Outputs the explanation to an `EXPLAIN.md` file in your current directory, prints it directly in the terminal, or a specified output file (`.txt`, `.pdf`, `.docx`, `.md`)
 - Multiple explanation modes (quick, simple, detailed)
+- Additional tools: stack detection, repo map
 
 ## Installation
 
@@ -115,8 +118,8 @@ npx explainthisrepo owner/repo
 
 ExplainThisRepo uses a hybrid architecture:
 
-- Python → core implementaion (analysis, prompts, providers, output)
-- npm → ships prebuilt native binaries (no Python required)
+- Python → core implementation (analysis, prompts, providers, output)
+- npm → launches prebuilt native binaries (no Python install required)
 - pip → installs the full Python package
 
 > The npm and pip versions run the same core engine.
@@ -185,7 +188,7 @@ Run:
 explainthisrepo init
 ```
 
-For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
+For step-by-step instructions, see [docs/GITHUB_TOKEN.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/GITHUB_TOKEN.md)
 
 ## Flag options
 
@@ -199,6 +202,8 @@ For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
 
 - `--stack` → Tech stack breakdown from repo signals
 
+- `--map` → System map for understanding a codebase before changing it
+
 - `--version` → Check installed CLI version
 
 - `--help` → Show usage guide
@@ -209,7 +214,7 @@ For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
 
 - `--output` / `-o` → Specify output file or directory (default: `EXPLAIN.md`)
 
-## Flexible Repository and Local Directory Input
+## Flexible Input Types
 
 Accepts various formats for repository input, full GitHub URLs (with or without https), `owner/repo` format, issue links, query strings, and SSH clone links
 
@@ -226,7 +231,7 @@ explainthisrepo ./path/to/directory
 explainthisrepo ./path/to/file.py
 ```
 
-All inputs are normalized internally to `owner/repo`.
+GitHub inputs are normalized internally to `owner/repo`.
 
 ## CLI aliases
 
@@ -322,6 +327,26 @@ explainthisrepo owner/repo --stack
 ```
 ![Stack detector Output](assets/stack-command-output.png)
 
+### Repo map
+
+Navigation system map for understanding unfamiliar codebases that shows you where to start, what matters and what to ignore before touching it:
+
+```bash
+explainthisrepo owner/repo --map
+explainthisrepo . --map
+```
+
+By default, repo map mode writes to `REPO_MAP.md`.
+
+The map focuses on:
+
+- where to start reading
+- the likely main flow through the project
+- important files and why they matter
+- visible architecture boundaries
+- files or folders to ignore first
+- open questions that cannot be determined from repo signals
+
 ## Local Directory Analysis
 
 ExplainThisRepo can analyze local directories directly in the terminal, using the same modes and output formats as GitHub repositories
@@ -338,6 +363,7 @@ explainthisrepo . --quick
 explainthisrepo . --simple
 explainthisrepo . --detailed
 explainthisrepo . --stack
+explainthisrepo . --map
 ```
 
 When analyzing a local directory:
@@ -351,7 +377,7 @@ This allows analysis of projects directly from the local filesystem, without req
 
 ## File Analysis
 
-ExplanThisRepo analyzes individual files directly
+ExplainThisRepo analyzes individual files directly
 
 ```bash
 explainthisrepo ./path/to/file.py
@@ -388,9 +414,11 @@ explainthisrepo owner/repo/path/to/file.py --detailed
 
 When analyzing a GitHub file:
 - The file is fetched directly via the GitHub API
-- Only valid text files are processed (binary files are rejected)
-- File size is capped to prevent unsafe or truncated analysis
+- Raw bytes are passed into a unified ingestion pipeline
+- Binary detection, decoding, and size limits are handled in one place
+- File ingestion is identical to local file analysis
 - The explanation focuses on the file’s purpose, logic, and behavior
+- This removes divergence between local and GitHub file handling
 
 Input format must be:
 
@@ -421,14 +449,10 @@ explainthisrepo owner/repo/path/to/directory --detailed
 When analyzing a GitHub directory:
 
 - Directory contents are fetched via the GitHub API
-
 - Only structure and metadata are used (no full repo fetch)
-
 - Signals include files, subdirectories, and extension distribution
-
 - The explanation focuses on the directory’s role and structure
 
-
 `--stack` is not supported for directory targets.
 
 ### Custom output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.25.3",
+  "version": "0.26.0",
   "description": "The fastest way to understand any codebase in plain English. Not blind AI summarization",
   "license": "MIT",
   "type": "module",