iiEsaywebUIapp/AGENTS.md

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.

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