chore: ignore auto-generated files and update documentation (#417)

- Add *.g.dart and *.mocks.dart to .gitignore
  - Remove previously tracked generated files from repository
  - Update README.md with mandatory setup instructions
  - Enhance CONTRIBUTING.md with generated files workflow
  - Update CLAUDE.md with complete CI/CD documentation

Author: Catrya

.gitignore

@@ -7,6 +7,11 @@
 **/.flutter-plugins-dependencies
 **/.flutter-versions
 
+# Generated files (auto-generated by build_runner and other code generators)
+# These files are regenerated automatically in CI and should not be committed
+*.g.dart
+*.mocks.dart
+
 # IntelliJ related
 .idea/
 *.iml

CLAUDE.md

@@ -188,11 +188,12 @@ When orders are canceled, Mostro sends `Action.canceled` gift wrap:
 - Integration tests in `integration_test/`
 - Mocks generated using Mockito in `test/mocks.dart`
 
-### Mock Files Guidelines  
+### Mock Files Guidelines
 - **Generated file**: `test/mocks.mocks.dart` is auto-generated by Mockito
 - **File-level ignores**: Contains comprehensive ignore directives at file level
 - **Regeneration**: Use `dart run build_runner build -d` to update mocks after changes
 - **No manual editing**: Never manually modify generated mock files
+- **Not in git**: All `*.mocks.dart` files are in `.gitignore` and should NOT be committed
 
 ## Development Guidelines
 
@@ -365,6 +366,10 @@ For complete technical documentation, see `RELAY_SYNC_IMPLEMENTATION.md`.
 - **Commit messages**: Descriptive messages following conventional commits
 - **No Claude references**: Don't include Claude/AI references in commit messages
 - **Code review**: All changes should pass `flutter analyze` before commit
+- **Generated files**: NEVER commit `*.g.dart` or `*.mocks.dart` files - they are in `.gitignore`
+  - These files are automatically regenerated by CI/CD workflows
+  - Only commit source files that you manually write/edit
+  - If you see generated files in `git status`, do NOT stage them
 
 ## Project Context & Recent Work
 
@@ -501,22 +506,47 @@ For complete technical documentation, see `RELAY_SYNC_IMPLEMENTATION.md`.
 - `RELAY_SYNC_IMPLEMENTATION.md` - Complete technical documentation
 
 ### Generated Files (Don't Edit Manually)
-- `lib/generated/` - Generated localization files
-- `*.g.dart` - Generated Riverpod and other code
-- `*.mocks.dart` - Generated Mockito mock files (especially `test/mocks.mocks.dart`)
+- `lib/generated/` - Generated localization files (in `.gitignore`)
+- `*.g.dart` - Generated Riverpod and other code (in `.gitignore`)
+- `*.mocks.dart` - Generated Mockito mock files (in `.gitignore`)
 - Platform-specific generated files
 
 ### Generated Files Best Practices
 - **NEVER manually edit** generated files (`.g.dart`, `.mocks.dart`, `lib/generated/`)
+- **NEVER commit** generated files - they are in `.gitignore` and auto-generated by CI
 - **NEVER add individual ignore comments** to generated files (e.g., `// ignore: must_be_immutable`)
 - **DO NOT modify** `test/mocks.mocks.dart` - it already has file-level ignores
 - **If analyzer issues exist**: Regenerate files instead of adding ignores
 - **Mock files specifically**: Have file-level `// ignore_for_file: must_be_immutable` - don't add more
-- **Regeneration commands**: 
+- **Regeneration commands**:
   - Riverpod: `dart run build_runner build -d`
   - Mocks: `dart run build_runner build -d`
   - Localization: `flutter gen-l10n`
 
+### Generated Files Workflow
+```
+Local Development:
+1. Clone repo → flutter pub get
+2. Generate files → dart run build_runner build -d
+3. Develop → Edit source files only
+4. Re-generate if needed → dart run build_runner build -d
+5. Commit → git add (source files only, NO *.g.dart or *.mocks.dart)
+
+CI/CD Workflow:
+1. Pull request created
+2. CI runs → dart run build_runner build -d (auto-generates)
+3. CI runs → flutter analyze
+4. CI runs → flutter test
+5. All generated files exist for CI, but NOT in git history
+```
+
+**Why This Approach?**
+- ✅ Clean git diffs - only see actual code changes in PRs
+- ✅ No merge conflicts from generated files
+- ✅ Prevents accidental manual edits to generated code
+- ✅ CI ensures files can always be regenerated correctly
+- ✅ Smaller repository size
+
 ## Notes for Future Development
 
 - Always maintain zero Flutter analyze issues
@@ -529,10 +559,12 @@ For complete technical documentation, see `RELAY_SYNC_IMPLEMENTATION.md`.
 
 ### Generated Files - CRITICAL
 - **NEVER** manually edit `test/mocks.mocks.dart` or any `*.g.dart` files
+- **NEVER** commit `*.g.dart` or `*.mocks.dart` files - they are in `.gitignore`
 - **NEVER** add `// ignore: must_be_immutable` to individual classes in generated files
 - **MockSharedPreferencesAsync** already has file-level ignore - don't add more
 - **duplicate_ignore warnings** are caused by adding individual ignores to files with file-level ignores
 - **Solution**: Always regenerate files instead of adding ignore comments
+- **Git workflow**: Generated files exist locally for development, but are NOT tracked by git
 
 ---
 

README.md

@@ -82,14 +82,21 @@ This is a fully-featured mobile application that enables secure, private, and de
    flutter pub get
    ```
 
-3. Generate localization and other required files:
+3. **Generate required files (REQUIRED STEP):**
 
    ```bash
    dart run build_runner build -d
    ```
 
-> **Note:**
-> These commands generate files needed by `flutter_intl` and any other code generators. You must run them after installing dependencies and whenever you update localization files or code generation sources. If you skip this step, you may encounter missing file errors when running the app.
+> **⚠️ IMPORTANT:**
+> This step is **mandatory** and must be run after cloning the repository. It generates code files (`*.g.dart`, `*.mocks.dart`) required for the app to compile and run. These generated files are not committed to the repository and are automatically recreated in CI/CD pipelines.
+>
+> You will need to run this command again whenever you:
+> - Update localization files (`lib/l10n/*.arb`)
+> - Modify files that use code generation (Riverpod providers, JSON serialization, etc.)
+> - Pull changes that affect generated code
+>
+> If you see compilation errors about missing files or imports, run this command again.
 
 ## Running the App
 

docs/CONTRIBUTING.md

@@ -81,19 +81,25 @@ Mostro Mobile is a Flutter app designed with modularity and maintainability in m
    ```sh
    flutter pub get
    ```
-3. **Run the app:**
+3. **Generate required files (CRITICAL STEP):**
+   ```sh
+   dart run build_runner build -d
+   ```
+   This generates code files (`*.g.dart`, `*.mocks.dart`) required for the app to compile. You must run this after cloning and whenever you modify files that use code generation (Riverpod providers, JSON serialization, localization files, etc.).
+
+4. **Run the app:**
    ```sh
    flutter run
    ```
-4. **Configure environment:**
+5. **Configure environment:**
    - Localization: Run `flutter gen-l10n` if you add new strings.
    - Platform-specific setup: See `README.md` for details.
 
-5. **Testing:**
+6. **Testing:**
    - Unit tests: `flutter test`
    - Integration tests: `flutter test integration_test/`
 
-6. **Linting & Formatting:**
+7. **Linting & Formatting:**
    - Check code style: `flutter analyze`
    - Format code: `flutter format .`
 
@@ -111,6 +117,90 @@ Mostro Mobile is a Flutter app designed with modularity and maintainability in m
 
 ---
 
+## Generated Files & Git Workflow
+
+### What Are Generated Files?
+
+This project uses code generation for several purposes:
+- **Riverpod providers** (`*.g.dart`)
+- **JSON serialization** (`*.g.dart`)
+- **Mock classes for testing** (`*.mocks.dart`)
+- **Localization** (`lib/generated/`)
+
+These files are automatically created by running:
+```sh
+dart run build_runner build -d
+```
+
+### Important: DO NOT Commit Generated Files
+
+**Generated files (`*.g.dart`, `*.mocks.dart`) are in `.gitignore` and should NEVER be committed to the repository.**
+
+#### Why?
+- ✅ **Clean PRs**: Only source code changes appear in pull requests
+- ✅ **No merge conflicts**: Generated files won't cause conflicts between branches
+- ✅ **CI regenerates them**: GitHub Actions automatically regenerate these files during builds
+- ✅ **Prevents errors**: No one can accidentally modify generated code manually
+
+### Development Workflow
+
+```
+1. Clone repo
+   └─> flutter pub get
+   └─> dart run build_runner build -d  ← Generate files locally
+
+2. Develop your feature
+   └─> Make code changes
+   └─> If you modify providers/models, re-run build_runner
+
+3. Before committing
+   └─> flutter analyze  ← Must pass with zero issues
+   └─> flutter test     ← All tests must pass
+   └─> git add          ← Add ONLY source files, NOT *.g.dart or *.mocks.dart
+
+4. Create PR
+   └─> CI automatically regenerates all files
+   └─> CI runs analyze and tests
+   └─> Your PR only shows actual code changes
+```
+
+### What If I See Generated Files in My Git Status?
+
+If you see modified `*.g.dart` or `*.mocks.dart` files when running `git status`, **do NOT commit them**. They are already in `.gitignore` and should be ignored automatically. If they appear as modified, it means they were tracked before the `.gitignore` update.
+
+Simply don't stage them:
+```sh
+git status           # See what changed
+git add lib/...      # Add only your actual source files
+git commit           # Generated files won't be included
+```
+
+### Common Scenarios
+
+**Scenario 1: After pulling changes**
+```sh
+git pull
+dart run build_runner build -d  # Regenerate locally
+flutter run                     # App works
+```
+
+**Scenario 2: Modified a model or provider**
+```sh
+# Edit lib/features/settings/settings.dart
+dart run build_runner build -d  # Regenerate affected files
+flutter run                     # Test changes
+git add lib/features/settings/settings.dart  # Add ONLY source file
+git commit -m "feat: add new setting"
+```
+
+**Scenario 3: Compilation errors about missing files**
+```sh
+# Error: "File not found: '*.g.dart'"
+dart run build_runner build -d  # Regenerate
+```
+
+---
+
 ## Contact & Further Resources
 
 - **Main repo:** [https://github.com/MostroP2P/mobile](https://github.com/MostroP2P/mobile)