create AI_template

codex-rules.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Modules
+- Docs live in `docs/`; start with `project-overview.md`, `phases-plan.md`, then `frontend/` and `backend/`. `README.md` summarizes; `DOCS.md` indexes English docs.
+- Agent configs sit in `agents/`; core rules are in `RULES.md`. Use the feature-first layout from `docs/frontend/architecture.md` (`app/`, `features/`, `entities/`, `shared/`) mapped to invoicing, expenses, payroll, compliance.
+
+## Core Stack & Services
+- Frontend: Next.js (TypeScript, App Router), Tailwind CSS, React Query/SWR. Backend: Node.js + TypeScript with Express/Fastify; BullMQ (Redis); Prisma or Drizzle.
+- Data: Postgres (Supabase/RDS) + `pgvector`; include `EventLog.source_agent` (default `balance`) and `Transaction.reasoning_trace` JSONB for explainability.
+- Ops: Dockerized deploys (Render/Fly.io/Railway). Payments: Stripe. Auth: Clerk/Auth.js. LLM: OpenAI API via one helper; model switches must be one-line.
+
+## Build, Test, and Development Commands
+- **Do not run** `npm run dev` (repository rule). Use `npm run build` to verify compilation; rerun after meaningful changes.
+- Add `npm test` / `npm run lint` when tooling is added; document scripts in `README.md` and here. Docs-only changes: just check links.
+
+## Coding Style & Naming
+- Prefer Server Components; mark client components explicitly. Keep code feature-first; put shared utilities in `shared/` and API clients in dedicated modules. Encapsulate finance/LLM integrations behind services.
+- Names in English; use descriptive files. Follow framework defaults; run Prettier/ESLint if configs exist. Keep prompt logic only in the LLM helper.
+
+## Testing Guidelines
+- Layered coverage: unit tests for calculations/rules; component tests for invoicing, expense upload, reconciliation; E2E for onboarding, ingestion, categorization, approval, payment.
+- Name tests `*.spec.ts` / `*.test.ts(x)` alongside code or under `__tests__/`. Mock Stripe, tax/reporting APIs, QuickBooks webhooks, and LLM calls. Validate webhook handling and `reasoning_trace` persistence via backend-facing mocks.
+- Document test commands and required env vars in `README.md`.
+
+## Commit & Pull Request Guidelines
+- Use concise, imperative commit messages. PRs: state purpose/scope, affected modules/docs, validation (`npm run build`, tests), screenshots if UI. Link tasks/issues; note risks (provider edges, missing secrets, migrations). Update docs when behavior or decisions change.
+
+## Agent, API, & Security Notes
+- Review `RULES.md` and relevant agent files before coding. Keep secrets out of the repo; use env vars and never commit provider keys, bank tokens, or webhook secrets.
+- All LLM calls must pass through the shared helper to centralize config and logging.
+- Maintain APIs for transactions, approvals, overrides, reports, rules, billing; expose read-only `/api/events` for downstream agents. Log `TX_INGESTED`, `TX_CATEGORIZED`, `TX_APPROVED`, `RULE_CREATED`, `REPORT_GENERATED` with `source_agent`; persist `reasoning_trace` for auditability.
+- Keep project phase/status aligned across `README.md`, `DOCS.md`, and `docs/phases-plan.md`; update when phase changes.