AGENTS.md for a 400k-line Nx monorepo

# AGENTS.md — platform monorepo

Nx workspace, ~400k LOC, 40+ projects. pnpm + Nx 20. Read this before touching anything.

## Orientation

- `apps/` — deployables: `web` (Next.js), `api` (Nest), `worker`, `admin`
- `libs/shared/` — cross-cutting: `ui`, `util`, `types`, `config`. CHANGES HERE FAN OUT — see boundary rules.
- `libs/domain/` — business logic per domain: `billing`, `catalog`, `identity`, `shipping`
- `tools/` — generators and scripts. Generated outputs are marked with `@generated` headers.
- Project graph when confused: `npx nx graph --focus=<project> --print` (do NOT open the web UI).

## Commands — affected only

The workspace is too big for full runs. Always scope:

- Test what you changed: `npx nx affected -t test --base=main`
- Build + lint + test gate: `npx nx affected -t build,lint,test --base=main`
- One project: `npx nx test domain-billing` / `npx nx build web`
- NEVER `nx run-many -t test --all`. It takes 40 minutes and tells us nothing affected didn't.

## Module boundaries

Enforced by `@nx/enforce-module-boundaries` — lint failures here are design feedback, not obstacles.

- `apps/*` may import `libs/*`; libs NEVER import from apps.
- `libs/domain/*` may import `libs/shared/*` but not other domains. Cross-domain needs go through events (`libs/shared/events`) — ask before adding one.
- `libs/shared/*` imports nothing outside `libs/shared`. It is the bottom of the graph.
- Owners: `shared/*` platform team; `domain/billing` payments team; everything else, the team in `CODEOWNERS`. Changing another team's lib: make the change minimal and flag it in the PR description.

## Generated code

- Files with an `@generated` header are NEVER edited directly. Find the generator under `tools/generators` and change the source. If unclear, `git log --follow <file>` shows the generator commit pattern.
- After running a generator, commit generated output separately from hand-written changes.

## Testing

- Unit tests colocated; `nx affected -t test` must be green before you call anything done.
- Integration tests (`apps/api-e2e`) run only when your change touches `apps/api` or `libs/domain/*` public APIs.
- Do not increase any project's `testTimeout` to make a flaky test pass. Report the flake.

## Prohibited

- Root config files (`nx.json`, `tsconfig.base.json`, `pnpm-workspace.yaml`, root `package.json`): human-only.
- No new projects without the generator: `npx nx g @nx/js:lib` — and ask first.
- Do not "clean up" imports across projects you weren't asked to touch; wide mechanical PRs break every open branch.

## Done means

1. `npx nx affected -t build,lint,test --base=main` green, output included in your summary.
2. Diff contained to the projects the task named (plus generated output, committed separately).
3. Any boundary-lint suppression = automatic failure. There are currently zero; keep it that way.