# AGENTS.md

Guidelines for AI coding agents working in this repository. Follow these guardrails to make safe, minimal, and effective changes.

## Purpose

- Define how agents contribute changes safely to this Flutter mobile app.
- Provide project‑specific commands, structure, and do/don’t rules.
- Ensure consistency with existing code style and workflows.

## Guardrails

- Minimal, targeted changes only; don’t refactor broadly without a clear reason.
- Don’t edit generated files or vendored sources (see “Do Not Edit” list).
- Don’t introduce new dependencies without a clear justification.
- Don’t commit secrets, tokens, or credentials. Use env/config only.
- Don’t change licensing headers or LICENSE.
- Prefer surgical fixes over sweeping rewrites; match existing patterns.
- Update or add documentation when behavior changes.

## Project Overview

- Stack: Flutter/Dart mobile app for interacting with Open‑WebUI.
- Notable packages: `flutter_riverpod`, `dio`, `freezed`, `json_serializable`, `flutter_secure_storage`.
- Codegen: `build_runner` (freezed/json_serializable) and Flutter gen‑l10n.
- State management: Riverpod.

## Key Commands

Run from repository root.

```bash
# Install deps
flutter pub get

# Generate code (freezed/json_serializable)
flutter pub run build_runner build --delete-conflicting-outputs

# Localization codegen (auto during run/build)
flutter gen-l10n

# Analyze & format
flutter analyze
dart format .

# Run app (pick a platform)
flutter run -d ios
flutter run -d android

# Build release artifacts
flutter build apk --release
flutter build appbundle --release
flutter build ios --release
```

## Repository Structure (high‑level)

```
lib/
  core/         # models, services, providers, utils
  features/     # feature‑scoped UI/logic (auth, chat, server, settings)
  l10n/         # ARB + generated localization
  shared/       # shared widgets, theme, utils
```

Follow existing folder conventions when adding code. Prefer feature folders for new UI or logic.

## Code Generation

- Freezed/JSON: run `flutter pub run build_runner build --delete-conflicting-outputs` after changes to models/DTOs.
- Localization: edit ARB files and run `flutter gen-l10n` (or `flutter run`). See `docs/localization.md`.

## Do Not Edit (Generated/Vendored)

- `build/`
- `lib/l10n/app_localizations*.dart` (generated by gen‑l10n)
- `openwebui-src/` (vendored upstream; only update by syncing from upstream, not ad‑hoc edits)
- Any other generated files created by build tools

If a change appears necessary to a generated file, modify its source (e.g., ARB or model) and regenerate.

## Patterns & Style

- Riverpod: prefer providers/notifiers consistent with existing usage.
- Networking: use the shared `Dio` provider and interceptors if present.
- Models: use `freezed`/`json_serializable` patterns matching current models.
- UI: reuse shared widgets where possible; keep styling consistent.
- Null safety: follow strict null‑safety conventions already in the codebase.
- Lints: keep `flutter analyze` clean; fix warnings you introduce.

## Validation Checklist (before opening a PR)

- Ran `flutter pub get` and codegen commands.
- App compiles and runs on at least one target (`ios` or `android`).
- `flutter analyze` passes with no new issues.
- Updated docs/README if behavior or setup changed.
- No changes to generated/vendored files.
- No secrets, tokens, or credentials added to the repo.

## Localization

- Add/edit strings in `lib/l10n/app_en.arb`; mirror in other `app_<lang>.arb` as needed.
- Provide `@key` metadata with descriptions and placeholders.
- Don’t edit `app_localizations*.dart` directly. See `docs/localization.md`.

## Releases

- Primary release flow is CI‑driven. A helper exists at `scripts/release.sh`.
- Don’t bump versions casually. If required, coordinate and follow `scripts/release.sh` prompts.

## When Adding Dependencies

- Justify why it’s needed and whether an existing dependency covers the use case.
- Prefer well‑maintained packages with strong adoption.
- Keep `pubspec.yaml` tidy; avoid overlapping functionality.

## When Touching Platform Code

- iOS: ensure entitlements, Info.plist keys, and signing remain valid.
- Android: check permissions, minSdk (23+), and manifest changes.
- Test basic run on the affected platform.

## Security & Privacy

- Credentials must use platform secure storage (`flutter_secure_storage`).
- Avoid logging sensitive information.
- Network calls should respect the configured Open‑WebUI endpoint and headers.

## PR Expectations

- Keep diffs focused; include a short rationale in the PR description.
- Link related issues or TODOs when possible.
- Include screenshots or short clips for UI changes.

## If You’re Unsure

- Prefer creating a small draft PR or documenting assumptions inline with the PR description rather than pushing risky changes.
- When in doubt about ownership or expectations, open a GitHub issue first.

---

Thank you for keeping changes safe, minimal, and consistent. This helps maintain velocity and quality for the Conduit app.