Root AGENTS.md for a Turborepo monorepo

A root AGENTS.md demonstrating the nested-file pattern: repo-wide rules here, per-package files closest to the code win.

# Nova (Turborepo monorepo)

## Project Overview
pnpm workspaces + Turborepo. Apps in `apps/` (web: Next.js, api: Hono),
shared code in `packages/` (ui, config, db, tsconfig). Node 20, TypeScript
strict everywhere. This root file holds repo-wide rules; each package has its
own AGENTS.md with specifics - the closest file to the code you edit wins.

## Setup & Commands
```bash
pnpm install                            # once, at the root only
pnpm turbo run build                    # build everything (cached)
pnpm turbo run test --filter web        # test one workspace
pnpm turbo run lint typecheck           # repo-wide gates
pnpm --filter @nova/db generate         # regen Drizzle client after schema edits
```

## Repo-wide rules
- Workspace deps use `workspace:*` protocol; never a version range for
  internal packages.
- Cross-package imports go through the package's public entry
  (`@nova/ui`, `@nova/db`) - reaching into another package's `src/` breaks
  the build graph and the cache.
- Shared tsconfig/eslint come from `packages/config`; packages extend, never fork.
- Env vars are validated per app in `apps/*/env.ts`; new vars get added there
  first or the app fails at boot.

## Testing
- `pnpm turbo run test --filter <pkg>` while iterating; the unfiltered run is
  for CI. Turbo caches by inputs - if a test "didn't run", its inputs didn't change.

## Boundaries
- Never run package scripts from inside a package dir with a different package
  manager; everything goes through pnpm at the root.
- `packages/db/src/generated/` is codegen output - regenerate, don't edit.
- Do not add a dependency to the root `package.json` unless it is a repo-wide
  dev tool; runtime deps belong to the package that uses them.

## PR Guidelines
- One workspace per PR when possible; `turbo run lint typecheck test` must be
  green. Changesets required for anything under `packages/` that ships.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.