4.0.1: README rewrite, rendered screenshots, AI assistant guide, and five fixes

.gitignore

@@ -32,3 +32,6 @@ build/
 # FVM Version Cache
 .fvm/
 .fvmrc/
+
+# Screenshot harness intermediates (tool/screenshots); only the framed WebP files are committed.
+doc/readme/raw/

.pubignore

@@ -0,0 +1,46 @@
+# pub reads this file INSTEAD of the root .gitignore, so it repeats those rules.
+
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+.vscode/
+.history/
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+.packages
+build/
+
+# FVM Version Cache
+.fvm/
+.fvmrc/
+
+# Screenshot harness intermediates (tool/screenshots); only the framed WebP files are committed.
+doc/readme/raw/
+
+# Repository-only material: the README hero image and the screenshot harness.
+# The README resolves its images against the GitHub repository, and the
+# pub.dev gallery uses screenshots/, which does ship.
+doc/readme/
+tool/
+coverage/

CHANGELOG.md

@@ -1,3 +1,61 @@
+## 4.0.1
+
+### Fixed
+
+- **`showMapLocationPicker` threw when an existing `onNext` popped with a
+  result.** Code carried over from 3.x as `onNext: (r) => Navigator.pop(context, r)`
+  popped the route with a `GeocodingResult`, but the route was typed
+  `PickedPlace`, so it failed with an assertion in debug and a `TypeError` in
+  release — on exactly the migration path the migration guide recommends. Any
+  popped value is now accepted, and the future still resolves to the
+  `PickedPlace` the user confirmed.
+- **A geocoder given to `MapLocationPickerController` was silently discarded.**
+  `MapLocationPicker(controller: c)` without its own `geoCodingConfig` replaced
+  the one configured on `c` with the default, so a proxy, custom HTTP client or
+  test fake stopped being used as soon as the picker mounted. A geocoder passed
+  to the widget still takes precedence.
+- The back button and the search field now share one row, so they are centred
+  on the same line; they previously sat at different heights.
+- `bottomCardTitle` now starts at the same left edge as the address below it.
+- The default search hint is now "Search for a place or address". The previous
+  text was clipped mid-sentence whenever the back button was shown.
+
+### Documentation
+
+- README rewritten: a step-by-step getting-started guide, a section for each
+  feature, a configuration reference, and troubleshooting. Every factual
+  claim was then audited against the source, which corrected several errors
+  carried over from the old README:
+  - The iOS `AppDelegate` snippet didn't match current Flutter templates.
+  - Android was listed as API 21, when `google_maps_flutter` needs 24.
+  - The iOS 14 deployment target that apps created with Flutter 3.38 must set
+    was never mentioned.
+  - The web Maps script was loaded with `async`/`loading=async`;
+    `google_maps_flutter_web` needs it loaded synchronously. The example app
+    is fixed too.
+  - The key-restriction sample used `dart:io`, which throws on web, and the
+    guidance didn't mention that the Geocoding API rejects
+    referrer-restricted keys.
+  - How key problems map to error kinds is now documented per API. With
+    Places API (New) (search, details, nearby), a wrong key arrives as
+    `invalidRequest` (HTTP 400, "API key not valid"). The Geocoding API
+    reports it as `requestDenied`, and an empty key fails search with
+    `unknown` in debug builds.
+- `MIGRATION_GUIDE.md`: the deprecation note now says all four deprecated
+  options, not "both", are removed in 5.0.0.
+- New screenshots rendered from the real widgets, with a reproducible
+  generator in `tool/screenshots`. The pub.dev gallery grows from three
+  images to eight, and the package archive shrinks from about 10 MB to under
+  1 MB.
+- New "Using with AI coding assistants" section: project rules for
+  `CLAUDE.md`, `AGENTS.md`, Copilot, Cursor and Gemini, plus seven copy-paste
+  prompts for integrating, embedding, migrating, localizing, debugging and
+  testing. Each prompt was checked by having an assistant follow it without
+  access to the package source, then compiling the result.
+- Added `llms.txt`, a compact and authoritative 4.x API reference for AI
+  assistants.
+- The package description on pub.dev now says what the package does.
+
 ## 4.0.0
 
 A full audit release: every open issue closed, every open pull request merged or

CONTRIBUTING.md

@@ -61,7 +61,7 @@ dart run build_runner build
 git diff --exit-code -- '*.freezed.dart' '*.g.dart'
 ```
 
-Two things worth knowing:
+Worth knowing:
 
 - **Never hand-edit a `.freezed.dart` file.** `freezed` and `build_runner` are
   pinned to exact versions precisely so everyone's generated output matches;
@@ -73,6 +73,31 @@ Two things worth knowing:
 - **If you change a README code sample**, update
   `example/lib/readme_samples.dart` to match. Every sample in the README is
   compiled there.
+- **Keep `llms.txt` accurate** whenever the public API changes. AI coding assistants
+  read it in place of their training data, so a stale entry there becomes
+  wrong code in someone else's app. The copy-paste prompts in the README repeat
+  some of the same facts; keep them in step.
+
+## Updating the screenshots
+
+The README and pub.dev images are rendered from the real widgets. They don't
+come from a device, so they can be regenerated after any UI change, without an
+API key:
+
+```bash
+flutter test tool/screenshots/generate_test.dart   # renders doc/readme/raw/*.png
+python3 tool/screenshots/frame.py                  # device frames -> screenshots/*.webp, doc/readme/hero.webp
+```
+
+The first command drives each scene with canned Places and Geocoding
+responses, so search, place details and nearby search run through the
+package's real code. Google's tiles can't load in a test, so the map itself is
+an illustration drawn by `tool/screenshots/map_art.dart`. The second command
+needs Pillow (`pip install pillow`) and finds Roboto in your Flutter SDK.
+
+Commit the WebP files; `doc/readme/raw/` is ignored. Scenes are defined in
+`generate_test.dart`. If you add one, list it in `pubspec.yaml` under
+`screenshots:` and in the README gallery.
 
 ## Reporting a bug
 

MIGRATION_GUIDE.md

@@ -136,7 +136,7 @@ MapLocationPickerConfig(bottomCardType: ...)  // ignored
 MapLocationPickerConfig(cardType: ...)        // use this
 ```
 
-Both still compile in 4.x and will be removed in 5.0.0.
+All four still compile in 4.x and will be removed in 5.0.0.
 
 ---