Initial project scaffold and agent docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

.cursor/chat-context-template.md

@@ -0,0 +1,31 @@
+# Copy into a new Cursor chat (fill brackets, delete this line)
+
+## Session
+- Type: [learning | implementation | debug]
+- Phase: [e.g. Phase 4 — Context discipline]
+- Project: financeOne (`/home/duarte/development/financeOne`)
+
+## Stack
+- Next.js, React, TypeScript, Tailwind (planned — see README)
+- Verify: `npm run lint && npm test` (when scaffold exists)
+
+## How I want replies
+- Concise and direct; no fluff or long summaries unless I ask.
+- Ask me anything unclear (scope, constraints, tradeoffs) before big changes.
+
+## My profile
+- Senior dev/architect; learning Cursor.
+- Minimal diffs; match existing patterns; short tradeoff notes when choices matter.
+- Do not commit/push unless I ask; no secrets in chat.
+
+## Goal (this chat)
+[One sentence — what “done” looks like]
+
+## Already decided
+- Repo prepared: README, AGENTS.md, `.cursor/rules/`, `.gitignore`, `.env.example`
+
+## Attachments
+@README.md @AGENTS.md @.cursor/rules/
+
+---
+[Phase title and your questions below]

.cursor/rules/project-core.mdc

@@ -0,0 +1,20 @@
+---
+description: Core FinanceOne project standards for all work
+alwaysApply: true
+---
+
+# FinanceOne — core
+
+## Responses
+
+- Concise, direct, plain language. No filler or fancy phrasing.
+- Ask 1–3 specific questions when scope, constraints, or approach is unclear — do not guess on large changes.
+
+## Code
+
+- Minimal, focused diffs; match existing style and layout.
+- Read `AGENTS.md` and `README.md` before multi-file edits.
+- No commit, push, or git config changes unless the user explicitly asks.
+- No secrets in repo; `.env.local` locally; names in `.env.example` only.
+- Money: integer minor units or a decimal library — not JS `number` for currency math.
+- Prefer `@` references over whole-repo search when the task names files or areas.

.cursor/rules/typescript.mdc

@@ -0,0 +1,13 @@
+---
+description: TypeScript conventions for FinanceOne
+globs: **/*.{ts,tsx}
+alwaysApply: false
+---
+
+# TypeScript
+
+- Prefer explicit return types on exported functions and API handlers.
+- Avoid `any`; use `unknown` and narrow, or small domain types.
+- Use `import type` for type-only imports.
+- Colocate types with features; shared types in a dedicated `types` module when reused.
+- Handle errors explicitly; do not swallow failures without logging or user-visible feedback.

.cursor/rules/web-ui.mdc

@@ -0,0 +1,13 @@
+---
+description: React and Next.js UI patterns for FinanceOne
+globs: **/*.{tsx,css}
+alwaysApply: false
+---
+
+# Web UI
+
+- Next.js App Router: default to Server Components; add `"use client"` only for interactivity.
+- Accessible markup: labels on inputs, semantic headings, keyboard-friendly controls.
+- Tailwind: reuse spacing and color patterns from nearby components; avoid one-off magic values when a token exists.
+- Forms: validate on client for UX and on server for security; show clear error messages.
+- Loading and empty states for lists (accounts, transactions).

.env.example

@@ -0,0 +1,10 @@
+# Copy to .env.local and fill in. Do not commit real values.
+
+# App
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Database (when added)
+# DATABASE_URL=
+
+# Auth (when added)
+# AUTH_SECRET=

.gitignore

@@ -0,0 +1,40 @@
+# Dependencies
+node_modules/
+
+# Build / framework
+.next/
+out/
+dist/
+build/
+.turbo/
+.vercel/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Logs and debug
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Testing
+coverage/
+.nyc_output/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# TypeScript
+*.tsbuildinfo
+
+# Misc
+.cache/
+*.pem

AGENTS.md

@@ -0,0 +1,58 @@
+# FinanceOne — agent guide
+
+For Cursor Agent and other coding agents in this repo.
+
+## How to respond
+
+- **Be concise**: short paragraphs, bullets when listing. Match reply length to the task.
+- **Be direct**: state facts, decisions, and next steps. No filler, hype, or “great question” openers.
+- **No fluff**: skip long preambles, repeated summaries, and engagement closers unless the user asks.
+- **Ask when it helps**: if scope, constraints, or “done” is unclear — or there are multiple valid approaches — ask **1–3 specific questions** before a large change. Do not guess and build the wrong thing.
+- **Say what you need**: missing file paths, env, repro steps, or preferences? Ask once, clearly.
+
+## Project
+
+Personal finance web app. Small, reviewable diffs; match existing patterns.
+
+## Before you change code
+
+1. Read `README.md` for stack and verify commands.
+2. Stay within the user’s request; no drive-by refactors.
+3. Prefer `@` file references over whole-repo search when the task names files or areas.
+
+## Conventions
+
+- **TypeScript**: strict types; avoid `any` unless justified in a comment.
+- **React / Next.js**: App Router; server components by default; `"use client"` only when needed.
+- **Styling**: Tailwind utilities; match nearby components.
+- **Money**: minor units (cents) or a decimal library — never raw floats for currency.
+- **Secrets**: never commit `.env`, keys, or tokens; names only in `.env.example`.
+
+## Verification
+
+After substantive changes (when `package.json` exists):
+
+```bash
+npm run lint
+npm test
+```
+
+UI changes: note manual checks or use browser tooling if configured.
+
+## Git
+
+- Commit only when the user explicitly asks.
+- No force-push to `main` / `master`.
+- Do not skip git hooks unless the user asks.
+
+## Domain
+
+- **Accounts**: cash, credit, investment — clear balance semantics each.
+- **Transactions**: signed amounts; categories/tags optional but consistent.
+- **Reports**: aggregate from stored transactions; document timezone (UTC vs user locale).
+
+## Out of scope unless requested
+
+- New major dependencies
+- Large architectural rewrites
+- CI/CD or deployment changes

README.md

@@ -0,0 +1,69 @@
+# FinanceOne
+
+Personal finance web application — budgets, accounts, transactions, and reporting.
+
+## Stack (planned)
+
+| Layer | Choice |
+|-------|--------|
+| Runtime | Node.js 20+ |
+| Framework | Next.js (App Router) |
+| Language | TypeScript |
+| Styling | Tailwind CSS |
+| Package manager | npm |
+
+Adjust this table when the scaffold is generated or the stack changes.
+
+## Prerequisites
+
+- Node.js 20 or later
+- npm 10+
+
+## Getting started
+
+The application scaffold is not generated yet. After `package.json` exists:
+
+```bash
+npm install
+cp .env.example .env.local   # fill values locally; never commit secrets
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Scripts
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Local development server |
+| `npm run build` | Production build |
+| `npm run start` | Run production build |
+| `npm run lint` | ESLint |
+| `npm test` | Unit / integration tests |
+
+Scripts appear in `package.json` once the app is scaffolded.
+
+## Environment variables
+
+See [.env.example](.env.example). Copy to `.env.local` for local development.
+
+## Project layout (target)
+
+```
+financeOne/
+├── src/                 # application source (after scaffold)
+├── public/
+├── .cursor/rules/       # Cursor agent guardrails
+├── AGENTS.md            # agent workflow and conventions
+└── README.md
+```
+
+## Cursor / agents
+
+- Read [AGENTS.md](AGENTS.md) first: concise replies, ask when unclear, then conventions and verify steps.
+- Rules: `.cursor/rules/`. Chat starter: `.cursor/chat-context-template.md`.
+- Verify: `npm run lint` and `npm test` when available.
+
+## License
+
+Private / unlicensed unless stated otherwise.