sure/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Code: app/ (Rails MVC, services, jobs, mailers, components), JS in app/javascript/, styles/assets in app/assets/ (Tailwind, images, fonts).
• Config: config/, environment examples in .env.local.example and .env.test.example.
• Data: db/ (migrations, seeds), fixtures in test/fixtures/.
• Tests: test/ mirroring app/ (e.g., test/models/*_test.rb).
• Tooling: bin/ (project scripts), docs/ (guides), public/ (static), lib/ (shared libs).

Build, Test, and Development Commands

• Setup: cp .env.local.example .env.local && bin/setup — install deps, set DB, prepare app.
• Run app: bin/dev — starts Rails server and asset/watchers via Procfile.dev.
• Test suite: bin/rails test — run all Minitest tests; add TEST=test/models/user_test.rb to target a file.
• Lint Ruby: bin/rubocop — style checks; add -A to auto-correct safe cops.
• Lint/format JS/CSS: npm run lint and npm run format — uses Biome.
• Security scan: bin/brakeman — static analysis for common Rails issues.

Coding Style & Naming Conventions

• Ruby: 2-space indent, snake_case for methods/vars, CamelCase for classes/modules. Follow Rails conventions for folders and file names.
• Views: ERB checked by erb-lint (see .erb_lint.yml). Avoid heavy logic in views; prefer helpers/components.
• JavaScript: lowerCamelCase for vars/functions, PascalCase for classes/components. Let Biome format code.
• Commit small, cohesive changes; keep diffs focused.

Testing Guidelines

• Framework: Minitest (Rails). Name files *_test.rb and mirror app/ structure.
• Run: bin/rails test locally and ensure green before pushing.
• Fixtures/VCR: Use test/fixtures and existing VCR cassettes for HTTP. Prefer unit tests plus focused integration tests.

Commit & Pull Request Guidelines

• Commits: Imperative subject ≤ 72 chars (e.g., "Add account balance validation"). Include rationale in body and reference issues (#123).
• PRs: Clear description, linked issues, screenshots for UI changes, and migration notes if applicable. Ensure CI passes, tests added/updated, and rubocop/Biome are clean.

Security & Configuration Tips

• Never commit secrets. Start from .env.local.example; use .env.local for development only.
• Run bin/brakeman before major PRs. Prefer environment variables over hard-coded values.