add README with screenshots, features, and build instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -1,16 +1,71 @@
-# muzzlevelocity
+# Muzzle Velocity
 
-A new Flutter project.
+<img src="assets/blaster.svg" width="96" alt="Muzzle Velocity logo">
 
-## 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)
+<table>
+  <tr>
+    <td align="center"><a href="screenshots/01.jpg"><img src="screenshots/01.jpg" width="180"></a><br><sub>Search with tags</sub></td>
+    <td align="center"><a href="screenshots/02.jpg"><img src="screenshots/02.jpg" width="180"></a><br><sub>View mode</sub></td>
+    <td align="center"><a href="screenshots/03.jpg"><img src="screenshots/03.jpg" width="180"></a><br><sub>Editor menu</sub></td>
+    <td align="center"><a href="screenshots/04.jpg"><img src="screenshots/04.jpg" width="180"></a><br><sub>Preview mode</sub></td>
+    <td align="center"><a href="screenshots/05.jpg"><img src="screenshots/05.jpg" width="180"></a><br><sub>Edit mode</sub></td>
+  </tr>
+</table>
 
-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