feat: document BYOS and multi-action button chaining

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]
+
+### Added
+
+- `references/concepts/byos.md` — Bring Your Own Screen reference: when to use it (native login step in a Flow, A/B against an existing paywall, reordering onboarding), Console configuration (Screen ID + connections), iOS implementation (`PLYCustomScreenViewControllerDelegate` / SwiftUI `PLYCustomScreenViewDelegate`), Android implementation (`PLYCustomScreenProvider` + `PLYCustomScreen.View` / `.Fragment`), `executeConnection(...)` / `execute(connection)` contract for resuming a Flow or running a standalone action, `Purchasely.synchronize()` requirement for in-screen purchases, analytics behaviour, and a list of anti-patterns BYOS replaces (custom VC over Purchasely, manual close-then-push, skipping `display()`). iOS + Android only, SDK ≥ 5.6.0.
+- `references/concepts/paywall-actions.md` § **Chaining multiple actions on a single button** — documents how a Composer button can carry several actions (purchase + open_screen / open_placement / deeplink / close, login + purchase, etc.) executed sequentially, the default behaviour when no second action is configured (close in Full mode, stay open in Observer mode), how the interceptor sees each action separately, and the fact that `proceed(false)` short-circuits the chain.
+- `sdk-expert` agent: new response rule for BYOS / "show my own screen inside a paywall or Flow" / "native login step inside a Flow" — forces loading `references/concepts/byos.md`, gates the answer on SDK ≥ 5.6.0 + iOS/Android platform, and steers users away from anti-patterns (presenting a custom VC over the Purchasely controller, `Purchasely.close()` then push, skipping `display()`).
+- `review` skill: new section **3.12 BYOS** — conditional checklist (platform support, SDK version, `display()` usage, delegate/provider completeness, `executeConnection` on every exit, connection ID consistency, `synchronize()` after in-screen purchases, no manual navigation around the SDK controller, in-screen analytics instrumentation).
+- `review` skill § 3.3: new checkpoint flagging interceptors that try to override the post-purchase flow (holding the interceptor open, skipping `proceed`, manual `Purchasely.close()`) — recommends configuring a second Composer action instead, or BYOS for a custom next step.
+- `integrate` skill § Step 9 (Beyond the Basics): two new entries — BYOS and chained Composer actions — so they surface during onboarding when the user's roadmap matches.
+
 ## [1.0.1] — 2026-05-20
 
 ### Changed

purchasely/agents/sdk-expert.md

@@ -86,8 +86,9 @@ If the bundled reference is missing a detail, looks stale, or the question depen
 
 **Universal concepts** — apply to all 5 platforms (`references/concepts/`):
 - `running-modes.md` — Full vs Observer
-- `paywall-actions.md` — interceptor + `proceed/processAction`
+- `paywall-actions.md` — interceptor + `proceed/processAction` + chaining multiple actions on a single button (purchase + open_screen / open_placement / deeplink)
 - `presentation-types.md` — NORMAL / FALLBACK / DEACTIVATED / CLIENT guard
+- `byos.md` — Bring Your Own Screen (native screens inside a Flow — login, custom forms, legacy paywall A/B); iOS + Android only, SDK ≥ 5.6.0
 - `presentation-cache.md` — preload + invalidation
 - `observer-mode-post-purchase.md` — `proceed/processAction → dismiss` ordering
 - `user-identity.md` — `userLogin` / `userLogout` + anonymous→logged-in merge
@@ -149,4 +150,5 @@ Use `Glob` and `Read` tools to access these files when you need precise API sign
     - **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.
+13. **For BYOS / "show my own screen inside a paywall or Flow" / "native login step inside a Flow" / "embed my legacy paywall as a Purchasely variant"**: load `references/concepts/byos.md` FIRST. Confirm SDK ≥ 5.6.0 and the platform is iOS (Swift/SwiftUI) or Android (Kotlin) — BYOS is **not** available on React Native, Flutter, or Cordova yet. Steer users away from anti-patterns (presenting their own VC over the Purchasely controller, calling `Purchasely.close()` then pushing their screen, skipping `display()`). The supported path is: Console creates a Screen with layout `Bring Your Own Screen` and connections; the app sets `Purchasely.setCustomScreenViewControllerDelegate(...)` / `setCustomScreenViewDelegate(...)` (iOS) or `setCustomScreenProvider(...)` (Android); when the user finishes the step, the app calls `presentation.executeConnection(...)` / `presentation.execute(connection)` with the matching `PLYConnection`. Remind callers to `Purchasely.synchronize()` after any purchase performed inside a Custom Screen (especially for A/B and A/A tests).
+14. **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.

purchasely/references/concepts/README.md

@@ -11,8 +11,9 @@ When a topic also has a deeper platform-specific take (e.g. SwiftUI lifecycle, J
 | File | Topic |
 |------|-------|
 | [running-modes.md](running-modes.md) | Full vs Observer modes, log levels |
-| [paywall-actions.md](paywall-actions.md) | `PLYPresentationAction` enum + interceptor `proceed/processAction` rules |
+| [paywall-actions.md](paywall-actions.md) | `PLYPresentationAction` enum + interceptor `proceed/processAction` rules + chaining multiple actions on a single button (purchase + open_screen / open_placement / deeplink) |
 | [presentation-types.md](presentation-types.md) | `PLYPresentationType` enum (NORMAL / FALLBACK / DEACTIVATED / CLIENT) guard |
+| [byos.md](byos.md) | Bring Your Own Screen — embed native screens (login, custom forms, legacy paywall) inside a Flow; iOS + Android only, SDK ≥ 5.6.0 |
 | [presentation-cache.md](presentation-cache.md) | App-side caching + preload pattern (avoid `FlowsManager.flowSteps` accumulation) |
 | [observer-mode-post-purchase.md](observer-mode-post-purchase.md) | `proceed → dismiss` ordering, native vs bridge close APIs, chaining follow-up placements |
 | [user-attributes-targeting.md](user-attributes-targeting.md) | Setting user attributes for audience targeting + GDPR consent |
@@ -39,4 +40,6 @@ When a topic also has a deeper platform-specific take (e.g. SwiftUI lifecycle, J
 | Wiring analytics / tracking | `analytics-integration.md`, `user-identity.md` |
 | Improving paywall perceived performance | `presentation-cache.md` (preload pattern) |
 | Debugging stuck paywalls / blank presentations | `presentation-types.md`, `presentation-cache.md`, `paywall-actions.md` |
+| Embedding a native login / custom form / legacy paywall inside a Flow | `byos.md` (iOS + Android, SDK ≥ 5.6.0) |
+| Configuring multi-step buttons (purchase + next step, purchase + placement) | `paywall-actions.md` § Chaining multiple actions |
 | Reviewing an existing integration | all of the above |