quill: Instructions file for GitHub Copilot

Copilot instructions for this repository

Repository state

This repository contains the implementation source tree together with the product requirements document under docs/Product Requirement Documents and Specifications/QUILL-PRD.md and docs/QUILL-PRD.html.

When generating code or task plans, treat the PRD as the source of truth for intended architecture and conventions. For the detailed day-to-day command and invariant reference, read CLAUDE.md; keep this file as the concise, always-on guide.

Build, test, and lint commands

The project has a runnable test suite and CI gates. Use focused tests while developing, then run the narrowest applicable quality checks:

# Environment setup
uv python install 3.14
uv sync --all-extras
pre-commit install

# Fast test paths
pytest -m smoke -q
pytest tests\unit\path\to\test_file.py::test_name -q
pytest -q -n 8 --dist loadgroup

# Lint + strict type-check
ruff check .
ruff format --check .
mypy quill\core quill\io

# Optional suites
RUN_PERF=1 pytest -m perf -q
$env:QUILL_UIA_TESTS = "1"; pytest -m uia -q

tests/conftest.py forces quill.core.paths._DEV_BUILD = True and puts the pytest temp root under the user home directory. This is what makes per-test QUILL_DATA_DIR overrides safe; preserve it and use tmp_path for isolated persistence tests. The parallel command above serializes tests/unit/ui on one worker because wx, clipboard, hotkey, and screen-reader resources are process-global.

quill/core and quill/io are strict and wx-free. Keep mypy scoped to those layers; quill/ui is gradually typed. Before changing the UI dependency, note that wxPython is exactly pinned in pyproject.toml because screen-reader acceptance covers that tested build, not every upstream wx release.

High-level architecture (from PRD)

Quill is designed as a screen-reader-first Windows desktop app in Python + wxPython, with a strict separation between UI, core logic, I/O format handlers, platform bindings, and optional AI providers.