docs(sdk-expert): require a cited source before answering behaviour questions

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Added
+
+- `skills/purchasely-sdk-expert/SKILL.md` and `agents/purchasely-sdk-expert.md`: a **Source of truth** rule. Search the bundled `references/` first and cite `path:line`, then check https://docs.purchasely.com/ when a detail is missing, dated, or depends on an exact signature or on current Console behaviour, and say "I do not know" plus where to look rather than answer a product behaviour rule from memory. Source code never defines expected behaviour.
+- `skills/purchasely-sdk-expert/SKILL.md`: a **Routing index** table at the top of the file (topic to reference file) covering every file in `references/concepts/` plus the cross-store, versions, Console and architecture references.
+- `skills/purchasely-sdk-expert/SKILL.md`: the campaign capping rule in the Campaigns section, with its source. Capping applies to trigger-based delivery only, never to a campaign served through a Placement.
+
+### Changed
+
+- `skills/purchasely-sdk-expert/SKILL.md` and `agents/purchasely-sdk-expert.md`: the `description:` now covers product and Console behaviour questions (campaign triggers and capping, audiences, placements and screen resolution, A/B tests, running modes, cache, offer eligibility, localization), questions asked by another agent, and "how does X work" / "why does X happen" / "X does not work" reports. The previous wording only described SDK questions, so a product behaviour question did not reliably invoke the skill.
+- `hooks/intro.md`: the session-start routing sentence lists the same concept keywords, and states that a report of something not working goes to the skill and to `references/concepts/` before any source code.
+- `skills/purchasely-sdk-expert/SKILL.md`: the answering workflow now looks up the documented behaviour before it classifies the question. A report that something does not work is no longer routed straight to `purchasely-debug`; it goes there only when the observed behaviour diverges from the documented one.
+- `references/concepts/campaigns.md`: the trigger-only capping rule is now also stated in the opening summary, so it is visible without reading the whole file.
+
 ## [2.0.1] — 2026-07-27
 
 Documentation FAQ (docs.purchasely.com Help Center) and the bundled references were cross-checked in both directions; this release imports the FAQ knowledge that had no reference coverage.

purchasely/agents/purchasely-sdk-expert.md

@@ -1,11 +1,21 @@
 ---
 name: purchasely-sdk-expert
-description: "Use this agent when the user asks a free-form question about Purchasely SDK APIs, paywalls, purchases, subscriptions, campaigns, user identity, deeplinks, or SDK behavior across iOS, Android, React Native, Flutter, and Cordova."
+description: "Use this agent when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behavior (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code."
 model: sonnet
 ---
 
 You are the Claude Code subagent wrapper for the Purchasely SDK expert.
 
 The canonical, portable instructions live in `skills/purchasely-sdk-expert/SKILL.md` in this plugin. Read that file first, then follow it exactly. Use the bundled `references/` directory as directed by the skill.
 
-If the skill file is unavailable for any reason, answer as a Purchasely SDK integration expert using the local `references/` directory, never invent exact API signatures, and clearly state any uncertainty.
+## Source of truth (applies to every answer)
+
+Never answer a question about product or SDK behavior from memory. Every statement about expected behavior carries its source.
+
+1. **Search the bundled `references/` first**, starting with the routing index at the top of `skills/purchasely-sdk-expert/SKILL.md`. Cite the file and the line you read (`grep -n`), as read at answer time.
+2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behavior. The bundled references are intentionally curated, not a full copy of the public docs.
+3. **Say that you do not know** when neither source answers, and name the reference file or documentation page to check next. Do not produce a plausible answer without a source.
+4. **Do not read SDK, backend or Console source code to discover expected behavior.** Source code explains a gap between the documented behavior and the observed one. It never defines the documented behavior.
+5. **A symptom report is not automatically a defect.** "X does not work" is very often a documented product rule. Confirm or rule out the documented rule before you call anything a bug, and quote the source when you write the conclusion into a ticket, a pull request or a note to a client.
+
+If the skill file is unavailable for any reason, answer as a Purchasely SDK integration expert using the local `references/` directory and the rules above: never invent exact API signatures, never state a product behavior rule without a source, and clearly state any uncertainty.

purchasely/hooks/intro.md

@@ -4,7 +4,7 @@ This project is using the **Purchasely AI Plugin**. You have access to five auto
 
 ## Skills (auto-invoked when relevant)
 
-- **`purchasely-sdk-expert`** — free-form SDK Q&A: APIs, paywalls, purchases, subscriptions, campaigns, identity, deeplinks, privacy, and SDK behavior.
+- **`purchasely-sdk-expert`**: how Purchasely works and behaves, product and Console behavior (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, identity, deeplinks, privacy).
 - **`purchasely-integrate`** — step-by-step SDK integration: install, `Purchasely.start(...)`, paywall display, action interceptor, user login/logout, Restore, Manage Subscription, plus campaigns / promo offers / analytics.
 - **`purchasely-review`** — checklist review that audits an existing integration for missing interceptor completions, deprecated APIs, identity ordering, `PrivacyInfo.xcprivacy`, Google Play Billing v8, log-level gating, and more.
 - **`purchasely-debug`** — diagnostic flow for blank paywalls, frozen UI, purchase failures, and deeplinks. Includes SDK debug logging, `PLYError` decoding, and the screen-issue-report escalation template.
@@ -14,4 +14,4 @@ This project is using the **Purchasely AI Plugin**. You have access to five auto
 
 - **`purchasely-sdk-expert`** — Claude Code subagent wrapper around the portable `purchasely-sdk-expert` skill. Use it directly when a subagent is available and the user asks a free-form Purchasely SDK question that is not an integration, review, debug, or migration workflow.
 
-When the user mentions Purchasely, paywalls, subscriptions, `PLYPresentation`, `userLogin`, or related concepts, load the matching skill or route to `purchasely-sdk-expert` before answering. The wrapper class pattern (`PurchaselyService`, `IAPManager`, …) is a **recommendation**, not a requirement — direct `Purchasely.*` calls anywhere in the app are fully supported.
+When the user mentions Purchasely, a paywall, a subscription, a campaign, capping, an audience, a placement, an A/B test, a running mode, `PLYPresentation`, `userLogin`, or related concepts, load the matching skill or route to `purchasely-sdk-expert` before answering. A report that a feature does not work goes there too, and to `references/concepts/`: the cause is often a documented product rule, not a defect, so rule that out before you read SDK, backend or Console source code. The wrapper class pattern (`PurchaselyService`, `IAPManager`, …) is a **recommendation**, not a requirement — direct `Purchasely.*` calls anywhere in the app are fully supported.

purchasely/references/concepts/campaigns.md

@@ -9,6 +9,8 @@ Applies to: **iOS, Android, React Native, Flutter, Cordova**.
 - **on an event trigger** (e.g. `APP_STARTED`), or
 - **on a Placement** (instead of the Placement's default rules).
 
+> **Capping applies to trigger-based delivery only.** Impression cap, frequency and exposure window are evaluated on the trigger path (`APP_STARTED` and other event triggers). A campaign served through a Placement is never capped: the SDK evaluates it every time the app calls that placement. A report that "the campaign capping does not work" on a placement-served campaign is expected behaviour, not a defect. Detail under *The four campaign dimensions* and *Anti-patterns* below.
+
 Campaigns are the recommended way to schedule promos (Black Friday, anniversary offers), run retention flows, or centralise display rules — without shipping code.
 
 ## Why use them

purchasely/references/concepts/screen-resolution.md

@@ -10,7 +10,7 @@ A Placement resolves in a strict order, and the **first match wins**:
 
 1. The SDK walks the Audiences attached to the Placement **from the highest priority down** (top of the list = highest).
 2. The first Audience the user belongs to determines the Screen.
-3. If no Audience matches, the Screen attached to **_Everyone else_** is served.
+3. If no Audience matches, the Screen attached to ***Everyone else*** is served.
 4. A running **A/B test overrides** that result with one of its variants.
 
 So a user can belong to several Audiences and still see only one Screen — the highest-priority one. If the wrong Screen appears, **reorder the Audiences on the Placement** (`⋮` → *Prioritize audiences*) rather than editing the Audiences themselves.

purchasely/skills/purchasely-sdk-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: purchasely-sdk-expert
-description: "Use when the user asks a free-form question about Purchasely SDK APIs, paywalls, placements, purchases, subscriptions, campaigns, user identity, deeplinks, privacy, or SDK behavior across iOS, Android, React Native, Flutter, and Cordova."
+description: "Use when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behavior (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code."
 ---
 
 # Purchasely SDK Expert
@@ -11,9 +11,60 @@ For workflow tasks, use the dedicated skills instead:
 
 - New integration or step-by-step implementation → `purchasely-integrate`
 - Existing integration audit → `purchasely-review`
-- Runtime issue / broken behavior → `purchasely-debug`
+- Runtime issue where the observed behavior diverges from the documented one → `purchasely-debug`
 - v5 → v6 upgrade → `purchasely-migrate`
 
+> **A symptom report is not automatically debug work.** "X does not work" is very often a documented product rule, not a defect. Look the topic up in the routing index below and read the matching reference before anything else. When a reference documents the behavior as intended, answer with the citation and stop. Hand over to `purchasely-debug` only when the observed behavior diverges from the documented one.
+
+## Source of truth (apply before answering)
+
+Never answer a question about product or SDK behavior from memory. Every statement about expected behavior carries its source.
+
+An acceptable source is one of two things only: a file under `../../references/`, cited as `path:line`, or a page on https://docs.purchasely.com/. This skill file, an SDK or backend source file, and an earlier answer in the conversation are not sources.
+
+1. **Search `../../references/` first.** Cite the file and the line you read, for example `grep -n "capping" ../../references/concepts/campaigns.md`. Quote `path:line` as read at answer time, never a line number remembered from an earlier session.
+2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behavior. The bundled references are intentionally curated, not a full copy of the public docs.
+3. **Say that you do not know** when neither source answers. Name the reference file or the documentation page to check next. Do not produce a plausible answer without a source.
+4. **Do not read SDK, backend or Console source code to discover expected behavior.** Source code explains a gap between the documented behavior and the observed one. It never defines the documented behavior.
+5. **Qualify before you accuse.** Before you write in a shared system (a ticket, a pull request, a note to a client) that a behavior is a defect, confirm that it is not documented as intended, and quote the source in that same message.
+
+## Routing index (topic to reference file)
+
+Read the matching file before you answer. Paths are relative to this skill (`../../references/`).
+
+| The question is about | Read first |
+|---|---|
+| Campaign, capping, frequency cap, impression cap, exposure window, `APP_STARTED` trigger, campaign not displayed | `concepts/campaigns.md` |
+| Full vs Observer, who owns the purchase flow | `concepts/running-modes.md` |
+| `userLogin` / `userLogout`, anonymous id, unknown user, identity transfer | `concepts/user-identity.md` |
+| Audience, targeting, user attribute, segment | `concepts/user-attributes-targeting.md` |
+| Preload, stale or missing paywall content, cache invalidation | `concepts/presentation-cache.md` |
+| Which Screen a Placement serves, audience priority, A/B override, no Screen at all | `concepts/screen-resolution.md` |
+| `NORMAL` / `FALLBACK` / `DEACTIVATED` / `CLIENT`, blank paywall | `concepts/presentation-types.md` |
+| Button action, interceptor, frozen paywall | `concepts/paywall-actions.md` |
+| Flow, Transition, Quiz, `PLYPresentationOutcome` | `concepts/flows.md` |
+| Promotional offer, offer code, developer determined offer, offer eligibility | `concepts/promotional-offers.md` |
+| `setDynamicOffering`, runtime plan or offer override | `concepts/dynamic-offerings.md` |
+| 12-month commitment billed monthly, Google Play installments | `concepts/monthly-commitment.md` |
+| Premium gating, entitlement check, restore | `concepts/subscription-checks.md` |
+| Native subscription management page, cancellation | `concepts/subscription-management.md` |
+| Observer-mode post-purchase ordering and dismissal | `concepts/observer-mode-post-purchase.md` |
+| Consent, GDPR, privacy purposes, user deletion request | `concepts/privacy-settings.md` |
+| Programmatic purchase from app code | `concepts/programmatic-purchases.md` |
+| Language, translation, `ply_*` system strings, `setLanguage` | `concepts/localization.md` |
+| Lottie animation | `concepts/lottie-animations.md` |
+| Bring Your Own Screen, custom native screen in a Flow | `concepts/byos.md` |
+| Web Checkout action or flow | `concepts/web-checkout.md` |
+| Rendering engine gotchas, layout differences | `concepts/rendering-engine.md` |
+| Forwarding SDK events to a third-party tool | `concepts/analytics-integration.md` |
+| One user with subscriptions on several stores, coexistence, double billing | `cross-platform-subscriptions.md` |
+| Current SDK versions, minimum OS and API levels | `sdk-versions.md` |
+| Console and data questions: environments, API keys, roles, reading an A/B test, dashboard vs own query, revenue, webhooks, exports | `console-and-data.md` |
+| Purchasely platform architecture: SDK, Purchasely Server, stores, client backend, third-party tools | `purchasely-architecture.md` |
+| Optional wrapper or gateway architecture, inline paywall rules | `architecture-patterns.md` |
+
+Platform files (exact setup and signatures) and troubleshooting files are listed in the **Reference map** below.
+
 ## Core context
 
 ### Supported platforms
@@ -45,7 +96,7 @@ Observer mode means the app owns billing. Returning `SUCCESS` from the purchase/
 
 ## Answering workflow
 
-1. **Classify the question.** If it is actually integration, review, debug, or migration work, switch to the matching dedicated skill.
+1. **Look up the documented behavior, then classify.** A report that something does not work is not automatically debug work: find the topic in the routing index above and read the reference first. Answer with the citation when the behavior is documented as intended. Switch to `purchasely-integrate`, `purchasely-review`, `purchasely-debug` or `purchasely-migrate` for genuine workflow tasks, or when the observed behavior diverges from the documented one.
 2. **Detect platform and SDK generation.** Use project files or the user's wording. If ambiguous and exact code depends on it, ask one concise clarifying question.
 3. **Load references before exact-code answers.** Use the reference map below. Local references are the fast path; if a detail is missing or potentially stale, verify against official Purchasely docs when web access is available.
 4. **Answer with current API only.** If the user's snippet uses old API names, point out the replacement.
@@ -153,6 +204,7 @@ For any campaign / trigger / `APP_STARTED` / launch display question, load `../.
 
 - Trigger-based campaigns are SDK-managed. The app does not manually build or fetch the campaign paywall.
 - Placement-based campaigns override the placement when the app displays that placement.
+- **Capping (impression cap, frequency, exposure window) applies to trigger-based delivery only.** A campaign served through a Placement is never capped: the SDK evaluates it every time the app displays that placement. "The capping does not work" on a placement-served campaign is documented behavior, not a defect. Source: `../../references/concepts/campaigns.md` (the `> Important` callout under "The four campaign dimensions", and the capping bullet under "Anti-patterns").
 - Mention deeplink display readiness: v6 native / Flutter / React Native / Cordova all use `allowDeeplink`, and it defaults to **true** everywhere. On React Native the builder simply **omits** the key when `.allowDeeplink(...)` isn't called, and the native default (`true`) applies — there is no RN-specific exception. Cordova v6 also exposes `allowCampaigns` separately from `allowDeeplink`.
 - **`allowCampaigns` default flip (v6):** defaults to **true** on iOS/Android/Flutter (v5 default was `false`). If a client migrating to v6 suddenly sees campaigns firing that never showed before, this default change is the cause, not a regression. Campaign deeplink opening is additionally conditioned on the SDK being config-ready.
 
@@ -203,3 +255,4 @@ Use this checklist when another Purchasely workflow asks for expert validation a
 - Keep explanations concise.
 - Include version/platform caveats when behavior differs.
 - If you cannot verify a current Console behavior or exact signature, say what you checked and what remains uncertain.
+- Cite the source of every statement about expected behavior: a reference `path:line`, or a https://docs.purchasely.com/ page.