From bf1a310c286e39664908ca989ffda0d3cea4ef3c Mon Sep 17 00:00:00 2001
From: Dionizio Ferreira <dionizioaf@gmail.com>
Date: Fri, 28 Nov 2025 01:30:09 -0300
Subject: [PATCH] feat: add AI coding assistant instructions and update Node.js
 version requirement in README

---
 .github/copilot-instructions.md | 58 +++++++++++++++++++++++++++++++++
 .nvmrc                          |  1 +
 README.md                       |  2 +-
 3 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .nvmrc

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..e590a7f
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,58 @@
+# AI Coding Assistant Instructions for Opensheets
+
+## Project Overview
+
+Opensheets is a self-hosted personal finance management application built with Next.js 16, TypeScript, PostgreSQL, and Drizzle ORM. It provides manual transaction tracking, account management, budgeting, and financial insights with a Portuguese interface.
+
+## Architecture
+
+- **Frontend**: Next.js App Router with React 19, shadcn/ui components, Tailwind CSS
+- **Backend**: Server actions in Next.js, API routes for auth/health
+- **Database**: PostgreSQL with Drizzle ORM, schema in `db/schema.ts`
+- **Auth**: Better Auth (OAuth + email magic links)
+- **Deployment**: Docker multi-stage build, health checks
+
+## Key Patterns
+
+- **Server Actions**: Use `"use server"` for mutations, validate with Zod schemas, handle errors with `handleActionError`
+- **Database Queries**: Use Drizzle's query API with relations, e.g., `db.query.lancamentos.findMany({ with: { categoria: true } })`
+- **Authentication**: Import from `lib/auth/server`, redirect on failure
+- **Revalidation**: Call `revalidateForEntity("lancamentos")` after mutations
+- **Portuguese Naming**: DB fields like `nome`, `tipo_conta`, `pagador` (payer), `lancamento` (transaction)
+- **Component Structure**: Feature-based folders in `components/`, shared UI in `components/ui/`
+
+## Development Workflow
+
+- **Start Dev**: `pnpm dev` (Turbopack), `docker compose up db -d` for DB
+- **Database**: `pnpm db:push` to sync schema, `pnpm db:studio` for visual editor
+- **Build**: `pnpm build`, `pnpm start` for production
+- **Docker**: `pnpm docker:up` for full stack, `pnpm docker:logs` for monitoring
+
+## Common Tasks
+
+- **Add Transaction**: Create server action in `app/(dashboard)/lancamentos/actions.ts`, validate with Zod, insert via Drizzle
+- **New Entity**: Add to `db/schema.ts`, define relations, create CRUD actions in `lib/[entity]/actions.ts`
+- **UI Component**: Use shadcn/ui, place in `components/[feature]/`, export from `components/ui/`
+- **API Route**: Add to `app/api/`, use `getUserSession()` for auth
+
+## Conventions
+
+- **Imports**: Absolute paths with `@/`, group by external/internal
+- **Error Handling**: Return `{ success: false, error: string }` from actions
+- **Currency**: Store as decimal strings (e.g., "123.45"), convert to cents for calculations
+- **Periods**: Format as "YYYY-MM", use `parsePeriodParam()` for URL params
+- **Notifications**: Send emails via `sendPagadorAutoEmails()` for payer updates
+
+## External Integrations
+
+- **Better Auth**: Config in `lib/auth/config.ts`, session handling
+- **Drizzle**: Migrations in `drizzle/`, studio at `pnpm db:studio`
+- **AI Features**: Use `@ai-sdk/*` for insights, configured in environment
+- **Email**: Resend for notifications, configured via `RESEND_API_KEY`
+
+## File Examples
+
+- Schema: `db/schema.ts` (relations, indexes)
+- Actions: `app/(dashboard)/lancamentos/actions.ts` (CRUD with validation)
+- Components: `components/lancamentos/page/lancamentos-page.tsx` (client component)
+- Utils: `lib/lancamentos/page-helpers.ts` (data transformation)
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 0000000..dc0bb0f
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+v22.12.0
diff --git a/README.md b/README.md
index ca3018f..937c69f 100644
--- a/README.md
+++ b/README.md
@@ -206,7 +206,7 @@ Esta é a **melhor opção para desenvolvedores** que vão modificar o código.
 
 #### Pré-requisitos
 
-- Node.js 22+ instalado
+- Node.js 22+ instalado (se usar nvm, execute `nvm install` ou `nvm use`)
 - pnpm instalado (ou npm/yarn)
 - Docker e Docker Compose instalados