AGENTS.md: Persistent Project Memory for Codex CLI

# In the composer input box at the bottom:
/init

# Project Overview (1-3 sentences)
A SaaS subscription management platform. Backend: Node.js + Express + PostgreSQL.
Frontend: React + TypeScript. Stripe handles payments.

## Directory Structure
- `src/api/`      — Express routes and controllers
- `src/services/` — Business logic (no routing here)
- `src/models/`   — Sequelize ORM model definitions
- `src/frontend/` — React SPA
- `tests/`        — Jest unit tests
- `generated/`    — **Auto-generated. Never modify manually.**

## Tech Stack
- Runtime: Node.js 22 LTS
- Database: PostgreSQL 16 (local: Docker Compose)
- ORM: Sequelize v6
- Testing: Jest + Supertest
- CI: GitHub Actions

## Coding Conventions
- ESLint + Prettier (configured in .eslintrc, runs pre-commit)
- All functions must have JSDoc comments if they have parameters or a return value
- Database queries only in `src/services/` — never directly in route handlers
- No `any` types (TypeScript strict mode)

## Common Commands
```bash
npm run dev          # Start dev server (port 3000)
npm test             # Run all tests
npm run db:migrate   # Run database migrations
docker-compose up -d # Start local PostgreSQL
```

## Off-Limits
- Never modify anything in `generated/`
- Never push directly to main — always use a PR
- No hardcoded API keys or secrets in code
- The Stripe webhook handler in `src/api/webhooks.ts` has signature verification logic — understand it before modifying

## Testing Notes
- Unit tests: `npm test` (covers services and models)
- Integration tests need Docker Compose running (`npm run test:integration`)
- New features must include unit tests in the corresponding `tests/` subdirectory

# Project: User Authentication Service
JWT authentication microservice handling user registration, login, and token refresh.
Other microservices call `/auth/verify` to validate tokens.

## Stack
Node.js 22 / Express 5 / TypeScript 5.4 / PostgreSQL / Redis (refresh tokens)

## Key Conventions
- JWT signing key comes from env var `JWT_SECRET` — never hardcode it
- All passwords must be hashed with `bcryptjs`, cost factor 12
- Database connection pool config in `src/db/pool.ts` — don't create new connections
- Error response format: `{ error: string, code: string }`

## Commands
```bash
npm run dev     # ts-node-dev with hot reload
npm test        # Jest
npm run build   # tsc compile to dist/
```

# Project: Data Processing Pipeline
Processes user behavior logs (CSV/Parquet), generates user profile features,
outputs to ClickHouse. Triggered nightly at 2am by Airflow.

## Stack
Python 3.12 / Pandas / Polars / ClickHouse-driver / Poetry

## Conventions
- Format with Ruff (`poetry run ruff format .`)
- Type annotations required on all function parameters and return values
- Prefer Polars over Pandas (faster) — use Pandas only when sklearn compatibility is needed
- `pipelines/` contains only orchestration code, not business logic

## Directories
- `src/processors/` — Data transformation logic
- `src/loaders/`    — I/O (ClickHouse, S3, local files)
- `pipelines/`      — Airflow DAG definitions
- `tests/`          — pytest tests
- `data/samples/`   — Small sample files for local testing (gitignored)

## Commands
```bash
poetry run pytest          # Run all tests
poetry run pytest -x -q    # Fast-fail mode
```

# Project: Full-Stack SaaS Monorepo
pnpm workspace monorepo with web frontend, API backend, and shared library.

## Packages
- `packages/web/`    — Next.js 14 frontend
- `packages/api/`    — Fastify API service
- `packages/shared/` — Shared types and utility functions

## Global Conventions
- Cross-package dependencies go through `@myapp/shared` — no direct source file imports across packages
- `pnpm run build` at root builds all packages in dependency order
- Commit message format: `feat(api): add avatar upload endpoint`

## Off-Limits
- No Node.js-only modules in packages/web
- packages/shared contains only pure functions and types — no I/O

# API Service (Fastify)
REST API for auth, user management, and order processing. PostgreSQL database.

## Conventions
- Routes defined in `src/routes/` — one file per resource
- Database queries only in `src/repositories/`
- All endpoints need Zod schema validation for both input and response
- Error handling via `src/plugins/error-handler.ts` — no ad-hoc try/catch for 500s

## Commands
```bash
pnpm dev           # Start with hot reload
pnpm test          # Vitest
pnpm db:migrate    # drizzle-kit push
```

# My Preferences
- Use English for code comments and variable names
- When explaining a solution, state the conclusion first, then explain why
- Always include error handling in generated code — don't skip it
- If a task is ambiguous, ask clarifying questions before writing code
- Don't auto-install npm/pip packages — tell me what you need first

## Tech Preferences
- Frontend: React + TypeScript (not Vue)
- CSS: Tailwind CSS preferred
- Testing: Vitest preferred over Jest for new projects
- Package manager: pnpm preferred

# .github/workflows/codex-changelog.yml
name: Generate Changelog with Codex
on:
  push:
    branches: [main]

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22' }
      - run: npm install -g @openai/codex
      - run: |
          # codex exec reads AGENTS.md — knows the changelog format rule
          codex exec "Update CHANGELOG.md based on the latest git diff"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}