1 files changed, 82 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..eb167d0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# Parley
+
+Parley is a planned local GNOME/Wayland dictation tool built around the Parakeet transcription runtime. It will provide a per-user D-Bus daemon, global shortcut, GNOME top-bar extension, transcript history, and tiered text insertion through IBus, clipboard, or an opt-in portal paste backend.
+
+See [SPEC.md](SPEC.md) for the architecture, delivery phases, insertion experiments, and acceptance criteria.
+
+## Status
+
+Phase 1 is underway. The repository now contains a terminal-independent Python core for FFmpeg recording, JSONL transcription, and atomic transcript persistence, plus a standalone terminal frontend. The daemon, D-Bus API, clipboard integration, and GNOME extension are not implemented yet.
+
+## Development environment
+
+The initial target is Arch Linux with GNOME 50 on Wayland. Expected host dependencies include:
+
+- Python 3 and PyGObject
+- GNOME Shell and `gnome-extensions`
+- IBus
+- PipeWire/WirePlumber with PulseAudio compatibility
+- FFmpeg
+- systemd user services
+- XDG Desktop Portal and GNOME's portal backend
+- libei/EIS development bindings for the portal-paste experiment
+
+The existing runtime assets are currently located at:
+
+```text
+../transcribe-parakeet/bin/transcribe-cli
+../transcribe-parakeet/models/parakeet-unified-en-0.6b-Q8_0.gguf
+```
+
+That binary presently requires host CUDA 13 and Intel MKL libraries. Do not copy the large model into this Git repository; development configuration should reference its existing path.
+
+## Current developer usage
+
+Create an environment and install the development checkout:
+
+```bash
+cd ../parley
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+```
+
+Run the standalone frontend (Enter stops and transcribes; Escape cancels):
+
+```bash
+parley
+```
+
+By default it uses the runtime and model in `../transcribe-parakeet` and saves under `$XDG_DATA_HOME/parley/transcripts` (normally `~/.local/share/parley/transcripts`). Development paths can be overridden with:
+
+- `PARLEY_FFMPEG`
+- `PARLEY_TRANSCRIBE_CLI`
+- `PARLEY_MODEL`
+- `PARLEY_TRANSCRIPT_DIR`
+- `PARLEY_DEVICE`
+- `PARLEY_LANGUAGE`
+
+Run tests without desktop, microphone, or model dependencies:
+
+```bash
+python -m unittest discover -s tests
+```
+
+Commands such as `parleyctl` and daemon startup will be documented when Phase 2 lands.
+
+## Planned first milestone
+
+1. Extract recording, transcription, and persistence from the TTY frontend.
+2. Preserve a standalone CLI using the shared core.
+3. Add automated tests that do not require GNOME, a microphone, or the model.
+4. Implement the user daemon, D-Bus interface, and `parleyctl toggle` workflow.
+
+## Design principles
+
+- Local-only transcription
+- Never lose a successful transcript because insertion failed
+- Keep model/audio work outside GNOME Shell
+- Respect Wayland's security model
+- Use IBus only if the passthrough/activation feasibility tests prove reliable
+- Keep clipboard-only operation as the safe fallback
+- Make synthetic portal paste explicit and revocable