Fix what the eval and the client trial found

[franco-zalamena-iterable]

Twelve commits from two rounds of testing the Android and React Native skills against real apps: a 12-arm eval on a greenfield app, a non-greenfield scenario where the app already sent its own push, and a client trial in which an agent playing a protective app developer integrated the SDK end to end until a real push landed on a device. Rebased onto main — the two Xcode 27 commits this branch used to carry reached main via #21. Version ends at 26.9.3-beta.

Security and correctness

Refuse on-device JWT signing (ebbfecf). Told "JWT is on, here is the shared secret, we have no backend", the skill implemented HMAC signing in the app. Rule 1 said "wire up the handler" without saying where tokens come from, its pointer to the JWT doc was dangling, and the corpus ships a complete IterableJwtGenerator.java with nothing marking it as server code. Rule 1 now makes a backend a hard requirement and says to stop and stub without one; pitfall #22 names the corpus sample as the attractive nuisance it is.

Forward to an existing FirebaseMessagingService, don't replace it (0eec62b). Iterable's service registers at priority -1, so adding the SDK doesn't steal dispatch from an app that already sends order-status or security-code push — but Iterable receives nothing until their service forwards to it. The tempting fixes (delete their service, repoint the manifest, tools:node="remove") trade a silent marketing failure for a broken transactional channel. Android rule 8 + pitfall #23, RN rule 8 + pitfall #15, and Step 0 now greps for an existing service before scoping push work.

Accuracy of what the skill tells developers

Read dashboard nav paths, don't recite them (ebbfecf). The skill said Integrations > API Keys in one eval arm and Settings > API Keys in two others, while its own corpus gives the correct path in nine places. The routing table now carries the verified path per slug, with an instruction not to paraphrase and a rule that the doc wins on disagreement.

Add the dashboard prerequisite articles (f750f0a). api-keys, jwt-enabled-api-keys, fcm-http-v1-migration and the two embedded-messages articles, for both platforms — the steps a developer who doesn't yet have a key or a push integration has to perform.

Reconcile the init-callback guidance (c4620c1). PITFALLS.md #2 said the init callback should log initialization and nothing else; the canonical pattern said keep it empty and shipped a comment-only body. The trial followed the pattern — correctly, it's the one labelled "start here" — and read "should log" as optional. The pattern is now concrete: the SDK's verbose output proves the SDK initialized, but only the callback's own line separates "init never fired" from "init fired, identify didn't".

What the client trial cost

~43 minutes, and four of those causes are now closed.

• Pitfall [SDK-425] Add React Native skill skeleton and multi-platform docs refresh #16 was Groovy-only (553ceef). Kotlin DSL is the default for new projects and the block doesn't compile there. It also needs buildFeatures { buildConfig = true }, which AGP defaulted on before 8.0; measured on AGP 8.4, the failure text is quoted verbatim because it reads as "the field is wrong" rather than "the flag is off".
• Stop trusting the handed-over inputs (553ceef). The trial found a stale ITERABLE_API_KEY in local.properties belonging to another project, and caught it only by diffing against the key it had been given — nothing told it to look. Same shape for google-services.json against applicationId.
• A definition of done that needs no dashboard (fd057d2, Android only). SKILL.md stopped at "initialized, identified, key wired, builds" while the push doc ends at Test Push, which needs access many app developers don't have. Three device-side checks replace the guesswork. One exists purely because the trial hit it: registerDeviceToken returned Success and getMessages immediately returned UnknownEmailError for the same address. The profile hadn't propagated, and repairing a non-defect is how a working integration gets broken.
• Identity that arrives after init (42a104c). The largest single cost, 15 minutes. The canonical pattern took identity as a String, assuming it exists at Application.onCreate(); the app kept email in a DataStore Flow that emits at login and on account switch. The variant takes the stream and names the two shortcuts that look like simplifications — hoisting setEmail into the init callback (Package as a Cursor plugin (skill + Context7 MCP) #2), and first()-ing the flow back into a String, which drops the account switch (Claim Context7 library and fix MCP config #3).

Two independent reviews of this PR

Fourteen defects between them, all fixed (669d579, 5bc03bc, a196094, 4eb1d3a). The ones that mattered:

• Both citations of the forwarding procedure gave its heading as ## Handling Firebase push messages and tokens. It is ####, nested under ### Step 5 — so an agent grepping at the level it was handed finds nothing, skips the procedure, and hits the failure rule 8 exists to prevent. Every doc anchor in both skills has since been checked against the real heading level.
• The rebase renumbered this branch's new RN pitfall to Stop Context7 serving anti-pattern samples; collapse three doc copies into one #15 but left its label reading 14, which after the rebase is an Expo- and iOS-only item. The Android POST_NOTIFICATIONS note cited pitfall Reduce context7.json to minimal claim file #4 (postDelayed sequencing) instead of Enable live Context7 fetching (snapshot becomes fallback) #7.
• The stale-key bullet offered a 401 as its confirmation signal. A key belonging to a different Iterable project authenticates normally and returns 200, quietly populating that project — so an agent watching for a 401 would read the stale key as verified. It now names the real symptom: none of it appears in their dashboard.
• The definition of done claimed a notification channel observable before any push arrived. registerChannelIfEmpty has a single call site, inside the notification-building path, so it cannot be there yet; that step is dropped and the push-arrived check proves strictly more.

Verification

• pnpm check:all green: typecheck, 37 reference docs against the schema, plugin manifests. 26.9.3-beta consistent across all three manifests.
• Every pitfall #N cross-reference and doc anchor in both trees resolves to something that exists — checked by hand, because CI covers neither. A gate for it is a follow-up, as is the RN definition of done, which still has no device-side proof path.
• The AGP 8.4 failure text, the dumpsys notification arrival output and the Iterable-side token registration were observed on a live emulator. The channel-creation claim was read from SDK source; the 401-versus-200 split is server behaviour, inferred from the SDK labelling any non-JWT 401 Invalid API Key.

🤖 Generated with Claude Code