chore(install): add reproducible local setup

docs/installation.md

@@ -0,0 +1,92 @@
+# Local Installation
+
+This guide installs the source checkout into an isolated virtual environment. It does not modify the system Python and does not store provider credentials in the repository.
+
+## Supported baseline
+
+- Python 3.11 or newer; CI and this installation use Python 3.11.
+- macOS, Linux, or Windows for the cross-platform desktop UI.
+- Windows-only integrations such as AppContainer, Windows Sandbox, Outlook COM, and Office COM conversion remain unavailable on macOS/Linux and degrade gracefully.
+
+## Automated installation
+
+From the repository root:
+
+```bash
+./scripts/install_local.sh
+```
+
+The installer:
+
+1. selects `python3.11` when available;
+2. creates `.venv/` inside the repository;
+3. installs `requirements.txt` and `requirements-test.txt` with `uv` when available, otherwise `pip`;
+4. creates `~/.local/bin/cowork-local` when that path is free;
+5. never replaces an existing launcher or global Python package.
+
+Override the interpreter when necessary:
+
+```bash
+COWORK_PYTHON=/path/to/python3.11 ./scripts/install_local.sh
+```
+
+## Run
+
+Use the repository launcher:
+
+```bash
+./scripts/run_local.sh
+```
+
+If `~/.local/bin` is in `PATH`, use:
+
+```bash
+cowork-local
+```
+
+The launcher changes to the package's parent directory and runs `python -m cowork_local`, which is required by the current source layout.
+
+## Configure credentials
+
+Application state is stored outside Git under `~/.cowork_local/`. Export only the variables you need; `.env.example` documents the supported names. For example:
+
+```bash
+export OPENAI_API_KEY="..."
+export OPENAI_BASE_URL="https://your-approved-gateway/v1"
+export COWORK_SANDBOX_PASSWORD="..."
+export COWORK_MS365_UNLOCK_CODE="..."
+cowork-local
+```
+
+Do not put real values in `.env.example` or any tracked file.
+
+## Verify
+
+```bash
+.venv/bin/python -m pytest tests -q
+.venv/bin/python -c "import PySide6, pydantic, requests; print('runtime imports OK')"
+```
+
+A headless startup smoke test suitable for CI or remote shells is documented in the verification section below:
+
+```bash
+cd ..
+QT_QPA_PLATFORM=offscreen cowork_local/.venv/bin/python -c \
+  "from PySide6.QtCore import QTimer; from PySide6.QtWidgets import QApplication; app=QApplication([]); QTimer.singleShot(1000, app.quit); from cowork_local.app import run; raise SystemExit(run([]))"
+```
+
+## Optional document tooling
+
+Install PDF extraction helpers when needed:
+
+```bash
+uv pip install --python .venv/bin/python -r requirements-optional.txt
+```
+
+LibreOffice is an external application, not a Python package. Install it separately if headless Office-to-PDF conversion is required. Microsoft Office/Outlook COM integration and `pywin32` are Windows-only.
+
+## Update or repair
+
+Pull the desired reviewed revision and rerun `./scripts/install_local.sh`. The operation is idempotent: it reuses `.venv`, reconciles declared packages, and keeps the existing launcher when it already points to this checkout.
+
+The first verified macOS installation is recorded in [installation-log-2026-08-11.md](installation-log-2026-08-11.md).