chore(install): add reproducible local setup

docs/installation-log-2026-08-11.md

@@ -0,0 +1,71 @@
+# Installation Record — 2026-08-11
+
+This record captures the successful local source installation performed on an Apple Silicon macOS host. It contains no credentials or machine-specific home-directory path.
+
+## Environment
+
+```text
+Architecture: arm64
+Python: 3.11.15
+Installer: uv 0.11.8
+Virtual environment: <repository>/.venv
+Launcher: ~/.local/bin/cowork-local
+Installed size: approximately 1.3 GB
+```
+
+## Steps executed
+
+From the repository root:
+
+```bash
+git switch -c chore/local-installation
+./scripts/install_local.sh
+```
+
+The installer selected Homebrew Python 3.11, created `.venv`, installed the runtime and test requirement sets, and created the user launcher without replacing any existing path.
+
+Key resolved packages:
+
+```text
+PySide6==6.11.1
+anyio==4.14.2
+holidays==0.102
+keyring==25.7.0
+mcp==1.29.0
+msal==1.37.0
+networkx==3.6.1
+openpyxl==3.1.5
+psutil==7.2.2
+pydantic==2.13.4
+Pygments==2.20.0
+python-pptx==1.0.2
+requests==2.34.2
+pytest==9.1.1
+```
+
+## Verification executed
+
+```bash
+.venv/bin/python -m pytest tests -q
+.venv/bin/python -c "import PySide6, pydantic, requests"
+```
+
+Additional verification imported every module under `cowork_local` with `QT_QPA_PLATFORM=offscreen`, then started the real application entry point with a 1.5-second automatic Qt shutdown.
+
+Results:
+
+```text
+Tests: 81 passed
+Runtime dependency imports: PASS
+Application module imports: 0 failures
+Headless startup: exit 0
+Launcher in PATH: PASS
+```
+
+Qt emitted one non-fatal warning while populating the fallback alias for the missing `Sans Serif` family. It did not affect application startup.
+
+## Optional capabilities
+
+`pypdf` and `opendataloader-pdf` were intentionally not installed in the baseline environment. Install `requirements-optional.txt` when advanced PDF extraction is required. A `soffice` command was detected on the installation host, but LibreOffice availability remains an external host prerequisite rather than a Python dependency.
+
+No provider credential, unlock code, token, or application state was written to the repository during installation or verification.

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).