diff --git a/README.md b/README.md
old mode 100644
new mode 100755
index a873cb8..00a0317
--- a/README.md
+++ b/README.md
@@ -1,16 +1,71 @@
-# muzzlevelocity
+# Muzzle Velocity
-A new Flutter project.
+
-## Getting Started
+A fast and minimalist but opinionated note-taking app inspired by the legendary *Notational Velocity* on MacOS and *Terminal Velocity* for command line terminals.
-This project is a starting point for a Flutter application.
+Built for speed and efficiency, eliminating unnecessary UI clutter. Every action should be as fast and frictionless as possible.
-A few resources to get you started if this is your first Flutter project:
+## Screenshots
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+
+
+ 
Search with tags |
+ 
View mode |
+ 
Editor menu |
+ 
Preview mode |
+ 
Edit mode |
+
+
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+## Features
+
+**Search & Create** — Type to filter notes by title. Hit Enter on a new title to create it instantly. Search by `#tags`, `+projects`, `@contexts`, or `/folders`. Mix them freely.
+
+**Gestures**
+- Swipe right to mark a note as a favorite (swipe right again to remove)
+- Swipe left to move a note to the trash
+
+**Editor** — Three modes: View (syntax-highlighted, read-only), Edit, and Preview (rendered Markdown with LaTeX). Autosave, manual save, font size slider, and plain-text sharing from the editor menu.
+
+**Tags** — Detected automatically from note content. `#tags`, `+projects`, and `@contexts` are all searchable.
+
+**File Organization** — Notes live in a directory you choose. Subfolders are supported and ordered by most recently modified. Empty folders are cleaned up automatically.
+
+**Commands** — Type in the search bar and press Enter:
+
+| Command | Action |
+|---|---|
+| `:help` | Open help guide |
+| `:about` | Open app info |
+| `:tags` | Toggle tag visibility |
+| `:fav` | Toggle favorites filter |
+| `:sub` | Toggle subdirectory search |
+| `:content` | Toggle file content search |
+| `:day` | Switch to light theme |
+| `:night` | Switch to dark theme |
+| `:extern` | Toggle external editor |
+| `:intern` | Toggle internal editor |
+| `:emptytrash` | Permanently delete trashed notes |
+
+## Download
+
+Get the latest .apk on the [Release Page](https://codeberg.org/randogoth/muzzlevelocity/releases)
+
+## Build
+
+```sh
+flutter build apk --release
+```
+
+On systems without Flutter installed, [devbox](https://www.jetify.com/devbox) provides a reproducible environment:
+
+```sh
+devbox install
+devbox shell
+flutter build apk --release
+```
+
+---
+
+Made with 🧡 by randogoth
diff --git a/screenshots/01.jpg b/screenshots/01.jpg
new file mode 100644
index 0000000..40f2635
Binary files /dev/null and b/screenshots/01.jpg differ
diff --git a/screenshots/02.jpg b/screenshots/02.jpg
new file mode 100644
index 0000000..b78d41b
Binary files /dev/null and b/screenshots/02.jpg differ
diff --git a/screenshots/03.jpg b/screenshots/03.jpg
new file mode 100644
index 0000000..88ee553
Binary files /dev/null and b/screenshots/03.jpg differ
diff --git a/screenshots/04.jpg b/screenshots/04.jpg
new file mode 100644
index 0000000..222b214
Binary files /dev/null and b/screenshots/04.jpg differ
diff --git a/screenshots/05.jpg b/screenshots/05.jpg
new file mode 100644
index 0000000..1e7c30f
Binary files /dev/null and b/screenshots/05.jpg differ