chore: onboard repository agents

.github/copilot-instructions.md

@@ -0,0 +1,20 @@
+# Copilot repository instructions
+
+Follow the complete workflow in the root `AGENTS.md`. Treat current code, tests, `pyproject.toml`, `justfile`, `frontend/package.json`, and `.github/workflows/ci.yml` as authoritative.
+
+Tax Tracker is a local-first federal tax calculator and W-4 optimizer. Its React 19/TypeScript/Vite SPA stores personal records only in browser IndexedDB through Dexie. Its Python 3.14 FastAPI/Pydantic service performs transient calculations and does not persist personal data. Do not add server persistence, accounts, real financial data, or state-tax behavior unless explicitly requested. API routes have no `/api` prefix, and FastAPI serves `frontend/dist` with SPA fallback behavior in production.
+
+Use `uv` with the committed `uv.lock`, Node.js 26, and pnpm 11 with `frontend/pnpm-lock.yaml`. Bootstrap from the repository root with:
+
+```bash
+uv sync --locked --dev
+pnpm --dir frontend install --frozen-lockfile
+```
+
+Use focused tests while iterating. Before completing a code change, run the relevant checks and normally `just check`; use `just ci` for broader or high-risk changes. Backend pytest configuration enforces 80% overall coverage, while `just test-services` enforces 90% coverage across calculation services. Frontend behavior changes require Vitest/React Testing Library tests and `just frontend-check`. Run `uv run pre-commit run --all-files` for repository configuration, workflow, or documentation changes.
+
+Treat tax calculations, W-4 logic, projections, and files under `src/taxtracker/data/` as high risk. Tax logic or constants must cite an authoritative IRS or SSA source and include independently verifiable tests. Never weaken known-correct tax assertions to accommodate an implementation. Keep all examples and fixtures synthetic and free of personally identifiable information.
+
+CI additionally runs a Docker production smoke test, Playwright browser tests, dependency scanning, and a network-backed PSLmodels cross-check. Run those checks when the change affects them and the required Docker, browser, or network capability is available; do not claim they ran when they did not. Do not update dependencies, lockfiles, generated snapshots, or generated frontend output unless the task calls for it.
+
+Keep changes focused, update user or contributor documentation when behavior or workflows change, preserve unrelated work, and do not commit or push unless explicitly requested.

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,38 @@
+name: Copilot Setup Steps
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        with:
+          version: 11
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: "26"
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          enable-cache: true
+          cache-suffix: copilot
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Install backend dependencies
+        run: uv sync --locked --dev
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile

AGENTS.md

@@ -0,0 +1,79 @@
+# Repository Agent Guide
+
+Use this file as the primary guide for automated work in this repository. Trust it before doing broad searches. If an instruction conflicts with executable configuration or current code, follow the configuration or code and update this guide when appropriate.
+
+## Product and boundaries
+
+Tax Tracker is a local-first federal tax calculator and W-4 optimizer. The React SPA stores paychecks, pensions, settings, and scenarios in browser IndexedDB through Dexie. The FastAPI service is stateless: it accepts calculation inputs for a request and does not persist personal records. Do not introduce accounts, server-side personal-data storage, or a database without an explicit product decision.
+
+The supported scope is common federal wage and pension workflows. State and local taxes are out of scope. Treat this as tax-planning software, not tax advice. Never put real financial records, personally identifiable information, credentials, or secrets in code, fixtures, logs, issues, or documentation; use synthetic examples only.
+
+## Toolchain and bootstrap
+
+- Python 3.14 (`.python-version`), managed with `uv`; FastAPI and Pydantic v2.
+- Node.js 26 (`.nvmrc`) and pnpm 11; React 19, TypeScript, and Vite.
+- Backend quality tools: Ruff, `ty`, pytest, and pre-commit.
+- Frontend quality tools: Oxc (`oxlint`/`oxfmt`), TypeScript, Vitest, React Testing Library, and Playwright.
+- `justfile` is the canonical command catalog. Run `just --list` for recipes. Direct `uv` and `pnpm` equivalents are valid when `just` is unavailable.
+
+From the repository root, install locked dependencies without changing lockfiles:
+
+```bash
+uv sync --locked --dev
+pnpm --dir frontend install --frozen-lockfile
+```
+
+Do not upgrade dependencies or regenerate `uv.lock` or `frontend/pnpm-lock.yaml` unless the task requires it.
+
+## Architecture and navigation
+
+- `src/taxtracker/cli/app.py` creates the FastAPI application, registers routers, exposes `/health`, and serves the built SPA from `frontend/dist` when present.
+- `src/taxtracker/api/` contains stateless route handlers. API routes do **not** use an `/api` prefix.
+- `src/taxtracker/models/` contains Pydantic request, response, and browser-record models.
+- `src/taxtracker/services/` contains tax, projection, reconciliation, W-4, withholding, and data-loading logic.
+- `src/taxtracker/data/` contains IRS/SSA-sourced tax-bracket and FICA JSON for supported years.
+- `frontend/src/pages/` contains screens; `frontend/src/lib/api/` contains the API client and wire types; `frontend/src/lib/storage/` owns browser persistence.
+- `frontend/src/app/router.tsx` defines browser routes. Vite proxies backend route prefixes to `127.0.0.1:8000` during development.
+- `tests/unit/` covers calculations, data, and SPA routing; `tests/integration/` covers API behavior; frontend tests live beside the TypeScript modules; `frontend/e2e/` contains Playwright workflows.
+- `pyproject.toml`, `frontend/package.json`, frontend tool configs, `.pre-commit-config.yaml`, and `.github/workflows/ci.yml` are the sources of truth for tooling and validation.
+
+## Run and validate
+
+Run the API and frontend in separate terminals:
+
+```bash
+just run
+just frontend-dev
+```
+
+The frontend is available at `http://localhost:5173` and proxies the API at `http://127.0.0.1:8000`. For the production-style combined app, run `just app` and open `http://127.0.0.1:8000`.
+
+Use focused checks while iterating:
+
+```bash
+just test-file tests/unit/test_tax_calculator.py
+just test-name tests/unit/test_tax_calculator.py pattern
+just test-unit
+just test-integration
+just frontend-test
+```
+
+Before finishing, run checks proportional to the change, then the applicable aggregate gate:
+
+```bash
+just check          # format-check, lint, typecheck, fast backend tests, frontend checks
+just ci             # lint, typecheck, full backend tests, frontend checks
+just test-services  # separate 90% calculation-service coverage gate
+```
+
+The normal pytest configuration enforces at least 80% overall backend coverage. CI also runs pre-commit, the 90% service gate, a production-container smoke test, Playwright E2E, dependency scanning, and a PSLmodels cross-check. Run `uv run pre-commit run --all-files` when changing configuration, workflows, or documentation. Run `just frontend-test-e2e` for browser workflow changes after installing Chromium with `pnpm --dir frontend exec playwright install chromium`. Network-dependent security and PSL snapshot commands need not run for unrelated work.
+
+## Correctness rules
+
+- Tax math and tax-data changes are high risk. Cite the exact authoritative IRS or SSA source, cross-check values, and add tests with independently known-correct outcomes. See `docs/irs_data_sources.md` and `docs/annual_tax_data_update.md`.
+- Preserve calculation ordering: taxable income and deductions feed federal tax; supported credits reduce federal tax; FICA applies to eligible W-2 wages, not pension income.
+- Never weaken or rewrite IRS-validated assertions merely to make tests pass. Fix the implementation or establish that the expected value is wrong from an authoritative source.
+- Behavior changes require tests. Frontend behavior changes require Vitest/React Testing Library coverage; API changes require integration coverage; calculation changes require focused unit and validation cases.
+- Keep API and frontend wire types synchronized. Preserve browser-only persistence and SPA fallback behavior.
+- Update `README.md` or relevant `docs/` files when behavior, supported features, setup, APIs, architecture, tax data, or contributor workflow changes.
+- Keep changes focused and preserve unrelated user work. Do not commit or push unless explicitly asked. When asked to commit, use conventional prefixes such as `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, or `chore:`.