# MeshiTrack — Copilot Instructions

This is a nutrition management application built as a TypeScript monorepo.

## Project Documentation

Before writing code, always consult the relevant documentation in the `docs/` directory:

- **`docs/PLAN.md`** — Project overview, tech stack, and phase roadmap
- **`docs/architecture.md`** — Architecture Decision Records (ADRs)
- **`docs/cross-cutting.md`** — API versioning, pagination, error handling, security, observability

## Phase Specifications

Each phase has a detailed spec with schemas, endpoints, and business logic:

- **`docs/phases/phase-0-foundation.md`** — Monorepo setup, Docker, Keycloak, auth
- **`docs/phases/phase-1-product-library.md`** — Product CRUD, barcode lookup, LLM interface
- **`docs/phases/phase-2-recipes.md`** — Recipes, nutrition calculation, LLM import
- **`docs/phases/phase-3-pantry.md`** — Pantry tracking, freshness, notifications
- **`docs/phases/phase-4-meal-planning.md`** — Meal plans, nutrition targets, suggestion engine
- **`docs/phases/phase-5-grocery.md`** — Shopping lists, price tracking, store comparison
- **`docs/phases/phase-6-llm.md`** — LLM provider implementations, NLP parsing

## Coding Instructions (MUST READ)

The `docs/instructions/` directory contains best practices and conventions that **must** be followed:

- **`docs/instructions/conventions.md`** — Naming, formatting, linting, git conventions
- **`docs/instructions/fastify.md`** — Fastify plugin structure, Awilix DI, validation, hooks, repository pattern
- **`docs/instructions/nextjs.md`** — App Router, Server/Client Components, data fetching, forms
- **`docs/instructions/mongodb.md`** — Schema design, indexing, queries, pagination
- **`docs/instructions/typescript-zod.md`** — Type design, Zod schemas, shared package rules
- **`docs/instructions/turborepo.md`** — Monorepo workspace config, build pipelines, dependencies
- **`docs/instructions/docker.md`** — Compose services, Dockerfiles, env vars, health checks
- **`docs/instructions/keycloak.md`** — Auth integration, JWT claims, guards, token refresh
- **`docs/instructions/testing.md`** — Vitest unit/integration/E2E test patterns, coverage targets

## Tool Usage Rules

- **Always use `read_file` to read file contents** — never use terminal commands like `Get-Content`, `cat`, `head`, or `tail` to read files. These will be denied.
- **Always use `grep_search` or `file_search` to find files and patterns** — never use `Select-String`, `grep`, `find`, or `rg` in terminal commands.
- **Run scripts only via `npm run <script>`** — never use `npx`, and never add flags like `2>&1`, pipes (`|`), or `Select-Object` to `npm run` commands.
- **Use `execution_subagent` for build/test/lint commands** — it runs `npm run build`, `npm run test`, and `npm run lint` and returns relevant output without piping.
- **Never call tools in parallel** — always wait for one tool call to complete before calling the next. This includes file reads, searches, and terminal commands.
- **Every implementation task must end with**: `npm run build`, `npm run test:cov`, and `npm run lint` all passing. `npm run test:cov` enforces coverage thresholds (100% lines/functions/statements, 90% branches for `packages/api` and `packages/shared`). Do not use `npm run test` alone -- always use `test:cov` to catch coverage regressions.

## Key Rules

1. **All domain types and Zod schemas live in `packages/shared`** — never duplicate types across packages.
2. **Every data query must filter by `householdId`** — this is the multi-tenancy boundary.
3. **Use Server Components by default in Next.js** — only add `'use client'` when interactivity is needed.
4. **Use the repository pattern in Fastify** — routes → services → repositories (Awilix DI).
5. **Use `.lean().exec()` on all Mongoose read queries**.
6. **No `any` types** — use `unknown` and validate with Zod if the type is truly unknown.
7. **Cursor-based pagination** — never use `skip()` for large collections.
8. **ESM everywhere** — `"type": "module"`, `.js` extensions on imports, `import type` for type-only imports.
9. **Zod v4** — import from `'zod/v4'`, use `z.enum()` for enums, `z.email()` / `z.url()` as top-level.
10. **No `.js` extensions on `@/` imports in `packages/web`** — Next.js resolves TypeScript files directly; `.js` extensions on `@/` path-alias imports break Turbopack and webpack. Only use `.js` extensions in `packages/api` and `packages/shared` (Node ESM).