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).

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.

Planning artifacts for the Hotwire Native prototype live in docs/hotwire_native_prototype_plan.md. Review and update the checklist before starting native-wrapper work.
Implementation spikes for the native wrappers must originate from the feature/hotwire-native-prototype branch cut off the latest main once planning is approved.
Keep PWA regressions in mind: always confirm changes behave in both the web PWA and Turbo Native contexts.
Turbo Native requests are detected via TurboNative::Controller; when you add new controllers ensure they inherit from ApplicationController (or include the concern) so the :turbo_native layout variant is applied automatically.
The native layout exports navigation metadata through ApplicationHelper#turbo_native_navigation_payload and the turbo_native_bridge Stimulus controller. When adding tabs or nav links, update the helper to keep web and native shells in sync.

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.

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.

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.

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.