# Copilot Workspace Instructions

Purpose
- Help Copilot-style agents and contributors be productive and safe in this repository.
- Surface where to find authoritative docs and which conventions to follow.

Principles
- Link, don't embed: prefer linking to existing docs in `docs/`, `CONTRIBUTING.md`, or `README.md` rather than duplicating content.
- Minimize blast radius: make minimal, focused changes and explain rationale in PRs.
- Ask clarifying questions before large or ambiguous changes.

What the agent is allowed to do
- Suggest edits, create focused patches, and propose new files following repo style.
- Use `apply_patch` for file edits; create new files only when necessary.
- Run or suggest commands to run tests locally, but do not push or merge without human approval.

Conventions & expectations
- Follow existing code style and directory boundaries (`backend/` for Flask/Python, `frontend/` for Vite/TypeScript).
- When changing behavior, run tests and list the commands to reproduce the failure/fix.
- Keep PRs small and target a single logical change.

Key files & links (authoritative sources)
- README: [README.md](README.md#L1)
- Contribution & tests: [CONTRIBUTING.md](CONTRIBUTING.md#L1)
- Docker & run commands: [docs/Docker-Commands-Guide.md](docs/Docker-Commands-Guide.md#L1)
- Backend entry & requirements: [backend/requirements.txt](backend/requirements.txt#L1), [backend/Dockerfile](backend/Dockerfile#L1)
- Frontend scripts: [frontend/package.json](frontend/package.json#L1), [frontend/Dockerfile](frontend/Dockerfile#L1)
- Compose files: [docker-compose.yml](docker-compose.yml#L1), [docker-compose.prod.yml](docker-compose.prod.yml#L1)
- Deployment scripts: [scripts/deploy.sh](scripts/deploy.sh#L1)

Common build & test commands
- Backend tests (project root):
```
cd backend && python -m pytest tests/ -q
```
- Frontend dev & tests:
```
cd frontend && npm install
cd frontend && npm run dev
cd frontend && npx vitest run
```
- Dev compose (full stack):
```
docker compose up --build
```
- Prod deploy (refer to `scripts/deploy.sh`):
```
./scripts/deploy.sh
```

Anti-patterns (avoid)
- Don't invent architectural decisions or rewrite large areas without explicit approval.
- Don't add secrets, large binary files, or unrelated formatting changes.
- Don't run destructive commands or modify CI/CD configuration without coordination.

Agent prompts & examples
- "Create a small Flask route in `backend/app/routes` that returns health JSON and add a unit test."
- "Refactor the image compression service to extract a helper; update callers and tests." 
- "List the exact commands I should run to reproduce the failing tests for `backend/tests/test_pdf_service.py`."

Suggested follow-ups (agent customizations)
- `create-agent:backend` — focused on Python/Flask edits, runs `pytest`, and knows `backend/` structure.
- `create-agent:frontend` — focused on Vite/TypeScript, runs `vitest`, and uses `npm` scripts.
- `create-agent:ci` — analyzes `docker-compose.yml` and `scripts/deploy.sh`, suggests CI checks and smoke tests.

If you want, I can:
- Open a draft PR with this file, or
- Expand the file with more precise command snippets and per-service README links.

---
Generated by a workspace bootstrap; iterate as needed.