# Working with a coding agent

Every generated app has a guide for the coding agents that work on it, at the root of the app:

| File | What it holds |
| --- | --- |
| `AGENTS.md` | The guide: what the code of the app does not show. |
| `CLAUDE.md` | One line, `@AGENTS.md`, which gives the same guide to the agents that read `CLAUDE.md` instead. |

The guide is for an agent to read before it changes anything. It tells the rules of this app, so that you do not have to explain them in each session.

## What the guide says

The code of an app shows what it does, and an agent can read it. The guide holds what the code does not show: a rule that holds across files, an order, what not to do and what to do instead, a placeholder, a step that needs a person. Setup that needs a person or an account, such as a Firebase project, stays in the `README.md` of the app.

The guide starts with a short introduction and has a section for each part of the app that has notes for agents. The section of the app entry comes first, and the others follow in the order of their headings. This is the section "Preferences" of an app with [`shared_preferences`](https://doc.saymyframe.com/modules/shared-preferences.md):

> - `AppPreferences` in `lib/core/preferences/app_preferences.dart` remembers the settings of the app between its launches, such as the theme mode. It is not encrypted: never save a token, a password, an API key or an encryption key in it.
> - To remember a setting, write a function that takes the `AppPreferences` and add it to `_restorers` in that file. In it, read the setting, put it into the state that the widgets listen to, and keep the preferences in that state for its writes. The function awaits nothing, and keeps the current value when nothing is saved.
> - Name a key `<owner id>.<setting>`, such as `theme.mode`, where the owner is the feature or the concern whose code keeps the setting.
> - In the code of the app, do not call `createAppPreferences()` or `initPreferences()`. `bootstrap()` opens the preferences, and code gets them as the argument of its function in `_restorers`, or, with a DI container in the app, from the container. Widgets use the state and do not touch the preferences. A test may call both: `initPreferences()` opens the preferences again, as the next launch of the app does, and `createAppPreferences()` returns them.
>
> With `shared_preferences`:
>
> - In `lib/`, only `lib/core/preferences/shared_app_preferences.dart` imports the package. Other code uses `AppPreferences`.
> - A number is read only as the type that it was saved as: `getDouble()` returns `null` for a key with an `int`, and `getInt()` for a key with a `double`.
> - In a test that runs `bootstrap()`, first set `SharedPreferencesAsyncPlatform.instance = InMemorySharedPreferencesAsync.empty()`. Without it, opening the preferences throws. Both names are from the package `shared_preferences_platform_interface`: add it as a dev dependency.
> - `pubspec.yaml` keeps `shared_preferences_android` at 2.5.2 or later. With 2.5.0 and 2.5.1, a release build fails to open the preferences on Android, because R8 renames Kotlin classes that the package looks up by name. Before you change the constraint, check that a release build of the app starts on Android.

The section of a role has two parts. First comes what holds whichever module provides the role, such as how code remembers a setting. Then the module that provides the role adds what comes with it, here after the line "With `shared_preferences`:". Replace the module with another provider of the role, and only the second part changes.

## The sections of an app

A section is in the guide only when the app has what it describes. The table names the built-in module that brings each section:

| Section | In an app with | What it tells |
| --- | --- | --- |
| App entry | every app | The order of `main()`, the phases of `bootstrap()`, where shared code and features go, that `StatusBarIcons` asks for the icons of the status bar around every screen, and what a `flutter` command builds without `--flavor`. In an app with [steps by hand](https://doc.saymyframe.com/guides/smf-create.md#steps-by-hand), also that only you do them: an agent points you to the section "Finish the setup" of the README instead of trying them. `flutter_core` adds where each flavor is in the native projects, and the commands to run after a change, the root widget with the one `MaterialApp` of the app, where the test of a file goes, and where the entitlements of the iOS app are. |
| Analytics | [`firebase_analytics`](https://doc.saymyframe.com/modules/firebase-analytics.md) | That code records what users do through `AnalyticsService` and never through the SDK of a provider, where it gets the service, and how to add a provider. In an app with a router, the module adds that screen views need no code. |
| App icon | [`launcher_icons`](https://doc.saymyframe.com/modules/launcher-icons.md) | Which images the icon comes from, and that an agent changes those and not what is made from them. The module adds the command, and what an agent does not run or add. |
| Authentication | [`firebase_auth`](https://doc.saymyframe.com/modules/firebase-auth.md) | That code signs in, up and out only through `appSession`, how it shows a failure, that the mode gates nothing on its own and which guard keeps a user from what, and where the data of a guest moves. It also tells where the ways to sign in with an identity provider are listed, what a tap on one of their buttons does with `appSession.signInWith`, what a deletion asks of them, and what `AccountSession.issuers` lists. The module adds which file is on Firebase Authentication, where a code of Firebase gets its reason, that the ways to sign in are enabled in the Firebase project, and that an agent runs the script that enables them only when asked. In an app with Google sign-in, it adds what its script does for Google, and with Sign in with Apple, that the key of Apple never goes into the app. |
| CI | [`github_actions`](https://doc.saymyframe.com/modules/github-actions.md) | That CI runs the commands of the section "Continuous integration" of the README, so an agent keeps them passing and runs them before it finishes a change, and what `tool/write_env.dart` does. The module adds where the jobs are, how a new key reaches a build, how a value reaches a command, and how the actions are pinned. |
| Crash reporting | [`firebase_crashlytics`](https://doc.saymyframe.com/modules/firebase-crashlytics.md) | Which function reports the errors that nothing handles, how code reports an error that it catches, and how to add a provider. The module adds that `tool/configure_firebase.dart` keeps the build phase working for `flutter build ipa`, and what to run after `flutterfire configure` by hand. |
| Dependency injection | [`get_it`](https://doc.saymyframe.com/modules/get-it.md) | What a service is, where the services are registered, and that only the composition file of a feature resolves them. The module adds how its file registers a service. |
| Events | [`event_bus`](https://doc.saymyframe.com/modules/event-bus.md) | What an event is, where code gets the one event service of the app, and what events are for. The module adds when a listener gets an event. |
| Firebase | [`firebase_core`](https://doc.saymyframe.com/modules/firebase-core.md) | That `lib/firebase_options_of_flavor.dart` picks the options by the flavor of the build, that the options of a flavor are a placeholder until `tool/configure_firebase.dart` writes them, that an agent runs that script only when asked and never `flutterfire configure`, and what a test that starts the app needs. |
| Google sign-in | [`google_sign_in`](https://doc.saymyframe.com/modules/google-sign-in.md) | Which file asks Google and how it starts the package, which errors become which reason, what the icon shows, and what a test replaces to sign in with Google. |
| Home | [`home`](https://doc.saymyframe.com/modules/home.md) | What the start screen is for, and where the image that it shows is declared. |
| Layout | [`bottom_tabs`](https://doc.saymyframe.com/modules/bottom-tabs.md) | Who creates the shell of the main navigation, what a destination is, how its label follows the language, how to add one, and how code reaches a destination from a page shown over the main navigation. The module adds that it draws its bar itself, when the bar is hidden, how many destinations it should have, where the bar takes its colors from, and what a tab says to a screen reader. |
| Localization | [`gen_l10n`](https://doc.saymyframe.com/modules/gen-l10n.md) | How code reads a text, where the languages of the app are, how code changes the language, and what a new language needs. The module adds where the texts are, how to add one, and the command to run after a change. |
| Notifications | [`local_notifications`](https://doc.saymyframe.com/modules/local-notifications.md) | How code shows and schedules a notification and which ids it takes, how it asks for the permission and where the app asks, how it handles a tap, and the small icon of Android. The module adds which file is on flutter_local_notifications, how to add a channel, why a scheduled notification is inexact, and what its native files and a test need. |
| Onboarding | [`onboarding`](https://doc.saymyframe.com/modules/onboarding.md) | That no code navigates to the onboarding or away from it, where its pages and its steps are and what the screen keeps around them, that the animations of a page end, how code finishes the onboarding and starts it again, and what a test of another screen does first. |
| Onboarding screen | [`onboarding`](https://doc.saymyframe.com/modules/onboarding.md) | What a step of the onboarding is, how to add one, how a step that shows a screen of its own pushes it over the onboarding, and that skipping the onboarding skips its steps. |
| Paywall | [`paywall`](https://doc.saymyframe.com/modules/paywall.md) | Where the paywall and the screen of the subscription are and which guard shows them, that no screen closes itself or navigates after a purchase or a restore, how to sell from a button and keep a screen for users with premium access, which files are the look and which the state, where the plans get their words and a failure its text, what the links need in `.env`, whose a purchase before a sign-in is, and what a widget test minds while a call is on its way. By the state manager of the app, it adds where the state of a screen is and how a widget reads the access, and in an app with an onboarding, how its step shows the paywall and who closes it. |
| Preferences | [`shared_preferences`](https://doc.saymyframe.com/modules/shared-preferences.md) | What the preferences are for, what never goes into them, and how code remembers a setting. The module adds how it reads numbers, what a test that runs `bootstrap()` needs, and why `pubspec.yaml` keeps `shared_preferences_android` at 2.5.2 or later. |
| Purchases | [`revenuecat`](https://doc.saymyframe.com/modules/revenuecat.md) | What the access of the user is and where a widget reads it, how code gets the plans, buys, restores and shows a failure, what a screen that sells shows, how a screen is kept for users with premium access, what the app does while purchases are not set up, and which functions are not for the code of the app. In an app with sign-in, also whose the purchases are, and in an app with a settings screen, where the restore is. The module adds which file is on purchases_flutter, that the premium access is the entitlement `premium`, which API key a build takes and why, that nothing calls RevenueCat before it is configured, how a grant made on the dashboard reaches the app, and what a test answers in place of the package. |
| REST API | [`dio`](https://doc.saymyframe.com/modules/dio.md) | How code makes a request through `appRest` and turns the body into a type, how it shows a failure, what repeats, how a call ends, and what a test needs. In an app with sign-in, which requests carry the token and what a 401 does. The module adds where an interceptor goes and what it may do. |
| Push messages | [`firebase_messaging`](https://doc.saymyframe.com/modules/firebase-messaging.md) | Where the address of the device is and what to do with it, how a message shows in the foreground, how code handles a tap, and what the app does not handle. The module adds which file is on firebase_messaging, where the address comes from, why it sets the presentation options of iOS, and that the app never asks for the permission through the package. |
| Router | [`go_router`](https://doc.saymyframe.com/modules/go-router.md) | How code navigates with `context.nav`, the three places that a route is in, and the types of its values. In an app with [guards](https://doc.saymyframe.com/guides/navigation.md#guards), also where the guards are, what tells a gate from a guard for some routes, how code adds either, and that a screen neither closes itself nor navigates after it changed a guard. The module adds how its file writes a route and, in an app with a layout, where a destination of the main navigation goes and that the router creates the main navigation anew. |
| Settings screen | [`settings`](https://doc.saymyframe.com/modules/settings.md) | What an entry of the screen is and how to add one. The module adds where its screen is, what it shows with entries and without, and how code opens it in an app without a main navigation. |
| Sign in with Apple | [`apple_sign_in`](https://doc.saymyframe.com/modules/apple-sign-in.md) | Which file asks Apple and what it returns, that Apple gives the name only at the first sign-in, which errors become which reason, the entitlement, and what a test sets to sign in with Apple. |
| Sign-in | [`sign_in`](https://doc.saymyframe.com/modules/sign-in.md) | Where the screens of the sign-in are and which guards show them, that a screen neither closes itself nor navigates after a sign-in or a sign-out, which files are the look and which the state, where a failure gets its text, what a widget test minds while a call is on its way, where the buttons of the ways to sign in come from, and where the screen of the account and its entry are. By the state manager of the app, it adds where the state of a screen is and how a widget reads who uses the app. |
| Splash screen | [`native_splash`](https://doc.saymyframe.com/modules/native-splash.md) | Which images the screen comes from, and that an agent changes those and not what is made from them. The module adds the command and what it rewrites. |
| State management | [`bloc`](https://doc.saymyframe.com/modules/bloc.md) or [`riverpod`](https://doc.saymyframe.com/modules/riverpod.md) | How a screen with state is written with the state manager of the app: where its state is, how the screen passes it on to a view, where state that several screens read goes, what the state checks after a call that it awaited, and that a widget talks only to that state, never to a service or a DI container. |
| Theme | [`material_theme`](https://doc.saymyframe.com/modules/material-theme.md) | Where the look of the app is, how code changes and reads the theme mode, and where a screen takes its colors from. The module adds how its file creates both themes, where their colors and their font are, where a text field takes its look from, and what a change of the file must keep. |
| Values in .env | [`dart_define`](https://doc.saymyframe.com/modules/dart-define.md) | How code reads a value of `.env` through `AppEnv` and handles `null`, that no secret goes into `.env`, and what a new key needs. The module adds the commands with `--dart-define-from-file=.env`, the run configurations that pass it, that `flutter run` starts again after an edit of `.env`, and how the getter of a new key reads its value. |

## Where the sections come from

The app entry role generates both files in every app, whichever module provides the role. The roles and the modules of the app contribute the sections, as they contribute start-up code: a module knows nothing of the notes of the other modules, and `smf create` puts the sections together. So the guide of an app covers only what that app has.

SMF checks the paths that a guide names. In its tests, each file or directory that a note names in backticks below a top-level directory of a Flutter project, such as `lib/` or `android/`, and each path to a Dart file, must be in the app of that guide. A module author reads more in [Notes for coding agents](https://doc.saymyframe.com/extending/infrastructure-module.md#notes-for-coding-agents).

## Keep it true

The guide is a file of your app, like the rest of the code. Nothing writes it again, so it is right only as long as you keep it so, and its first paragraph asks the agent to do its part: "When you change what a section describes, change the section too."

- When you change how a part of the app works, such as where its files are or which function code must call, change the section of that part.
- When you add a part of your own with a rule that the code does not show, add a section for it under a heading of its own.
- Keep to what the code does not show. A note that repeats the code makes the other notes harder to find.

## The documentation for your agent

Every page of this documentation is also in Markdown, at its URL with `.md`, such as https://doc.saymyframe.com/guides/theme.md. [llms.txt](https://doc.saymyframe.com/llms.txt) lists the pages with a line about each, and [llms-full.txt](https://doc.saymyframe.com/llms-full.txt) has all of them in one file. An agent may know SMF from an older version, or not at all. Give it one of these before it picks the modules of an app or writes the command of `smf create`.
