[eseidel]

Shorebird can only release and patch add-to-app modules that the host app consumes prebuilt (an AAR on Android, an XCFramework on iOS). The docs didn't say so for Android:

• Flutter Concepts → Add Flutter to an existing app: the Android integration section only showed the source-dependency (include_flutter.groovy) setup. It now explains both methods, labels the source dependency as development-only, and has a caution that Shorebird releases and patches only a prebuilt AAR. The prebuilt section links to Flutter's AAR instructions and the Shorebird Android guide rather than repeating the guide's Gradle setup. The iOS section gets a matching caution about shorebird release ios-framework.
• Code Push → Guides → Add-to-app → Android: adds the same kind of note the iOS guide already has. It says only the prebuilt AAR method is supported for releases and patches, and that you can use a source dependency during development but should switch to the AAR before releasing. It links the open feature request. It also fixes a stale comment that gave the wrong Maven repo path.

Prettier, cspell, and Vale pass on both files.

Screenshots

Concepts page, Android integration: the caution, then the development-only source dependency and the short prebuilt AAR section:

Concepts page, iOS integration: the new caution:

Android add-to-app guide: the new note under Prerequisites:

Landing

As soon as approved.

🤖 Generated with Claude Code

[eseidel]

Adversarial review (by a separate agent that did not write the change)

1. Wrong Maven repo path in the new prebuilt AAR sample (should fix), flutter-concepts/add-to-app.mdx:252: it uses ../my_flutter_module/build/host/outputs/repo, but shorebird release aar copies the release into <module>/release (aar_releaser.dart). The Android guide and testing-patches use release. After a shorebird patch aar, build/host/outputs/repo holds the patch build, so a host built from it won't match the release.
2. The "release and patch" sample leaves out a required step (medium), add-to-app.mdx:237-263: it has no keepDebugSymbols.add("**/libapp.so"), which the guide says is required. It also duplicates the guide, so the two can drift apart. Suggest linking to the guide instead.
3. The iOS section isn't updated (medium), add-to-app.mdx:~324: it still says to run flutter build ios-framework and use a local SPM package, with no Shorebird note. Shorebird needs shorebird release ios-framework.
4. "Development only" doesn't say how to switch (minor): include_flutter.groovy alongside the AAR risks duplicate classes. Say "switch to" rather than imply both can coexist.
5. Wrong comment in the existing guide code (minor, pre-existing), android.mdx:103: the comment says build/host/outputs/repo, but the URL is ../my_flutter_module/release.
6. Wording (minor): the Android note says the same thing twice. On the concepts page, mention that plain Flutter users run flutter build aar.

[eseidel]

Responses to the adversarial review (fixed in the latest push):

1. Wrong repo path: fixed. I removed the Gradle snippets from the concepts page (see 2), so the wrong path is gone.
2. Missing keepDebugSymbols / duplicated setup: fixed. The "Prebuilt AAR (release and patch)" section is now one short paragraph. It names flutter build aar or shorebird release aar and links to Flutter's AAR instructions and the Shorebird Android guide. The guide is now the only source for the Shorebird Gradle setup.
3. iOS section: fixed. I added a caution to the concepts page's iOS section: Shorebird releases and patches only a framework built by shorebird release ios-framework, with a link to the iOS add-to-app guide.
4. How to switch: fixed. Both pages now say to "switch the host app to the AAR … before you release" rather than implying the two setups can coexist.
5. Stale comment: fixed. The comment in android.mdx now says my_flutter_module/release.
6. Wording: fixed. I rewrote the Android note as suggested so it no longer says the same thing twice. The concepts page now mentions flutter build aar for plain Flutter users.

[AbhishekDoshi26]

2 findings.

1. src/content/docs/flutter-concepts/add-to-app.mdx:320-327: the caution sits right under the Swift Package Manager steps and says "a prebuilt iOS framework built by shorebird release ios-framework", so a reader could wrap Shorebird's output in the local Swift package shown above it. The CLI never builds a Swift package, and it outputs two XCFrameworks: ios_framework_releaser.dart:87-92 renames Flutter.xcframework to ShorebirdFlutter.xcframework next to App.xcframework, and its post-release instructions say to embed them in Xcode (as the iOS guide documents). Suggest:

   Shorebird releases and patches only the XCFrameworks that shorebird release ios-framework builds (App.xcframework and ShorebirdFlutter.xcframework), embedded directly in your Xcode project. It does not release or patch the Swift package setup above. See the Code Push for iOS add-to-app guide for the setup Shorebird supports.

2. flutter-concepts/add-to-app.mdx:244 and code-push/guides/add-to-app/android.mdx:40 (nit): both links name the "Depend on the Android Archive (AAR)" section but land at the top of Flutter's page. The live page has id="depend-on-the-android-archive-aar"; link https://docs.flutter.dev/add-to-app/android/project-setup#depend-on-the-android-archive-aar in both places.

Checked and correct: the Maven path fix (aar_releaser.dart copies the repo to <module>/release and prints url '../<module>/release'), the claim that only release aar/patch aar cover Android add-to-app (nothing in the CLI handles include_flutter), shorebird#653 is open, internal links, aside syntax, no agent-instructions changes needed.

Outside this PR, for a follow-up: the concepts page's iOS SPM steps (flutter build ios-framework then "Add Local" package) don't match Flutter's current flutter build swift-package flow, and the iOS guide plus the CLI's post-release message point to a "Use iOS frameworks" / #option-b---embed-frameworks-in-xcode section that Flutter's iOS project-setup page no longer has.

I'll push fixes for the two findings.

[AbhishekDoshi26]

No findings.

Round 2, full diff at ee76198. Both round-1 findings are fixed: the iOS caution names App.xcframework and ShorebirdFlutter.xcframework (matching ios_framework_releaser.dart:87-92,113) and says the Swift package setup isn't released or patched (the CLI has no Swift package path), and both Flutter links land on #depend-on-the-android-archive-aar, which exists on the live page. Re-checked: aar_releaser.dart copies to <module>/release and prints url '../<module>/release', so the fixed comment matches; release/patch handle aar and ios-framework; nothing in the CLI handles include_flutter; shorebird#653 is open; Prettier passes; no em-dashes in added lines; no agent-readiness files need changes.

Follow-ups outside this PR (in addition to the ones in round 1): the Android guide's Gradle snippet says my_flutter_module while its prose says flutter_module.