diff --git a/README.md b/README.md
index 7c9fa43..3f26e81 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,163 @@
-# 1. Build
+# Marlin
+
+**Marlin** is a lightweight, metadata-driven file indexer you run on your own machine.
+It scans folders, stores paths and basic stats in a local SQLite database, and lets you tag
+files from the command line. Nothing leaves your computer.
+
+The goal is to build up toward a full “smart” file explorer (hierarchical tags, custom
+attributes, search, sync, etc.). This repo contains the **Sprint 0** foundation:
+
+* XDG-aware config — no hard-coded paths
+* Embedded SQLite migrations (WAL mode)
+* Fast directory scanner
+* Simple tagging tool
+* Human-readable logging via `tracing`
+
+---
+
+## How it works
+
+```text
+┌──────────────┐  scan           ┌─────────────┐
+│  your files  │ ───────────────▶│   SQLite    │
+└──────────────┘                 │  index.db   │
+        ▲  tag <pattern> <tag>   │ files tags  │
+        └────────────────────────┴─────────────┘
+```
+
+1. `marlin scan <dir>` walks the directory tree with `walkdir`, gathers size and
+   modification time, then upserts rows into `files`.
+2. `marlin tag "<glob>" <tag>` resolves the glob, looks up each file row, and inserts
+   junction rows into `file_tags`. New tag names are created on the fly.
+3. You can query the database yourself (e.g. with `sqlite3 ~/.local/share/marlin/index.db`)
+   while higher-level search commands are being built.
+
+---
+
+## Prerequisites
+
+| What             | Why                                                 |
+| ---------------- | --------------------------------------------------- |
+| **Rust** ≥ 1.77  | Build toolchain (`rustup.rs`)                       |
+| Build essentials | `gcc`, `make`, etc. for `rusqlite`’s bundled SQLite |
+
+### Windows
+
+Rust installs MSVC build tools automatically.
+SQLite is compiled from source; nothing else to set up.
+
+### macOS
+
+Install Xcode Command-Line Tools:
+
+```bash
+xcode-select --install
+```
+
+### Linux
+
+Deb-/RPM-based distros:
+
+```bash
+sudo apt install build-essential            # or
+sudo dnf groupinstall 'Development Tools'
+```
+
+---
+
+## Build & install
+
+Clone then build in release mode:
+
+```bash
+git clone https://github.com/yourname/marlin.git
+cd marlin
 cargo build --release
+```
 
-# 2. Initialise DB (idempotent)
-./target/release/marlin init
+The binary is placed at `target/release/marlin`.
+Feel free to copy it into a directory on your `PATH`, e.g.:
 
-# 3. Scan a directory
-./target/release/marlin scan ~/Pictures
+```bash
+sudo install -Dm755 target/release/marlin /usr/local/bin/marlin
+```
 
-# 4. Tag all JPEGs in Pictures
-./target/release/marlin tag "~/Pictures/**/*.jpg" vacation
+---
+
+## Quick start
+
+```bash
+# 1 - create the database (idempotent)
+marlin init
+
+# 2 - index a folder
+marlin scan ~/Pictures
+
+# 3 - add a tag to matching files
+marlin tag "~/Pictures/**/*.jpg" vacation
+```
+
+The database defaults to:
+
+```
+~/.local/share/marlin/index.db         # Linux
+~/Library/Application Support/marlin   # macOS
+%APPDATA%\\marlin\\index.db            # Windows
+```
+
+Override with an environment variable:
+
+```bash
+export MARLIN_DB_PATH=/path/to/custom.db
+```
+
+---
+
+## CLI reference
+
+```text
+USAGE:
+    marlin <COMMAND> [ARGS]
+
+COMMANDS:
+    init                   Create the SQLite database and run migrations
+    scan <path>            Walk a directory recursively and index all files found
+    tag  <glob> <tag>      Apply <tag> to files matched by <glob>
+
+FLAGS:
+    -h, --help             Show this help
+    -V, --version          Show version info
+```
+
+### Details
+
+| Command                     | Arguments / Notes                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `marlin init`               | Safe to run more than once; upgrades the DB in place if schema changes.                                             |
+| `marlin scan <path>`        | Accepts absolute or relative paths. Ignores directories it can’t read.                                              |
+| `marlin tag "<glob>" <tag>` | Use quotes if your shell would otherwise expand the glob. Wildcards follow `glob` crate rules (`**` for recursive). |
+
+---
+
+## Development tips
+
+* `RUST_LOG=debug marlin scan /some/dir` shows per-file indexing messages.
+* The integration database for tests lives in `/tmp` and is wiped automatically.
+* Run `cargo clippy --all-targets --all-features -D warnings` before opening a PR.
+
+---
+
+## Roadmap
+
+| Milestone | What’s coming next                                         |
+| --------- | ---------------------------------------------------------- |
+| **M1**    | Hierarchical tags, attributes table, virtual `tags://` URI |
+| **M2**    | Sync service, change log, diff viewer                      |
+| **M3**    | Natural-language search, visual query builder              |
+| **M4**    | Plug-in marketplace, mobile companion (view-only)          |
+
+---
+
+## License
+
+This project is licensed under the **MIT License**. See `LICENSE` for details.