fix(sdk-expert): force loading campaigns.md and online docs for Console-driven questions

The sdk-expert agent was conflating Campaigns (SDK-managed, trigger-based) with
manual placement display, leading to wrong answers when users asked how to show a
campaign at app launch. Now the agent:

- Loads references/concepts/campaigns.md on any campaign/trigger/APP_STARTED/
  readyToOpenDeeplink mention, and disambiguates trigger-based vs placement-based
  delivery before writing code.
- Fetches https://docs.purchasely.com/docs/<topic> via ctx_fetch_and_index for
  any Console-driven topic (campaigns, audiences, A/B tests, placement config,
  Screens, Flows, surveys) and reconciles with bundled references.
- Adds pitfall #16 explicitly stating Campaigns are SDK-managed, not app-coded.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kherembourg

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- `sdk-expert` agent: forces loading `references/concepts/campaigns.md` whenever a question mentions *campaign / campagne / trigger / `APP_STARTED` / `readyToOpenDeeplink` / "afficher au lancement"*, and explicitly distinguishes trigger-based (SDK-managed, only `readyToOpenDeeplink(true)` required) from placement-based delivery.
+- `sdk-expert` agent: for any Console-driven topic (campaigns, audiences, A/B tests, placement configuration, Screens, Flows, surveys), the agent now fetches the current official documentation via `ctx_fetch_and_index(https://docs.purchasely.com/docs/<topic>)` before answering, and reconciles with the bundled references.
+
+### Fixed
+
+- `sdk-expert` agent no longer conflates Campaigns with the manual `fetchPresentation` / `presentPresentation` flow when the user asks about displaying a campaign at app launch.
+
 ## [1.0.0] — 2026-05-20
 
 Initial release of the Purchasely AI Plugin for Claude Code, GitHub Copilot CLI, and Codex.

purchasely/agents/sdk-expert.md

@@ -64,6 +64,7 @@ Use these signatures when answering exact-code questions. If a platform is not l
 13. **Bridge dismissal names**: Native iOS/Android use `closeAllScreens()` after Observer-mode purchases. Current React Native / Flutter / Cordova public bridges use `closePresentation()`. Do not generate `closeAllScreens()` for bridges unless the project has added its own native bridge.
 14. **Privacy consent**: SDK 5.4.0+ exposes `revokeDataProcessingConsent(...)`. Do not claim legal-basis/revocation APIs are unavailable; load `privacy-settings.md`.
 15. **Cordova signatures**: Cordova uses positional callbacks. Verify `references/cordova/integration.md` before writing Cordova code.
+16. **Campaigns are SDK-managed, not app-coded**: A Console **Campaign** with an event trigger (e.g. `APP_STARTED`) is displayed **automatically by the SDK** — the app does NOT call `fetchPresentation` / `presentPresentation` for it. The only required code is `Purchasely.readyToOpenDeeplink(true)` once the splash/onboarding is ready. Do not conflate Campaigns with Placements: a Campaign can be triggered by an event, by a placement, or both. Trigger-based delivery is automatic; placement-based delivery overrides the placement's default screen when the app calls `fetchPresentation(placementId)`. See `references/concepts/campaigns.md`.
 
 ## Support-Derived Known Issues / Fixes
 
@@ -143,3 +144,9 @@ Use `Glob` and `Read` tools to access these files when you need precise API sign
    - Make the condition explicit: only use these when the user asks to own the container or render an inline/nested Screen; otherwise prefer `display()`.
 10. **For programmatic purchase questions**, load `references/concepts/programmatic-purchases.md` and use exact platform APIs. Never answer with `Purchasely.purchase({ planId })`, `Purchasely.purchase(planId:)`, or Cordova `Purchasely.purchase(...)`.
 11. **For privacy/GDPR questions**, load `references/concepts/privacy-settings.md` and mention `revokeDataProcessingConsent(...)`, `clearBuiltInAttributes()`, and essential vs optional user attributes.
+12. **For Campaigns questions** — any mention of *campaign / campagne / trigger / `APP_STARTED` / "afficher au lancement" / `readyToOpenDeeplink`*: ALWAYS load `references/concepts/campaigns.md` FIRST. Disambiguate Campaign vs Placement before writing code:
+    - **Trigger-based Campaign** (e.g. `APP_STARTED`) → no `fetchPresentation` in the app. Only `Purchasely.readyToOpenDeeplink(true)` after the splash/onboarding finishes. Display is fully SDK-managed.
+    - **Placement-based Campaign** → app keeps calling `fetchPresentation(placementId)` + `presentPresentation`; the Campaign substitutes the placement's default screen when audience matches.
+    - **Both** → Campaign fires on trigger AND can override on placement; the SDK handles routing.
+    Always mention `readyToOpenDeeplink(true)` for trigger-based, the `CAMPAIGN_TRIGGERED` / `CAMPAIGN_DISPLAYED` / `CAMPAIGN_NOT_DISPLAYED` analytics events, and SDK ≥ 5.1.0. Never claim "the campaign activates automatically through `fetchPresentation`" — that conflates the two delivery modes.
+13. **For Console-driven questions** — campaigns, audiences, A/B tests, placement configuration, Screen Composer, scheduling, capping, Flows, surveys, or anything the user configures in the Purchasely Console rather than in code: the local references are the fast path but Console behavior evolves quickly. BEFORE answering, fetch the current official doc with `ctx_fetch_and_index(url: "https://docs.purchasely.com/docs/<topic>", source: "purchasely-<topic>-doc")` then `ctx_search(...)` against it, and reconcile with the bundled reference. Useful entry points: `https://docs.purchasely.com/llms.txt` (full index for AI agents), `/docs/campaigns`, `/docs/campaign-configuration`, `/docs/campaigns-implementation`, `/docs/audiences`, `/docs/ab-tests`, `/docs/displaying-screens-placements`, `/docs/screens`, `/docs/flows`. If the doc fetch and the local reference disagree, trust the online doc and flag the discrepancy in your answer so the reference can be updated.