From a4dfb88a5d6e88ffeaa9dd566691f5afb9fe3bbe Mon Sep 17 00:00:00 2001
From: pavelb <pavelb@bugsy.cz>
Date: Fri, 6 Mar 2026 20:27:06 +0100
Subject: [PATCH] Add README

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c972197
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# Password Zebra
+
+An open-source Android password manager with two core features: a syllable-based random password generator and a deterministic password vault. No passwords are stored — they are derived on demand.
+
+**Minimum Android version:** 10 (API 29)
+
+<!-- Screenshots -->
+
+## Features
+
+### Random Password Generator
+Generates memorable, pronounceable passwords from a syllable corpus. Options:
+- Word count (1–10)
+- Remove spaces
+- Add special characters (uppercase letter, digit, special symbol inserted at random positions)
+
+### Deterministic Password Vault
+Derives passwords reproducibly from three inputs:
+- **Master password** — known only to you, never stored
+- **Device secret** — random key generated once and stored in Android Keystore via EncryptedSharedPreferences
+- **Service name + counter** — identifies the account and allows rotation
+
+The derivation uses **Argon2id** (memory: 64 MB, iterations: 3) so the same inputs always produce the same password, on any device that has the same device secret.
+
+**Service history** is saved locally so you can quickly regenerate passwords for known services.
+
+### Export / Import
+Transfer your device secret and service history to another device using an encrypted QR code, secured with Android device credentials (PIN/pattern/password).
+
+## Security
+- Screen content is protected with `FLAG_SECURE` (no screenshots, no recent apps preview)
+- Master password is held as `CharArray` and wiped from memory immediately after derivation
+- Device secret lives exclusively in Android Keystore-backed EncryptedSharedPreferences
+- No network permissions; no data leaves the device
+
+## Build
+
+```bash
+# Debug APK
+./gradlew assembleDebug
+
+# Install on connected device
+./gradlew installDebug
+
+# Unit tests
+./gradlew test
+
+# Lint
+./gradlew lint
+```
+
+Release signing requires a `keystore.properties` file at the project root:
+```
+storeFile=<path to .jks>
+storePassword=<password>
+keyAlias=<alias>
+keyPassword=<password>
+```
+
+## Tech Stack
+- Kotlin + Jetpack Compose + Navigation Compose
+- Material 3 with dynamic color (Android 12+)
+- Argon2id via Bouncy Castle (`bcprov-jdk15on`)
+- EncryptedSharedPreferences (`security-crypto`)
+- QR export/import via ZXing
+
+## License
+GNU General Public License v3.0 — see [LICENSE](LICENSE).