# AGENTS.md

<!-- Original teaching template for nextjs/saas-starter, not an upstream file.
     Source snapshot: 6e33e58b1e553a41fe22e6b941a7229a002de361.
     Repository facts were inspected on 2026-11-15.
     Recheck the facts below before using this with another revision. -->

## Project context

- This is a Next.js App Router application using TypeScript, PostgreSQL,
  Drizzle, Stripe, and Tailwind CSS.
- Follow the existing pnpm workflow and retain `pnpm-lock.yaml`.
- The inspected manifest uses Next.js `15.6.0-canary.59`. It has no
  `packageManager` field; do not claim an exact pnpm version is pinned.

<!-- Directory facts come from the Git tree. Names alone can be misleading:
     the marketing homepage is inside the (dashboard) route group. -->

## Where changes belong

- Marketing homepage: `app/(dashboard)/page.tsx`.
- Pricing: `app/(dashboard)/pricing/`.
- Signed-in dashboard: `app/(dashboard)/dashboard/`.
- Sign-in, sign-up, and related actions: `app/(login)/`.
- HTTP route handlers: `app/api/`.
- Reusable UI primitives: `components/ui/`.
- Authentication and session helpers: `lib/auth/`.
- Database schema, queries, and migrations: `lib/db/`.
- Stripe integration and payment actions: `lib/payments/`.
- Global styles: `app/globals.css`.

<!-- These are suggested working rules for this tutorial, not claims about
     the upstream maintainers' existing policy. -->

## Change conventions

- Follow nearby components and reuse existing UI and library helpers.
- Preserve the strict TypeScript configuration in `tsconfig.json`.
- The `@/*` alias maps to the repository root; follow existing imports.
- Keep copy and styling tasks scoped to their relevant pages/components.
- For schema changes, use `lib/db/schema.ts` and the migration output
  directory `lib/db/migrations`, as configured in `drizzle.config.ts`.
- Update this file when its commands, paths, or prerequisites change.

<!-- Installation follows the README. The development and database script
     names below come from package.json in the pinned snapshot.
     Listing a command does not mean it was run or will pass. -->

## Development and build commands

- Install dependencies: `pnpm install`, as documented in the README.
- Development server: `pnpm dev` (`next dev --turbopack`).
- Production build: `pnpm build` (`next build`).
- Serve a completed production build: `pnpm start` (`next start`).
- There are no `lint`, `typecheck`, or `test` scripts in this snapshot.
  Do not run `pnpm lint`, `pnpm typecheck`, or `pnpm test` as if they exist.

## Environment and database work

- Follow `.env.example`; this project expects `.env`, not `.env.local`
  unless its environment-loading configuration is changed.
- Required variable names documented there are `POSTGRES_URL`,
  `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `BASE_URL`, and `AUTH_SECRET`.
  Keep secret values out of committed files and task reports.
- `pnpm db:setup` runs an interactive setup that writes `.env`, uses the
  Stripe CLI, and can create/start a local Docker database.
- `pnpm db:generate` generates database migration files.
- `pnpm db:migrate` applies migrations to the configured database.
- `pnpm db:seed` writes database records and creates Stripe products/prices.
- `pnpm db:studio` opens the database management interface.
- Run these setup/database commands only for requested environment or
  database work, using the intended development/test services.

<!-- Validation should describe observed evidence. A build command's
     existence is not evidence of a passing build or a test suite. -->

## Validation and handoff

- Inspect the diff for the requested scope and check the relevant code.
- For application changes, run `pnpm build` when dependencies and the
  required environment are available and the check fits the task.
- If build prerequisites are missing, identify them and mark the build
  as not run. If the build fails, report the actual failure.
- Do not run migrations or seed services merely to complete a code review.
- Report changed files, checks actually run, their results, and checks
  not run. State explicitly when no applicable automated test is configured.