Tighten project documentation around the working product

1 files changed, 62 insertions, 113 deletions

diff --git a/README.md b/README.md
index a603464..800b134 100644
--- a/README.md
+++ b/README.md
@@ -1,155 +1,104 @@
 # 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.
+Parley is local, push-to-dictate text input for GNOME on Wayland. Put the caret in a text field, press a shortcut, speak, and press it again. Parley records through PipeWire, transcribes locally with Parakeet, and inserts the result through IBus.
 
-See [SPEC.md](SPEC.md) for the architecture, delivery phases, insertion experiments, and acceptance criteria.
+Audio and transcription stay on your machine. Every successful transcript is also saved and copied to the clipboard before insertion is attempted.
 
-## Status
-
-Phase 1's core and the useful portion of Phase 2 are implemented. The repository contains the standalone frontend, asynchronous per-user D-Bus daemon, `parleyctl`, clipboard copying, prototype notifications, service definitions, and a GNOME Shell 50 top-bar extension. The custom shortcut and insertion experiments are not implemented yet.
-
-## Development environment
+## Platform
 
-The initial target is Arch Linux with GNOME 50 on Wayland. Expected host dependencies include:
+Parley deliberately targets one current desktop stack:
 
-- Python 3 and PyGObject
-- GNOME Shell and `gnome-extensions`
-- IBus
-- PipeWire/WirePlumber with PulseAudio compatibility
+- fully updated Arch Linux
+- GNOME Shell 50 on Wayland
+- IBus 1.5.34
+- PipeWire and WirePlumber
+- Python 3.14 with PyGObject
 - 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
-
-Set up the development checkout with `uv` and Arch's current system Python (Python 3.14). PyGObject is supplied by Arch, so the uv environment must inherit system site packages:
-
-```bash
-cd ../parley
-uv venv --python /usr/bin/python --system-site-packages
-uv pip install -e .
-```
+- the Parakeet `transcribe-cli` runtime and Unified EN model
 
-Use `uv run` for local Python commands.
+Other distributions, desktop environments, X11 sessions, older GNOME releases, and older Python versions are currently unsupported.
 
-Run the standalone frontend (Enter stops and transcribes; Escape cancels):
+## Usage
 
-```bash
-uv run parley
-```
+With Parley installed and the shortcut configured:
 
-By default it finds `transcribe-cli` on `PATH` and the model at `$XDG_DATA_HOME/parley/models/parakeet-unified-en-0.6b-Q8_0.gguf`. During development, each falls back to the corresponding asset in `../transcribe-parakeet`. Transcripts are saved under `$XDG_DATA_HOME/parley/transcripts` (normally `~/.local/share/parley/transcripts`). Paths can be overridden with:
+1. Put the caret in an editable field.
+2. Press `Super+Shift+D` to start recording.
+3. Speak.
+4. Press `Super+Shift+D` again.
+5. Wait for local transcription and insertion.
 
-- `PARLEY_FFMPEG`
-- `PARLEY_TRANSCRIBE_CLI`
-- `PARLEY_MODEL`
-- `PARLEY_TRANSCRIPT_DIR`
-- `PARLEY_DEVICE`
-- `PARLEY_LANGUAGE`
-- `PARLEY_AUTO_INSERT`
-- `PARLEY_INSERTION_MODE` (`clipboard` or `ibus`)
+GNOME displays its microphone privacy indicator while recording. The Parley top-bar indicator shows idle, recording, transcribing, and error states and provides start/stop, cancel, copy-last, and open-folder actions.
 
-Run tests without desktop, microphone, or model dependencies:
+Useful fallback commands:
 
 ```bash
-uv run python -m unittest discover -s tests
+parleyctl status
+parleyctl toggle
+parleyctl cancel
+parleyctl copy
+parleyctl insert
 ```
 
-Run the daemon in a terminal for development:
+Transcripts are stored in:
 
-```bash
-uv run parleyd
+```text
+~/.local/share/parley/transcripts/
 ```
 
-In another terminal, control it over the session bus:
+If insertion is unavailable, the transcript remains saved and on the clipboard, ready for `Ctrl+V`.
 
-```bash
-uv run parleyctl status
-uv run parleyctl toggle  # start recording
-uv run parleyctl toggle  # stop and transcribe
-uv run parleyctl cancel
-uv run parleyctl copy
-```
+## Runtime assets
 
-For the normal development loop, install an editable local user service once:
+Parley expects:
 
-```bash
-./scripts/install-dev
+```text
+~/.local/bin/transcribe-cli
+~/.local/share/parley/models/parakeet-unified-en-0.6b-Q8_0.gguf
 ```
 
-This writes only to `~/.config/systemd/user` and `~/.local/share/dbus-1/services`; it does not install a system package. Python source changes are visible through the editable uv install. Restart the daemon after changes and follow its journal with:
+The current runtime binary requires host CUDA 13 and Intel MKL libraries. The approximately 700 MiB model is not stored in this repository.
 
-```bash
-systemctl --user restart parley.service
-journalctl --user -u parley.service -f
-```
+## Status
 
-Rerun `./scripts/install-dev` after changing entry points or service files.
+The working development build currently provides:
 
-Install the development GNOME Shell extension as a symlink into your user extension directory:
+- asynchronous recording and local transcription through the `parleyd` user service
+- collision-safe transcript persistence and clipboard fallback
+- D-Bus control through `parleyctl`
+- a GNOME Shell 50 top-bar extension
+- a persistent passthrough IBus engine with automatic semantic text insertion
+- local systemd user units and an Arch PKGBUILD
 
-```bash
-./scripts/install-extension
-gnome-extensions info parley@org.parley
-```
+End-to-end IBus insertion is confirmed in Firefox and Ghostty. Broader application, keyboard-layout, compose-key, shortcut, and sensitive-field testing is ongoing; results live in [docs/IBUS_BAKEOFF.md](docs/IBUS_BAKEOFF.md).
 
-The top-bar microphone shows daemon state and its menu provides start/stop, cancel, copy-last, and open-folder actions. Source changes are visible through the symlink, but GNOME Shell must reload the extension; toggle it off and on with the Extensions app. A newly installed extension may require one logout/login on Wayland before Shell discovers it.
+This is not yet a polished end-user release. See [SPEC.md](SPEC.md) for architecture, security constraints, remaining work, and acceptance criteria.
 
-### IBus insertion experiment
+## Development
 
-The development installer also starts a minimal persistent passthrough IBus engine. Enable the experiment with:
+Use Arch's system Python through `uv` so the environment can access system PyGObject bindings:
 
 ```bash
-./scripts/enable-ibus-test
-```
-
-This saves the current engine, selects Parley, and enables automatic IBus insertion in the daemon. Put the caret in a normal text field and use the recording shortcut twice. Successful transcripts are still saved and copied before insertion. Password and PIN purposes are refused where the application reports them.
-
-This is a bake-off prototype: while it is enabled, explicitly test normal typing, modifiers, shortcuts, compose/dead keys, layout switching, terminals, browsers, and Electron applications. Restore the previous engine and clipboard-only mode with:
-
-```bash
-./scripts/disable-ibus-test
+uv venv --python /usr/bin/python --system-site-packages
+uv pip install -e .
+./scripts/install-dev
 ```
 
-## Arch Linux package
-
-The local PKGBUILD installs `parleyd` and the other executables under `/usr/bin`, the systemd **user** unit under `/usr/lib/systemd/user`, and the session D-Bus service under `/usr/share/dbus-1/services`. It builds from the latest committed state of this checkout:
+Run tests and inspect the daemon:
 
 ```bash
-git status                    # commit the source you want packaged
-cd packaging/arch
-makepkg -si
-systemctl --user daemon-reload
-systemctl --user enable --now parley.service
+uv run python -m unittest discover -s tests
+systemctl --user restart parley.service
+journalctl --user -u parley.service -f
 ```
 
-The package deliberately does not bundle the runtime or model. Put `transcribe-cli` on `PATH` (for example at `~/.local/bin/transcribe-cli`) and the model at `~/.local/share/parley/models/parakeet-unified-en-0.6b-Q8_0.gguf`, or set the documented environment overrides. User-manager environment overrides can be placed in `~/.config/environment.d/parley.conf`; log in again after changing them.
-
-The prototype daemon uses `xclip` through GNOME's XWayland clipboard bridge and `notify-send` for notifications.
-
-## 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.
+Development helpers for the Shell extension and IBus experiment are in [`scripts/`](scripts/). The local Arch package recipe is in [`packaging/arch/`](packaging/arch/).
 
-## Design principles
+## 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
+- local-only audio and transcription
+- visible recording state
+- save and copy before attempting insertion
+- never destabilize GNOME Shell with model or audio work
+- refuse known password and PIN fields
+- preserve a clipboard fallback when an application rejects IBus insertion