1 files changed, 72 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b3cabf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# qpass
+
+`qpass` is a small Go password generator with a conservative cryptographic
+randomness model.
+
+By default it uses Go's `crypto/rand` OS CSPRNG. It can also run in hybrid mode,
+where local OS randomness is mixed with bytes from an external quantum,
+hardware, or certified randomness source. The external source is additive: it
+never replaces the OS CSPRNG as the safety baseline.
+
+## Usage
+
+```bash
+go run ./cmd/qpass
+go run ./cmd/qpass -stats
+go run ./cmd/qpass -length 32 -count 5
+go run ./cmd/qpass -length 32 -symbols=false
+```
+
+Hybrid entropy mode:
+
+```bash
+go run ./cmd/qpass -rng hybrid -entropy-file random-bytes.bin
+go run ./cmd/qpass -rng hybrid -entropy-device /dev/qrandom
+qrng-tool --raw | go run ./cmd/qpass -rng hybrid -entropy-stdin
+```
+
+Legacy compatibility:
+
+```bash
+go run ./cmd/qpass -length 32 -quantum-file random-bytes.bin
+qrng-tool --raw | go run ./cmd/qpass -length 32 -quantum-file -
+```
+
+`-quantum-file` is kept as an alias for older usage. New scripts should prefer
+`-rng hybrid` with `-entropy-file`, `-entropy-device`, or `-entropy-stdin`.
+
+Entropy checks:
+
+```bash
+go run ./cmd/qpass entropy status
+go run ./cmd/qpass entropy test -entropy-file random-bytes.bin
+go run ./cmd/qpass entropy test -entropy-device /dev/qrandom -require-external
+```
+
+## Notes
+
+- `-rng os` uses only Go's `crypto/rand.Reader`.
+- `-rng hybrid` mixes `crypto/rand.Reader` with the configured external source
+  using SHA-512 domain-separated blocks.
+- Without `-require-external`, hybrid mode degrades to OS CSPRNG if the external
+  source runs out or fails, and prints a warning on stderr.
+- With `-require-external`, generation fails when the external source cannot
+  provide enough bytes.
+- `-replace-global-rand` installs the selected engine as `crypto/rand.Reader`
+  for this process. It is an advanced integration option; normal password
+  generation passes the reader explicitly.
+- Entanglement-based randomness certification needs physical hardware and a
+  Bell-test/randomness-amplification protocol.
+- A normal laptop cannot reproduce that guarantee in software.
+- For everyday password generation, OS CSPRNG via `crypto/rand` is the
+  practical baseline.
+- `qpass` prints only passwords by default. Use `-stats` when you want the
+  alphabet size and estimated entropy on stderr.
+
+## Development
+
+```bash
+make fmt
+make test
+make build
+```