ADD: Codex AGENTS.md file

Author: rydmike

AGENTS.md

@@ -0,0 +1,24 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `lib/` holds all production Dart source, including `src/` helpers and the public API surface exported by `flex_seed_scheme.dart`.
+- `example/` hosts the Flutter demo and integration playground; update it whenever you add user-facing behaviors so the published sample stays in sync.
+- `test/` keeps regression suites grouped by feature; mirror the folder names from `lib/` so it is obvious where a failing test belongs.
+- `doc_assets/` stores screenshots referenced from `README.md`, while `coverage/` and `build/` are generated outputs — do not hand-edit them.
+- Check `analysis_options.yaml` and `pubspec.yaml` when touching analyzer settings or dependency ranges; both files gate CI.
+
+## Build, Test, and Development Commands
+Use Flutter 3.35+ with Dart 3.9.
+- `flutter pub get` — refreshes dependencies for the package and the example app.
+- `dart format lib test example --fix` — enforces the canonical 2-space indentation before committing.
+- `flutter analyze` — runs the strict analyzer + custom lint bundle from `analysis_options.yaml`.
+- `flutter test --coverage && genhtml coverage/lcov.info -o coverage/html` — executes all suites and refreshes the LCOV report mirrored on Codecov.
+
+## Coding Style & Naming Conventions
+Formatting is always delegated to `dart format`; never hand-align. The repo includes every lint from `all_lint_rules.yaml`, plus `strict-casts`, `strict-inference`, and `strict-raw-types`, so prefer explicit generics and null-safe guards. Expose public symbols in PascalCase, keep members and locals in lowerCamelCase, and prefix private helpers with `_`. Match file names to the primary type (`seed_color_scheme.dart`, `flex_tones.dart`) and keep doc comments focused on reasoning, not usage.
+
+## Testing Guidelines
+Tests rely on `flutter_test`, `package:test`, `matcher`, and custom color utilities under `test/utils`. Name files `<feature>_test.dart`, group cases with `group()` labels, and assert tonal values via the shared matchers to keep diffs readable. Aim to maintain or raise the coverage recorded in `coverage/lcov.info`; add regression tests for every bug fix before requesting review.
+
+## Commit & Pull Request Guidelines
+Follow the existing short, tagged commit style (`FIX:`, `ADD:`, `CHORE:`) and describe the change in imperative mood, optionally referencing `#issue-id`. Each PR should summarize the motivation, list functional changes, mention any screenshots from `example/`, and link related issues. Confirm analyzer + test output in the PR description, and call out any API or behavior risks so reviewers can focus on them.