diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..d3c712a
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,137 @@
+# WHERE - Universal System File and Package Mapper
+
+A command-line tool that provides comprehensive observability into your Linux system's package installations and file ownership. Built in Rust for performance and reliability.
+
+## Features
+
+- **Universal Package Manager Support** - Works with DNF, APT, Flatpak, Snap, and more
+- **File Ownership Tracking** - Instantly identify which package owns any file
+- **Package Tree Visualization** - See all files installed by a package in tree format
+- **Cross-Distribution Compatibility** - Single tool that works across Linux distributions
+- **High Performance** - Memory-mapped binary format for fast queries
+
+## Installation
+
+```bash
+git clone <repository-url>
+cd where
+cargo build --release
+```
+
+## Usage
+
+### Show Package File Tree
+Display all files installed by a specific package in a hierarchical tree structure:
+
+```bash
+# Show files installed by bash package
+cargo run -- tree --package bash
+
+# Show trees for first 5 packages (demo mode)
+cargo run -- tree
+```
+
+### Package Information
+Get detailed information about a specific package:
+
+```bash
+# Show package details and file tree
+cargo run -- package bash
+```
+
+### File Ownership
+Find out which package owns a specific file:
+
+```bash
+# Check who owns /usr/bin/bash
+cargo run -- file /usr/bin/bash
+```
+
+### List All Packages
+Display all installed packages:
+
+```bash
+# List all packages
+cargo run -- packages
+```
+
+### Find Files
+Search for files within packages:
+
+```bash
+# Find all files in bash package
+cargo run -- find --package bash
+```
+
+## Example Output
+
+### Package Tree
+```
+bash 5.2.15-6.fc41
+├── usr/
+│   ├── bin/
+│   │   └── bash
+│   └── share/
+│       ├── doc/
+│       │   └── bash/
+│       │       ├── CHANGES
+│       │       ├── README
+│       │       └── NEWS
+│       └── man/
+│           └── man1/
+│               └── bash.1.gz
+└── etc/
+    └── skel/
+        └── .bashrc
+```
+
+### File Ownership
+```
+/usr/bin/bash is owned by package: bash
+```
+
+## Architecture
+
+The tool is designed with a modular architecture supporting multiple package managers:
+
+- **Package Manager Abstraction** - Common interface for all package managers
+- **Binary Database Format** - High-performance storage for file metadata
+- **CLI Interface** - Clean command-line interface built with Clap
+- **Tree Visualization** - Hierarchical display of package contents
+
+## Supported Package Managers
+
+- ✅ **DNF/RPM** (Fedora, RHEL, CentOS)
+- 🚧 **APT** (Debian, Ubuntu) - Coming Soon
+- 🚧 **Flatpak** - Coming Soon  
+- 🚧 **Snap** - Coming Soon
+- 🚧 **Pacman** (Arch Linux) - Coming Soon
+
+## Development Philosophy
+
+This tool is part of the **IntentOS** project, focused on creating systems where every component has clear provenance and purpose. The core principle is "know where everything is" - eliminating the entropy and "shrapnel" that accumulates in traditional Linux installations.
+
+## Contributing
+
+Built with Rust 2021 edition. Key dependencies:
+- `clap` - Command line argument parsing
+- `memmap2` - Memory-mapped file access
+- `chrono` - Date/time handling
+
+## License
+
+[Add your license here]
+
+## Roadmap
+
+- [ ] Complete support for all major package managers
+- [ ] Real-time filesystem monitoring
+- [ ] Binary database format for fast queries
+- [ ] GUI interface
+- [ ] Integration with IntentOS package manager
+- [ ] Package installation profiles
+- [ ] System entropy analysis tools
+
+---
+
+*WHERE gives you complete visibility into your system's package installations - because you should know where everything comes from.*
\ No newline at end of file