# Console Outlook add-in — install & hosting (P6)

The Console add-in augments a live Outlook **reply compose**: click the ribbon button →
the taskpane drafts an AI reply from your thread + voice corpus → inject it on top of the
quoted original → you send natively. Provenance is stamped at inject so the matcher can
link the sent reply back to its draft (D-019).

This doc covers install + the two hosting modes. It assumes the Console backend and sync
daemon are already set up (see the repo `CLAUDE.md` / `docs/`).

---

## Prerequisites

1. **Backend running** — from the repo:
   ```
   cd backend && env -u ANTHROPIC_API_KEY uv run uvicorn bens_console.api.app:app \
     --host 127.0.0.1 --port 8765
   ```
   The taskpane talks to this. A red header dot = backend unreachable.
2. **Signature with the provenance URL** — for the primary provenance gate (Gate 1) to
   fire, your Outlook signature must contain a URL matching the configured
   **Settings → Signature URL pattern** (default `https://app.smartsheet.com/b/form/...`).
   No matching URL → the add-in falls back to the content-fingerprint gate (still works,
   just no edit-survival link). You can change the pattern in the add-in's Settings tab.

---

## Hosting modes

The taskpane is static HTML/JS; Office requires it over **HTTPS**. Two ways to serve it:

### A. Dev hosting (current default) — `addin/dev-server.py`

An HTTPS static server on `https://localhost:3443` that also reverse-proxies `/api/*` to the
HTTP backend on `127.0.0.1:8765`, so the HTTPS taskpane reaches the backend **same-origin**
(no mixed-content / CORS). Launch:
```
cd addin && CERT="$HOME/.office-addin-dev-certs/localhost.crt" \
  KEY="$HOME/.office-addin-dev-certs/localhost.key" PORT=3443 python3 dev-server.py
```
The shipped `manifest.xml` points at `https://localhost:3443/taskpane.html` — this is what
you sideload today.

### B. Production hosting — the backend serves `/addin/*`

The backend now mounts the add-in's static files at `/addin/*` (e.g.
`https://127.0.0.1:8765/addin/taskpane.html`). Same origin as `/api/*`, so no proxy is
needed. **This requires the backend to be served over HTTPS** — which is a deliberate
cutover (see below), because the Next.js frontend currently talks to the backend over
**HTTP** on the same port.

---

## The HTTPS cutover (decision pending — do NOT flip without deciding)

Moving the add-in onto the backend's `/addin/*` over HTTPS means `127.0.0.1:8765` serves
HTTPS, and the frontend must move to HTTPS too. Options:

1. **Backend HTTPS on :8765** — launch uvicorn with the dev certs and point the frontend at
   `https://127.0.0.1:8765`:
   ```
   cd backend && env -u ANTHROPIC_API_KEY uv run uvicorn bens_console.api.app:app \
     --host 127.0.0.1 --port 8765 \
     --ssl-keyfile "$HOME/.office-addin-dev-certs/localhost.key" \
     --ssl-certfile "$HOME/.office-addin-dev-certs/localhost.crt"
   ```
   Then update the frontend's API base to `https://127.0.0.1:8765`.
2. **Second HTTPS instance** — keep HTTP :8765 for the frontend, run a second uvicorn
   instance with `--ssl-*` on a different port (e.g. `:8443`) for the add-in; point the
   manifest at `https://127.0.0.1:8443/addin/taskpane.html`. No frontend change.
3. **Stay on the dev-server (A)** — defer the cutover; the dev-server keeps working.

After choosing, update `manifest.xml`'s `SourceLocation` + the icon/command URLs to the new
host, then **re-sideload** (the manifest URL changed). The `/addin/*` mount and this doc are
ready; the flip itself is intentionally left as a decision.

---

## One-time install (sideload via OWA)

1. Open `outlook.office365.com` in a browser, signed into your Microsoft 365 account.
2. **Settings (gear, top-right) → Get Add-Ins** (or "Manage Add-ins").
3. **My Add-Ins** tab → scroll to **Custom Add-ins** → **+ Add a custom add-in → Add from File…**
4. Select `addin/manifest.xml` from the repo root (the local clone of this repository).
5. Confirm the prompt (it warns it's a developer add-in — expected).
6. Wait a few minutes for propagation to desktop **Legacy** Outlook on the Mac.
7. Open a **reply** in Legacy Outlook — the **Console** group → **Draft Reply** button shows
   in the compose ribbon (compose-only by design; it won't appear in the read view).

---

## Verify

- Open a reply → click **Draft Reply** → the taskpane loads on **Home** with the Draft Reply
  workflow.
- Header dot **green** = backend reachable. Red = start the backend (see Prerequisites).
- Click **Draft Reply** → **Draft AI reply** → a preview appears → **Inject** → the AI prose
  lands on top of the quoted original. The inject footer reports the provenance gates.
- **Recent** tab lists past drafts; **Settings** shows health + voice-k + the sig config +
  **Send feedback**.

---

## Troubleshooting

- **Button missing** → make sure you're in a *reply compose* window (compose-only ribbon);
  give propagation a few minutes; re-open the compose window.
- **Red dot / "backend unreachable"** → start the backend; retry.
- **Taskpane won't load** → the dev cert may have expired; reinstall with
  `office-addin-dev-certs install`, restart the host server, re-open the taskpane.
- **No provenance link on a sent reply** → confirm your signature contains a URL matching the
  Settings → Signature URL pattern; the content-fingerprint gate still links unedited sends.