diff --git a/AGENTS.md b/AGENTS.md
index 9404256..5965135 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,23 +1,143 @@
-# Conduit - Flutter Mobile App for Open-WebUI
+# 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.
 
-## Build & Test Commands
 ```bash
-flutter pub get                                    # Install dependencies
-flutter pub run build_runner build --delete-conflicting-outputs  # Generate code
-flutter analyze                                     # Run static analysis
-flutter run -d ios/android                        # Run debug build
-flutter build apk --release                       # Build Android release
-flutter build ipa --release                       # Build iOS release
+# 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
 ```
 
-## Code Style Guidelines
-- **State Management**: Use Riverpod providers in `providers/` folders
-- **Architecture**: Follow clean architecture - `core/`, `features/`, `shared/`
-- **Imports**: Group by package/relative, use absolute paths for project files
-- **Models**: Use Freezed for data classes with `.freezed.dart` and `.g.dart` generated files
-- **Error Handling**: Use ApiErrorHandler and error interceptors, avoid print statements
-- **Naming**: snake_case files, PascalCase classes, camelCase methods/variables
-- **Async**: Prefer async/await over raw Futures, handle errors with try-catch
-- **Widgets**: Separate presentation (widgets/) from business logic (services/)
-- **UI Design**: Use AppTheme colors/styles and ConduitThemeExtension for consistent design
-- **Dependencies**: Check pubspec.yaml before adding packages - prefer existing solutions
\ No newline at end of file
+## 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.
+