# ByteMail for Windows

Select an email, press **Ctrl+Alt+R**, get the reply.

The same tool as the macOS app, built on the Python side of the repository.
Windows has no Accessibility API shaped like macOS's, so the two apps read the
selection differently, but the prompt stack, the gap rule and the sample caps
are shared files rather than two implementations: `prompt/`, `src/ai/`,
`src/llm/` and `config/providers.py` are read by this app exactly as the
prototype reads them.

## Run it from the checkout

```powershell
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt -r requirements-dev.txt
.\.venv\Scripts\python run.py
```

The app sits in the notification area. Select an email in Outlook, in Gmail, in
Word, anywhere, and press the shortcut.

## What it does

1. Reads the selected text, and the text around it when the application allows
   it, through UI Automation; the clipboard is the fallback.
2. Asks the model for a reply in the user's own voice, streaming it into a
   panel that appears over the mail.
3. Anything the model cannot ground in the email becomes a labelled field.
   **Copy stays closed until every field is answered**, so an invented date or
   price cannot leave the app.
4. **Ctrl+Shift+C** copies, **Ctrl+Enter** replaces the text that was selected.

Nothing is sent, ever. The only network call is the draft request to the
provider the user chose, with the key kept in the Windows credential store
(DPAPI) rather than in a settings file.

## Verify without a key

```powershell
python run.py --contracttest   # the gap gate, the model contract, shortcuts,
                               # the profile hand-off, the sample caps
python run.py --selftest       # one live reply through the real prompt stack
```

`--contracttest` needs no key, no window server and no mail client, and it is
what CI runs on Windows before it builds the installer. Every check in it was a
real defect at some point, and none of them raised an error when they were.

## Build the installer

```powershell
.\build.ps1 -Check
```

That lints, runs the tests and the contract test, freezes the app with
PyInstaller, and writes `ByteMail_Windows.zip`. GitHub Actions does the same on
a `v*` tag and attaches the zip to the release, so the download link on the
website is always a build that passed those checks.

## Files

| File | Responsibility |
|---|---|
| `run.py` | Entry point: the tray app, and the `--contracttest` commands |
| `bytemail/app.py` | The controller: tray, shortcut, and the flow between them |
| `bytemail/engine.py` | Providers, streaming, and the learn-my-voice call |
| `bytemail/prompt.py` | The user turn, section for section with the Swift app |
| `bytemail/draft.py` | The panel's state: the reply, the gaps, the Copy gate |
| `bytemail/store.py` | Preferences, the profile, the learned voice, the caps |
| `bytemail/transfer.py` | Reading the selection, and pasting the reply back |
| `bytemail/hotkey.py` | Parsing and registering the global shortcut |
| `bytemail/ui/panel.py` | The panel itself |
| `bytemail/ui/settings_window.py` | Settings |
| `bytemail/diagnostics.py` | `--contracttest` and `--selftest` |
| `check_version.py` | Fails when the macOS, Windows and product versions drift |
