social-app/apps/AGENTS.md

# Apps Domain Rules

This file governs `apps/**` (Flutter). Keep rules strict, short, and reusable.

## Scope & Precedence

- Inherits root `AGENTS.md` and workspace runtime rules.
- If rules conflict, apply the stricter one.
- Visual language source of truth: `apps/rules/visual_design_language.md`.

## Flutter Directory Contract (Must)

- `apps/lib` only allows these second-level directories: `app/`, `core/`, `data/`, `features/`, `shared/`, `l10n/`.
- `apps/lib/main.dart` is the only allowed root entry file.
- Do not add new second-level directories under `apps/lib` without explicit approval.

## UI Design System (Must)

- **Semantic colors**: always use `Theme.of(context).colorScheme.*` (primary, surface, error, etc.). Never hardcode hex or `Colors.*`.
- **Brand palette colors** (event presets, avatar colors, Eisenhower matrix quadrants): use `Theme.of(context).extension<AppColorPalette>()!.*`.
- **Spacing / Radius**: use `AppSpacing` / `AppRadius` from `design_tokens.dart`. No hardcoded values.
- `AppTheme.light` / `AppTheme.dark` provide complete `ColorScheme` (light + dark). `MaterialApp` wires them via `theme:` / `darkTheme:`.
- If a semantic slot is missing from `ColorScheme`, add it to `AppTheme` — do not bypass `colorScheme` with hardcoded values.

## Reuse & Composition (Must)

- Prefer `apps/lib/shared/widgets/` before adding new components.
- Extract repeated page structures/components; do not duplicate sibling-page scaffolds.
- Detail page top-right actions must use shared action-menu components.
- Destructive confirmations must use project-consistent shared surfaces.

## Interaction & Feedback (Must)

- User feedback: `Toast` / `AppBanner` only.
- Loading indicators: `AppLoadingIndicator` only.
- Form pages should default to keyboard-overlay behavior to avoid full-page layout jumps.

## Agent Chat Protocol (Must)

- Agent chat must follow AG-UI over SSE.
- Lifecycle events are mandatory: `RUN_STARTED` and exactly one of `RUN_FINISHED` or `RUN_ERROR`.
- Text streaming flow must be `TEXT_MESSAGE_START -> TEXT_MESSAGE_CONTENT -> TEXT_MESSAGE_END`.

## HTTP Error Parse Contract (Must)

- Frontend must parse backend errors as RFC7807: `type/title/status/detail/instance` + extension `code/params`.
- Error code registry single source of truth: `docs/protocols/common/http-error-codes.md`.
- Frontend mapping must be based on documented `code` only (`code -> l10n key`), not inferred from `detail` text.
- Any new/changed code requires protocol doc update first, then frontend mapping update.
- Unknown code fallback order: status-generic localized message -> safe generic localized message.

## High-Risk Modules (Must)

### Auth

- `AuthBloc` is the single source of truth.
- 401 invalidation must go through global callback chain; no feature-level token clearing or direct login navigation.

### Home Message Viewport

- Home message auto-scroll/anchor restore must be event-driven.
- Preserve viewport during history prepend and when user is reading above bottom.

### Cache / Repository

- Reads/writes that affect consistency must go through repository layer.
- Cache keys and invalidation policy belong to repository, not UI/Bloc.
- Shared cache infrastructure must live under `apps/lib/data/cache/`; feature modules must not duplicate low-level cache store logic.
- Cross-feature data access must go through `apps/lib/data/repositories/`; do not import another feature's data implementation directly from UI/Bloc.
- Repository instances should be resolved from DI singletons to reuse cache and avoid per-feature re-creation.

## Testing Policy

- Prioritize tests for model parsing, service logic, and high-regression interaction flows.
- Simple static UI changes may skip tests.
- Auth/Home/Cache changes must include targeted regression tests.