@superwall/cli 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/dist/{apple-CkKlHBZ9.js → apple-CSzNTGHM.js} +13 -13
  2. package/dist/auth.d.ts +1 -1
  3. package/dist/auth.js +3 -3
  4. package/dist/{billing-XCZU_T46.js → billing-C3Q8DBU2.js} +3 -3
  5. package/dist/{bind-drne__Ys.js → bind-BumHTi9O.js} +4 -4
  6. package/dist/{build-Gpdq5QXP.js → build-Bpviiclc.js} +6 -6
  7. package/dist/{client-DP6Rc0t_.js → client-BL0f_yGf.js} +2 -2
  8. package/dist/create-BSfvpWoD.js +19 -0
  9. package/dist/{create-Cwc3SRWJ.js → create-BUcVG4Ab.js} +23 -23
  10. package/dist/{create-BBrtgUgS.js → create-CfK3PeKA.js} +6 -6
  11. package/dist/{doctor-C9ldpPFC.js → doctor-BWqIYcMn.js} +6 -6
  12. package/dist/{drivers-DNrx4LWA.js → drivers-CPhdPkW5.js} +3 -3
  13. package/dist/entry.js +20 -21
  14. package/dist/{environment-DF1qKlny.js → environment-eBXjELoN.js} +1 -1
  15. package/dist/{existing-78LWSsqS.js → existing-BltvQiX5.js} +2 -2
  16. package/dist/held-CPve03KJ.js +16 -0
  17. package/dist/{held-Cy8Wl4D1.js → held-DgnTFMl3.js} +6 -6
  18. package/dist/{integrate-DcJhpXy8.js → integrate-BRsqoe01.js} +22 -22
  19. package/dist/{login-B2TsCE2H.js → login-BCEH5q0U.js} +1 -1
  20. package/dist/login-BPOONe7n.js +16 -0
  21. package/dist/{login-D0lh3_JI.js → login-BbTIrCFT.js} +5 -5
  22. package/dist/{lookup-D-nmmAbw.js → lookup-rr1AkCJA.js} +2 -2
  23. package/dist/{migrate-Cfec564E.js → migrate-C9X2Vz81.js} +22 -22
  24. package/dist/{notification-url-YDbq6FMA.js → notification-url-CV86qiKP.js} +2 -2
  25. package/dist/{open-Ba2vBl1_.js → open-CcpXotHG.js} +10 -10
  26. package/dist/{org-D0g_q3mv.js → org-BQQDo7wm.js} +2 -2
  27. package/dist/{paths-DxSLdpOI.js → paths-CRlU72cq.js} +1 -1
  28. package/dist/{playbook-DIeb7hne.js → playbook-DVMXN7fh.js} +10 -10
  29. package/dist/{promote-COD4fYdz.js → promote-Da8xctzy.js} +16 -16
  30. package/dist/push-BV-grvQg.js +22 -0
  31. package/dist/{push-CncywhkQ.js → push-D6R9icWN.js} +27 -14
  32. package/dist/{registry-DSrosOYs.js → registry-BYVD-_h6.js} +206 -49
  33. package/dist/{resources-Dqr01Dep.js → resources-DLON3-61.js} +18 -6
  34. package/dist/{run-C9qg_QlC.js → run-Co-BwhOg.js} +2 -2
  35. package/dist/scan-B88OlWOt.js +4 -0
  36. package/dist/{scan-DLrsrFS9.js → scan-CKuk-_6W.js} +1 -1
  37. package/dist/{scope-V336uz8j.js → scope-DV22_Ufm.js} +4 -4
  38. package/dist/{selection-Rdw-ZUoG.js → selection-C2_KbLuo.js} +10 -4
  39. package/dist/server-C4f6ccUr.js +22 -0
  40. package/dist/{server-D0tGG8C4.js → server-D0d2oP-5.js} +10 -8
  41. package/dist/{session-CFAmMhem.js → session-B-Uz0cQ7.js} +1 -1
  42. package/dist/session-BuvArt1j.js +6 -0
  43. package/dist/{session-D_nEWKXT.js → session-C4rbE3VS.js} +41 -13
  44. package/dist/skills/superwall-framework/SKILL.md +7 -3
  45. package/dist/skills/superwall-framework/references/cli.md +1 -0
  46. package/dist/skills/superwall-framework/references/layout.md +34 -1
  47. package/dist/{skills-DMG4bpKk.js → skills-CLGJuMnF.js} +8 -8
  48. package/dist/{skills-BvFOa4y6.js → skills-CZcpnEnG.js} +5 -4
  49. package/dist/{spinner-CneRK5rk.js → spinner-C2U6QBJ9.js} +3 -3
  50. package/dist/{storage-s2Dnz-yl.js → storage-6h9vyiAz.js} +1 -1
  51. package/dist/storekit-CK9JmM2D.js +16 -0
  52. package/dist/{storekit-yY_kS2iR.js → storekit-CinJra3V.js} +3 -3
  53. package/dist/{telemetry-DtG92m5O.js → telemetry-DKyDhURo.js} +1 -1
  54. package/dist/{token-DzRh7dI1.js → token-DaxQgQkv.js} +1 -1
  55. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  56. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  57. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  58. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  59. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  60. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  61. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  62. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  63. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  64. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  65. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  66. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  67. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  68. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  69. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  70. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  71. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  72. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  73. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  74. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  75. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  76. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  77. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  78. package/dist/tools-skills/superwall/SKILL.md +263 -0
  79. package/dist/tools-skills/superwall/references/api.md +303 -0
  80. package/dist/tools-skills/superwall/references/asa.md +166 -0
  81. package/dist/tools-skills/superwall/references/asc.md +95 -0
  82. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  83. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  84. package/dist/tools-skills/superwall/references/docs.md +51 -0
  85. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  86. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  87. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  88. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  89. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  90. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  91. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  92. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  93. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  94. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  95. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  96. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  97. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  98. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  99. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  100. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  101. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  102. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  103. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  104. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  105. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  106. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  107. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  108. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  109. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  110. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  111. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  112. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  113. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  114. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  115. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  116. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  117. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  118. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  119. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  120. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  121. package/dist/tools.d.ts +1 -1
  122. package/dist/tools.js +200 -18
  123. package/dist/{upgrade-Bt4Ouw1y.js → upgrade-DPo0a4Es.js} +1 -1
  124. package/dist/{upgrade-Cqy5orjb.js → upgrade-ffseQDMx.js} +2 -2
  125. package/package.json +2 -2
  126. package/dist/create-Yvf2gStM.js +0 -19
  127. package/dist/held-Ddw1XSsr.js +0 -16
  128. package/dist/kinds-GFXB3sYu.js +0 -11
  129. package/dist/login-BoBe8Psl.js +0 -16
  130. package/dist/push-CtD4FZQV.js +0 -22
  131. package/dist/scan-Cv5uOwVY.js +0 -4
  132. package/dist/send-BxD9yf6F.js +0 -150
  133. package/dist/server-z1LH94R_.js +0 -22
  134. package/dist/session-1AV_Bs_d.js +0 -6
  135. package/dist/storekit-DafAnGkM.js +0 -16
  136. /package/dist/{devtools-ByZ6XYnn.js → devtools-pBl_vt03.js} +0 -0
  137. /package/dist/{reports-DdPq4blM.js → reports-D_qbl7_u.js} +0 -0
  138. /package/dist/{screenshot-file-0UETadF8.js → screenshot-file-tVBfUEIi.js} +0 -0
  139. /package/dist/{storage-DYvmIOHa.d.ts → storage-CerJ5KLP.d.ts} +0 -0
@@ -0,0 +1,70 @@
1
+ # Review an existing Superwall setup
2
+
3
+ Review the integration as a system, not as a placement inventory. Inspect code,
4
+ project configuration, and authenticated dashboard state where available. A good
5
+ review explains what is correct, identifies only evidence-backed defects, and
6
+ separates optional opportunities from required fixes.
7
+
8
+ ## Review contract
9
+
10
+ 1. Read the app's architecture and detect its purchase path before judging it.
11
+ 2. Fetch the current platform docs at each relevant step; APIs and guidance move.
12
+ 3. Audit code and native project configuration without editing in review mode.
13
+ 4. Cross-check the dashboard and store through read-only CLI commands when auth
14
+ is available. A failed check is **Not verified**, never an issue by itself.
15
+ 5. Cite file and line evidence for every code finding. Never infer a defect from
16
+ a symbol name alone; read the surrounding flow.
17
+
18
+ ## Audit every area
19
+
20
+ | Area | What good looks like |
21
+ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22
+ | SDK & configuration | Supported package, configured once and early with the correct platform public key and intentional options. |
23
+ | Purchases & subscriptions | Exactly one deliberate purchase path: Superwall default, RevenueCat, or a custom controller; restores and status sync match that path. |
24
+ | Identity & attributes | Authenticated apps identify after login, reset/sign out on logout, and set useful targeting attributes without sensitive data. |
25
+ | Deep links | App URL entry points forward URLs to `handleDeepLink`, enabling the standard `deepLink_open` placement and preview links. |
26
+ | Web Checkout | If used or intended, redirects and redemption match the purchase path. If absent, describe readiness as optional - not broken setup. |
27
+ | Placements | Valuable moments are registered intentionally; real gates put controllable work in the feature callback; code and campaign names agree where presentation is expected. |
28
+ | Dashboard & store | Products, entitlements, paywalls, campaigns, placements, and store identifiers form a usable chain. |
29
+ | Analytics & lifecycle | Delegate/event forwarding is coherent and custom lifecycle events do not accidentally duplicate standard placements. |
30
+
31
+ ## Correctness rules that prevent false positives
32
+
33
+ - **Analytics events becoming placements is recommended.** The docs explicitly
34
+ recommend registering analytics events for future flexibility.
35
+ - **Fire-and-forget placements are valid.** A feature callback is needed only
36
+ when that specific action must be remotely gateable.
37
+ - **Subscription-state reads are valid.** The SDK documents them for app state and
38
+ UI. Flag only contradictory sources of truth or broken controller/status sync.
39
+ - **An unrouted placement is not automatically dead.** It is a problem only when
40
+ the app expects that placement to present or gate now; analytics-only and future
41
+ placements may intentionally have no campaign.
42
+ - Do not require optional features (Web Checkout, delegate analytics, custom
43
+ attributes) without evidence that the app intends to use them.
44
+ - Do not recommend renaming stable placement keys for style alone.
45
+
46
+ ## Authenticated cross-checks
47
+
48
+ Use `superwall whoami --json`, then `superwall bootstrap --json`. Derive the exact
49
+ project/app ids and pass them to `superwall products list --project <id> --json`,
50
+ `superwall entitlements list --project <id> --json`, `superwall campaigns list
51
+ --project <id> --app <id> --json`, and `superwall paywalls list --project <id>
52
+ --app <id> --json`. When App Store Connect is linked,
53
+ use `superwall asc subscriptions <bundle-id> --json` to compare store identifiers.
54
+
55
+ ## Framework reference
56
+
57
+ Read exactly one: `ios.md` (beside this file), `expo.md` (beside this file),
58
+ `react-native.md` (beside this file), `flutter.md` (beside this file), or `android.md` (beside this file).
59
+
60
+ ## Docs access
61
+
62
+ ```bash
63
+ curl -sL https://superwall.com/docs/llms.txt
64
+ curl -sL https://superwall.com/docs/{platform}/llms.txt
65
+ curl -sL https://superwall.com/docs/{path}.md
66
+ ```
67
+
68
+ Use the platform pages for configure, advanced purchasing, subscription state,
69
+ user management, deep links, feature gating, and Web Checkout. Use dashboard
70
+ pages for placements, standard placements, products, and subscription management.
@@ -0,0 +1,100 @@
1
+ # Review Superwall - React Native
2
+
3
+ You are reviewing a bare React Native app. First distinguish the recommended
4
+ `expo-superwall` provider path from the legacy
5
+ `@superwall/react-native-superwall` singleton path; do not mix their APIs.
6
+
7
+ ## Checklist
8
+
9
+ - [ ] package/native linking and deployment targets
10
+ - [ ] one provider or one early singleton configuration with platform keys
11
+ - [ ] purchase controller, restore flow, and subscription-status ownership
12
+ - [ ] identity/logout and user attributes
13
+ - [ ] platform linking and `handleDeepLink`
14
+ - [ ] conditional Web Checkout redemption readiness
15
+ - [ ] placements, callbacks, campaigns, and standard placements
16
+ - [ ] dashboard/store products, entitlements, paywalls, and campaigns
17
+ - [ ] event forwarding and native build verification
18
+
19
+ ## Docs access
20
+
21
+ ```bash
22
+ curl -sL https://superwall.com/docs/react-native/llms.txt
23
+ curl -sL https://superwall.com/docs/react-native/sdk-reference/configure.md
24
+ curl -sL https://superwall.com/docs/react-native/sdk-reference/handleDeepLink.md
25
+ curl -sL https://superwall.com/docs/react-native/sdk-reference/register.md
26
+ curl -sL https://superwall.com/docs/expo/quickstart/configure.md
27
+ curl -sL https://superwall.com/docs/expo/guides/advanced-configuration.md
28
+ curl -sL https://superwall.com/docs/expo/guides/handling-deep-links.md
29
+ curl -sL https://superwall.com/docs/expo/guides/web-checkout.md
30
+ ```
31
+
32
+ ## 1. SDK and configuration
33
+
34
+ Inspect `package.json`, lockfiles, iOS pods/project settings, Android Gradle, and
35
+ app entry points. Provider path: one root `SuperwallProvider` with per-platform
36
+ keys, no duplicate singleton `configure`. Legacy path: one
37
+ `Superwall.configure({ apiKey, ... })` in a root effect that does not rerun.
38
+ Public keys should match platform and existing config conventions.
39
+
40
+ ## 2. Purchases, restores, and subscription state
41
+
42
+ Infer the chosen path:
43
+
44
+ - **Default:** no custom controller is correct; Superwall owns purchases,
45
+ restores, and subscription status.
46
+ - **RevenueCat/custom:** the controller must implement the current App Store and
47
+ Google Play purchase methods plus restore, and synchronize Superwall status as
48
+ its entitlement source changes.
49
+
50
+ Reading status through `useUser` or the legacy singleton is documented and not a
51
+ defect. Report only broken ownership, conflicting sources, permanently unknown
52
+ status, missing controller branches, or behavior inconsistent with the intended
53
+ architecture. Compare product/entitlement IDs through authenticated CLI/store
54
+ checks; blocked checks go in **Not verified**.
55
+
56
+ ## 3. Identity and attributes
57
+
58
+ Trace real auth flows. Provider path uses `useUser` identity/sign-out methods;
59
+ legacy path uses `Superwall.shared.identify(...)` and `reset()`. Confirm login and
60
+ logout both update Superwall, and inspect attributes for targeting value and
61
+ sensitive data. Anonymous-only apps do not need fabricated identity work.
62
+
63
+ ## 4. Deep links and Web Checkout
64
+
65
+ Inspect React Navigation/linking config plus iOS and Android native URL handling.
66
+ Cover cold start and foreground delivery. Provider-style apps follow the current
67
+ Expo module `handleDeepLink` docs; legacy apps use the singleton
68
+ `handleDeepLink`. The goal is the standard `deepLink_open` placement and its URL
69
+ parameters - not an app-maintained URL-to-placement table.
70
+
71
+ Web Checkout is conditional. If used, verify return URLs and redemption behavior
72
+ for the detected purchase path. Default purchasing needs no custom entitlement
73
+ merge; custom/RevenueCat paths follow their dedicated redemption docs. Otherwise
74
+ list readiness only as an optional opportunity.
75
+
76
+ ## 5. Placements and lifecycle
77
+
78
+ Find provider `usePlacement`/`registerPlacement` and legacy
79
+ `Superwall.shared.register`, including wrappers and analytics bridges. Analytics
80
+ and fire-and-forget registrations are valid. Require a feature callback only when
81
+ that action is meant to be remotely gateable. Check event/effect placement,
82
+ awaiting of async calls, exact names for active presenting campaigns, and useful
83
+ parameters. Unrouted analytics/future placements are fine.
84
+
85
+ Prefer standard `app_launch`, `session_start`, and `deepLink_open` over truly
86
+ duplicative custom lifecycle placements. Do not propose cosmetic renames of
87
+ stable keys. Analytics delegate/hooks are optional unless the app relies on them.
88
+
89
+ ## 6. Dashboard and verification
90
+
91
+ Run the read-only CLI checks from `playbook.md` (Authenticated cross-checks). Verify app/platform keys, products,
92
+ entitlements, paywall products, campaigns, and placements expected to present
93
+ now form a usable chain. Cite IDs where available. In fix mode, run the existing
94
+ TypeScript and native build/test paths.
95
+
96
+ ## Fix-mode boundaries
97
+
98
+ Fix clear wiring bugs and code/doc mismatches. Never mix provider and legacy APIs,
99
+ switch purchase providers, enable Web Checkout, rename stable placements, change
100
+ prices, or invent campaign strategy without an explicit user decision.
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: superwall-editor
3
+ description: LEGACY — drives the browser (visual) paywall editor over a pairing code. For any screen an agent builds, use superwall-framework instead (paywalls, onboarding, update-required, lifecycle prompts, announcements, offers and web flows, as React code); to move an existing editor paywall onto it, run `superwall migrate <paywall-id>`. Use this skill only when the user explicitly wants to edit inside the visual editor, or to read an editor paywall before migrating it. Covers attach/call/release, native sw-* elements and the editor tool surface.
4
+ ---
5
+
6
+ # Superwall Paywall Editor
7
+
8
+ > [!WARNING]
9
+ > **LEGACY. For agents, the visual editor is the second choice.** Any screen
10
+ > an agent builds (a paywall, an onboarding, an update-required screen, a
11
+ > lifecycle prompt, an announcement, an offer, a web flow) belongs in the
12
+ > **superwall framework**: a React mini-app in the user's repo, reviewed as
13
+ > code, localized from message files, previewed in the studio on every
14
+ > device, and shipped with `superwall push` / `promote`. Use the
15
+ > `superwall-framework` skill. If it isn't installed:
16
+ >
17
+ > ```bash
18
+ > npx skills add https://github.com/superwall/skills/tree/next --skill superwall-framework --global --yes --agent claude-code universal --full-depth
19
+ > ```
20
+ >
21
+ > The framework is on the `next` channel: the CLI has its commands only
22
+ > while `SUPERWALL_CHANNEL=next` is set (an `Unknown command: create` means
23
+ > it is missing; ask the user to set it in their shell rc and relaunch).
24
+ >
25
+ > **An editor paywall moves over in one command:**
26
+ >
27
+ > ```bash
28
+ > superwall migrate <paywall-id>
29
+ > ```
30
+ >
31
+ > It scaffolds the paywall as code, briefs the rebuild (the framework
32
+ > skill's `references/migrate-from-editor.md` is the playbook), and shows
33
+ > the original beside the new one in the studio (Compare › Original). The
34
+ > original keeps serving until a campaign is switched to the new one, so
35
+ > nothing changes for users until then.
36
+ >
37
+ > **What to do here:**
38
+ >
39
+ > - Asked to build any new screen: build it with the framework, not here.
40
+ > - Asked to change an editor paywall: offer the migration first, in one
41
+ > line, saying what it gains (code review, localization files, any
42
+ > component library, the same studio for every screen). If the user
43
+ > says no or wants a quick edit in place, continue with this skill.
44
+ > - Never migrate unprompted, and never refuse an explicit editor request.
45
+
46
+ Paywalls are built in a browser editor that exposes its tools over an authenticated relay. This skill drives the same surface used by the MCP gateway, so every tool runs inside the live browser session the user has open.
47
+
48
+ ## When to use
49
+
50
+ - The user wants to build, edit, or review a Superwall paywall, onboarding, or web2app flow.
51
+ - The user pastes a pairing code and asks you to take over editing.
52
+ - The user asks "what tools can you run right now?" Discover them via the browser, not from memory.
53
+
54
+ ## Start here: attach, then discover
55
+
56
+ Never assume a tool name or signature from memory. The browser is the source of truth and its tool set changes across releases.
57
+
58
+ For `--agent-name`, use your agent's recognized slug, such as `codex`, `claude`,
59
+ or `cursor`. Use `other` for Grok Build, Muse Code, or any agent not listed in
60
+ the [CLI reference](references/cli.md#agent-identity).
61
+
62
+ Preferred API launch flow:
63
+
64
+ 1. Create an auto-expose URL: `scripts/sw-editor.sh expose --application-id <id> --paywall-id <id> --agent-name <agent> --open --wait`
65
+ 2. Ask the user to complete browser authorization if prompted. The editor auto-exposes; do not ask them to click the expose button.
66
+ 3. Discover what is available right now: `scripts/sw-editor.sh tools`
67
+ 4. Invoke tools: `scripts/sw-editor.sh call <tool-name> --args '<json>'`
68
+
69
+ Fallback manual flow:
70
+
71
+ 1. Ask the user for the **pairing code** shown in the editor UI.
72
+ 2. Attach: `scripts/sw-editor.sh attach <pairing-code> --agent-name <agent>`
73
+ 3. Continue with `tools` and `call`.
74
+
75
+ Full CLI reference: [references/cli.md](references/cli.md).
76
+
77
+ ## How to build and edit
78
+
79
+ - Workflow, build order, and when to use which tool: [references/workflow.md](references/workflow.md)
80
+ - Native `sw-*` elements (multiple-choice, indicator, drawer, picker, lottie, navigation): [references/native-elements.md](references/native-elements.md)
81
+ - Design standards, review checkpoints, typography, and conversion principles: [references/design.md](references/design.md)
82
+
83
+ ## Orchestration rules
84
+
85
+ - Always establish an attachment before editing. Use `expose --open --wait` when possible, otherwise use `attach <pairing-code> --agent-name <agent>`. `tools`, `call`, `status`, `release` all require an attached session.
86
+ - Prefer `expose --open --wait` when you have `SUPERWALL_API_KEY`, an application id, and a paywall id. It uses the same relay as manual pairing but removes the human pairing-code step.
87
+ - Before calling a tool you have not used this session, run `tools` to confirm it exists and to read the current parameter schema. Tools are defined in the browser bundle, so an updated editor can ship new or renamed tools without changing this skill.
88
+ - Use `get_screenshot` (if present in the tool list) every two or three modifications to verify. Don't fly blind.
89
+ - Prefer semantic tools (`update_styles`, `set_text_content`, `set_dynamic_value`, `move_nodes`) over re-running `write_html` on existing structure. See `references/workflow.md`.
90
+ - Prefer native `sw-*` elements over hand-rolled `<div>` recreations whenever the UI represents a semantic control. See `references/native-elements.md`.
91
+ - When parsing CLI output, use `jq`, not Python. Example: `sw-editor.sh call get_subtree --args '...' | jq -r '.content[0].text'`
92
+ - Release when the user is done: `scripts/sw-editor.sh release`.
93
+
94
+ ## When things go wrong
95
+
96
+ - `session_not_ready`: the browser disconnected or reloaded. Ask the user to bring the editor tab back, then re-attach. The pairing code rotates, so they must provide the new one.
97
+ - `session_locked`: another client is already attached. The user either attached from another MCP client, or a previous CLI attachment wasn't released. They can detach from the editor UI and you can retry.
98
+ - `unauthorized`: the controller token is stale. Re-attach with a fresh pairing code.
99
+ - `attach_failed: provide a valid current pairingCode`: pairing codes expire after ~10 minutes and rotate on detach. Ask the user to show you the current one.
100
+
101
+ ## Report what's broken
102
+
103
+ When you confirm an editor tool misbehaves (wrong result, a crash, a schema
104
+ that doesn't match `tools`, a doc here that's wrong), report it yourself:
105
+ write it with every ID needed to reproduce it, tell the user in one line,
106
+ send on their yes (or straight away if they've said you may). Strip secrets
107
+ and customer data.
108
+
109
+ ```bash
110
+ superwall feedback "Called X with Y; expected Z; got W." --title "..." \
111
+ --kind bug --command "sw-editor.sh call <tool>" --app <id> \
112
+ --context paywall=<id> --file error.json --json
113
+ ```
@@ -0,0 +1,135 @@
1
+ # sw-editor.sh CLI reference
2
+
3
+ The CLI is a thin bash wrapper over the Superwall editor relay. It speaks the same public HTTP surface the MCP gateway uses, authenticated by a short-lived controller token issued during attach. Tool definitions come from the browser. **Never hardcode tool names; always run `tools` first** when unsure.
4
+
5
+ ## Prerequisites
6
+
7
+ - `curl` and `jq` installed (both present by default on macOS/Linux, or one `brew install jq` away).
8
+ - For `expose`: a `SUPERWALL_API_KEY` with read access to the paywall.
9
+ - For manual `attach`: a live browser editor session with a visible pairing code.
10
+
11
+ ## Environment
12
+
13
+ | Variable | Default | Purpose |
14
+ | --- | --- | --- |
15
+ | `SUPERWALL_EDITOR_BASE_URL` | `https://mcp.superwall.com` | Relay base URL. Override for custom environments. |
16
+ | `SUPERWALL_EDITOR_WEB_URL` | `https://superwall.com/editor/` | Editor URL used by `expose`. Override only when the user provides a custom editor URL. |
17
+ | `SUPERWALL_API_KEY` | unset | Org API key used by `expose` / `wait-expose`. Also read from this skill `.env`, sibling `superwall/.env`, or `~/.superwall-cli/.env`. |
18
+ | `SUPERWALL_STATE_DIR` | `$PWD/.superwall` | Where to store attachment state. |
19
+
20
+ ## State file
21
+
22
+ `${SUPERWALL_STATE_DIR}/state.json`, chmod 600. Holds `{sessionId, controllerToken, baseUrl, transportSessionId, attachedAt}`. Treat it as an opaque implementation detail. Never read `sessionId` out of it when communicating with the user, and never echo `controllerToken`. The CLI's `status` and `whoami` commands already strip these.
23
+
24
+ ## Commands
25
+
26
+ ### Agent identity
27
+
28
+ Both `attach` and `expose` require `--agent-name`. Accepted slugs are
29
+ `superwall`, `claude`, `codex`, `cursor`, `opencode`, `windsurf`, `kilocode`,
30
+ `chatgpt`, `openwebui`, and `other`. Use `other` for Grok Build, Muse Code, or
31
+ any unlisted agent. The script sends the corresponding display name to the
32
+ editor so the user can see who is attached.
33
+
34
+ ### expose
35
+
36
+ ```
37
+ sw-editor.sh expose --application-id <id> --paywall-id <id> --agent-name <name> [--open] [--wait]
38
+ ```
39
+
40
+ Creates a short-lived editor launch URL through the relay API. Opening the URL loads the editor for that paywall and auto-exposes the browser session; the user only completes normal browser authorization if prompted. Launch creation and polling require `SUPERWALL_API_KEY`; the browser-side ready call uses only the short-lived launch token embedded in the URL. `--agent-name` is required so the editor can show which agent is attached.
41
+
42
+ Use `--open --wait` for the smoothest flow. The CLI opens the browser, polls the launch, and writes controller state once the editor connects.
43
+
44
+ Example:
45
+
46
+ ```bash
47
+ sw-editor.sh expose --application-id 5 --paywall-id 28 --agent-name codex --open --wait
48
+ ```
49
+
50
+ ### wait-expose
51
+
52
+ ```
53
+ sw-editor.sh wait-expose <launch-id> [--timeout <seconds>]
54
+ ```
55
+
56
+ Polls a launch created by `expose` until the browser editor auto-exposes and the CLI receives a controller token. Useful when `expose` was run without `--wait`.
57
+
58
+ ### attach
59
+
60
+ ```
61
+ sw-editor.sh attach <pairing-code> --agent-name <name>
62
+ ```
63
+
64
+ Exchange the single-use pairing code for a controller token and cache it locally. The pairing code is consumed on success; if you fail (bad code, expired code, editor disconnected, another client attached), the user needs to refresh the editor UI for a new one.
65
+
66
+ On success the response carries the browser's full tool list, but the CLI prints only a count. Run `tools` for details.
67
+
68
+ ### tools
69
+
70
+ ```
71
+ sw-editor.sh tools
72
+ ```
73
+
74
+ Prints `{toolDefinitions: [{name, description, parameters}], metadata}` as JSON. Always run this before calling an unfamiliar tool. Tool shapes can change when the editor ships.
75
+
76
+ ### call
77
+
78
+ ```
79
+ sw-editor.sh call <tool-name> [--args '<json>']
80
+ ```
81
+
82
+ Invokes a tool in the browser. `--args` must be valid JSON (defaults to `{}`). Prints the `CallToolResult` (`{content, isError, ...}`). Exits 1 when `isError: true`.
83
+
84
+ Example:
85
+
86
+ ```bash
87
+ sw-editor.sh call write_html --args '{"targetNodeId": "page:page", "position": "append", "html": "<h1>Hello</h1>"}'
88
+ ```
89
+
90
+ ### status
91
+
92
+ ```
93
+ sw-editor.sh status
94
+ ```
95
+
96
+ Prints session status (browser connectivity, pairing code freshness, metadata). Internal IDs are stripped from the output.
97
+
98
+ ### release
99
+
100
+ ```
101
+ sw-editor.sh release
102
+ ```
103
+
104
+ Notifies the relay, clears local state. Call when the user says they're done, or before attaching to a different session.
105
+
106
+ ### whoami
107
+
108
+ ```
109
+ sw-editor.sh whoami
110
+ ```
111
+
112
+ Prints `{attached, baseUrl, attachedAt}` without internal identifiers. Useful for confirming whether a session is cached.
113
+
114
+ ## Attach / call / release flow
115
+
116
+ ```
117
+ ┌────────────────┐ pairingCode ┌────────────────┐
118
+ │ Editor UI │ ────────────► │ User │
119
+ │ (browser) │ └────────────────┘
120
+ └────────────────┘ │ reads code aloud
121
+ ▼
122
+ ┌────────────────┐ POST /editor-sessions/claim
123
+ │ sw-editor.sh │ ────────────────────────┐
124
+ │ attach │ │
125
+ └────────────────┘ ▼
126
+ ▲ ┌───────────────┐
127
+ controllerToken │ Relay DO │
128
+ │ │ (per session)│
129
+ ┌────────────────┐ └───────────────┘
130
+ │ sw-editor.sh │ Authorization: Bearer ▲
131
+ │ call/tools/… │ ──────────────────────┘
132
+ └────────────────┘
133
+ ```
134
+
135
+ The controller token dies when the session expires or when `release` is called. Re-attach with a fresh pairing code, or create a fresh `expose` launch, to get a new token.
@@ -0,0 +1,51 @@
1
+ # Design Guide
2
+
3
+ Paywalls are purchase screens. Flows are multi-page experiences (onboardings, surveys, web2app retargeting). Both must feel polished, trustworthy, and optimized for their goal.
4
+
5
+ ## Review Checkpoints
6
+
7
+ After every 2-3 modifications, call `get_screenshot` and evaluate each:
8
+
9
+ - **Spacing**: Uneven gaps, cramped groups, areas that feel unintentionally empty
10
+ - **Typography**: Text too small, poor hierarchy between heading/body/caption
11
+ - **Contrast**: Low contrast text, elements blending into backgrounds
12
+ - **Alignment**: Elements that should share a lane but don't
13
+ - **Clipping**: Content cut off at edges (fix with `update_styles`, set dimension to `fit-content`)
14
+ - **CTA Clarity**: Purchase button must have the strongest visual weight
15
+
16
+ Summarize each into a one-line verdict. Fix issues before moving on.
17
+
18
+ ## Design Brief
19
+
20
+ Before writing HTML, generate:
21
+
22
+ 1. Color palette: 4-5 hex values (background, surface, text, accent, secondary)
23
+ 2. Type scale: headline/body/caption sizes and weights
24
+ 3. Spacing rhythm: section gaps, element gaps, padding
25
+ 4. One sentence visual direction
26
+ 5. CTA style: color, shape, text
27
+
28
+ ## Typography Hierarchy
29
+
30
+ | Level | Size | Weight | Purpose |
31
+ |-------|------|--------|---------|
32
+ | Hero | 28-36px | 700-800 | Short, punchy |
33
+ | Subheadline | 16-18px | 400-500 | 1-2 sentence value prop |
34
+ | Features | 14-16px | 400 | Benefit descriptions |
35
+ | Price | 20-28px | 700 | Clear currency + period |
36
+ | CTA | 16-18px | 600-700 | Action verb ("Start Free Trial") |
37
+ | Legal | 12px | 400 | Muted, cancellation terms |
38
+
39
+ ## Conversion Principles
40
+
41
+ - **One strong accent** for the CTA beats multiple colors. Build palette from neutrals first.
42
+ - **CTA buttons**: full-width, 16px+ vertical padding, strong background, clear text.
43
+ - **Trust signals**: trial duration, guarantee, cancellation policy, social proof.
44
+ - **Avoid clutter**: max 3 pricing options, 5-7 feature items.
45
+ - **Placeholder content**: realistic pricing ($4.99/week, $12.99/month, $49.99/year).
46
+
47
+ ## Build Cadence
48
+
49
+ - One visual group per `write_html` call (header, feature row, pricing card, CTA, footer).
50
+ - A full paywall = 5+ separate calls. Never batch everything into one.
51
+ - Screenshot every 2-3 modifications. The user watches in real-time.
@@ -0,0 +1,171 @@
1
+ # Superwall Native Elements Guide
2
+
3
+ When using `write_html`, prefer native `sw-*` elements over generic HTML whenever the UI represents a semantic control. Native elements stay editable, bindable, and tool-aware inside the editor.
4
+
5
+ ## When to use which element
6
+
7
+ | UI pattern | Element | Key attributes |
8
+ |------------|---------|---------------|
9
+ | Selectable options, surveys, radio/checkbox cards | `<sw-multiple-choice>` | `selection-mode`, `<sw-option>`, `<sw-choice-item>` |
10
+ | Dots, pills, progress bars, step indicators | `<sw-indicator>` | `current-index`, `total-items`, `<sw-indicator-item>` |
11
+ | Drawers, bottom sheets | `<sw-drawer>` | `dismissible`, `detents`, `open-state` |
12
+ | Date/time/custom wheel pickers | `<sw-picker>` | `picker-type`, `picker-style`, `components`, `columns` |
13
+ | Animations | `<sw-lottie>` | `src`, `autoplay`, `loop`, `speed` |
14
+ | Multi-page flows | `<sw-navigation>` | `transition`, `<sw-page>` children |
15
+
16
+ ## Native-first rules
17
+
18
+ - Selectable answers, survey options, radio rows, checkbox rows, tappable choice cards: use `<sw-multiple-choice>`.
19
+ - Dots, pills, segmented progress, linear progress bars, onboarding progress: use `<sw-indicator>`.
20
+ - Drawers, bottom sheets, slide-over panels: use `<sw-drawer>`.
21
+ - Date, time, or custom wheel pickers: use `<sw-picker>`.
22
+ - Lottie animations: use `<sw-lottie>`.
23
+ - Multi-page onboarding or paywall flows: use `<sw-navigation>` with `<sw-page>` children, then wire entry/routes with the dedicated navigation tools.
24
+ - Use plain HTML for layout, text, and visuals only when there is no native element that represents the control.
25
+
26
+ ## Multiple choice
27
+
28
+ Use `<sw-multiple-choice>` for any selectable list. Supply choices with direct `<sw-option>` children.
29
+
30
+ ```html
31
+ <sw-multiple-choice selection-mode="single">
32
+ <sw-option label="Cook at home" value="cook-home" />
33
+ <sw-option label="Order delivery" value="delivery" />
34
+ <sw-option label="Eat out" value="eat-out" />
35
+ </sw-multiple-choice>
36
+ ```
37
+
38
+ If you need a custom repeated row layout, provide at most one direct `<sw-choice-item>` template child:
39
+
40
+ ```html
41
+ <sw-multiple-choice selection-mode="single" style="gap:12px;">
42
+ <sw-option label="Starter" value="starter" />
43
+ <sw-option label="Pro" value="pro" />
44
+ <sw-choice-item style="background-color:#ffffff;border-radius:16px;padding:18px 20px;" />
45
+ </sw-multiple-choice>
46
+ ```
47
+
48
+ Important:
49
+
50
+ - `<sw-option>` is only valid as a direct child of `<sw-multiple-choice>`.
51
+ - `<sw-multiple-choice>` accepts at most one direct `<sw-choice-item>`.
52
+ - Do not create one `<sw-choice-item>` per option.
53
+ - Any visual or content difference between options should be implemented by dynamically changing child nodes inside the single `<sw-choice-item>` template.
54
+ - If the design has selected and unselected states, implement both states explicitly. Selected cards, checkmarks, highlights, borders, icons, and labels should respond correctly to `state:self.isSelected`, and the unselected fallback should also be defined.
55
+
56
+ ### Per-choice specialization
57
+
58
+ Per-choice icons, subtitles, colors, badges, visibility, and other specialized content are supported through the single template child. Create one `<sw-choice-item>` template, place child SVG/text/container nodes inside it, then call `set_dynamic_value` on those child nodes using self-scoped template state.
59
+
60
+ Use:
61
+
62
+ - `state:self.value` to branch by the option value.
63
+ - `state:self.label` to branch by label text.
64
+ - `state:self.index` to branch by position.
65
+ - `state:self.isSelected` to branch by selected state.
66
+ - `state:self.isFirst` and `state:self.isLast` for edge-specific layout tweaks.
67
+
68
+ ```html
69
+ <sw-multiple-choice selection-mode="single" style="gap:16px;">
70
+ <sw-option label="Improve sleep" value="sleep" />
71
+ <sw-option label="Improve focus" value="focus" />
72
+ <sw-option label="Regulate emotions" value="emotions" />
73
+ <sw-option label="Enhance energy" value="energy" />
74
+ <sw-choice-item style="border-radius:20px;padding:20px;">
75
+ <svg width="40" height="40" viewBox="0 0 40 40"></svg>
76
+ <p>Improve sleep</p>
77
+ <p>Subtitle</p>
78
+ <div style="display:none;">Popular</div>
79
+ </sw-choice-item>
80
+ </sw-multiple-choice>
81
+ ```
82
+
83
+ Then use `set_dynamic_value` on whatever child properties need specialization (SVG src, subtitle text, background color, badge visibility).
84
+
85
+ Never solve per-option specialization by creating multiple `sw-choice-item` nodes.
86
+
87
+ ## Indicator
88
+
89
+ Use `<sw-indicator>` for dots, segments, or progress bars. Style the single repeated `<sw-indicator-item>` template.
90
+
91
+ ```html
92
+ <sw-indicator current-index="1" total-items="3" style="width:100%;gap:8px;">
93
+ <sw-indicator-item style="height:6px;border-radius:3px;" />
94
+ </sw-indicator>
95
+ ```
96
+
97
+ Important:
98
+
99
+ - `<sw-indicator>` accepts at most one direct `<sw-indicator-item>`.
100
+ - Do not create one `<sw-indicator-item>` per segment manually.
101
+
102
+ Self-scoped fields: `state:self.index`, `state:self.isCurrent`, `state:self.isCompleted`, `state:self.isFirst`, `state:self.isLast`.
103
+
104
+ ## Drawer
105
+
106
+ ```html
107
+ <sw-drawer dismissible="true" detents="0.25,0.5,1" background-interactive="false">
108
+ <p>Drawer content</p>
109
+ </sw-drawer>
110
+ ```
111
+
112
+ Use `open-state="state:..."` when the drawer should bind to an external state.
113
+
114
+ ## Picker
115
+
116
+ ```html
117
+ <sw-picker
118
+ picker-type="date"
119
+ picker-style="wheel"
120
+ components="date-and-time"
121
+ minute-interval="5"
122
+ min-date="today"
123
+ max-date="+1 month"
124
+ />
125
+
126
+ <sw-picker
127
+ picker-type="weight-kg"
128
+ columns='[{"source":"range","id":"weight","min":10,"max":250,"step":1,"labelSuffix":" kg","width":96}]'
129
+ output-template="{weight}"
130
+ />
131
+ ```
132
+
133
+ Supported `components`: `date`, `date-and-time`, `time`, `time-list`.
134
+ Custom picker types are `custom`, `number`, `age`, `weight-kg`, `weight-lb`, `height-cm`, `height-imperial`, and `duration`. They use `picker-style="wheel"`, optional JSON `columns`, and optional `output-template`. Columns auto-size to the widest option unless a numeric `width` is provided. Output templates can use `{columnId}` or `{columnId.label}`.
135
+
136
+ ## Navigation
137
+
138
+ Use `<sw-navigation>` for multi-page flows. Each `<sw-page>` child becomes one page.
139
+
140
+ ```html
141
+ <sw-navigation transition="push">
142
+ <sw-page data-name="Welcome">
143
+ <p>Welcome</p>
144
+ </sw-page>
145
+ <sw-page data-name="Plans">
146
+ <p>Choose a plan</p>
147
+ </sw-page>
148
+ </sw-navigation>
149
+ ```
150
+
151
+ After creating structure, use navigation tools:
152
+ 1. `get_navigation_pages` to discover page IDs
153
+ 2. `set_navigation_entry_connection` for the starting page
154
+ 3. `set_navigation_connection` for page-to-page wiring
155
+ 4. `set_click_behavior` with `navigate-page` direction `next`/`back`
156
+
157
+ Do not encode routes in HTML. Do not pass target page IDs in click behavior.
158
+
159
+ ## Lottie
160
+
161
+ ```html
162
+ <sw-lottie src="https://example.com/animation.json" autoplay loop speed="1.0" />
163
+ ```
164
+
165
+ ## Constraints
166
+
167
+ - Leaf nodes (text, image, input, video, svg, lottie, picker) cannot contain children.
168
+ - `choice-item` is only valid as the single direct template child of `multiple-choice`.
169
+ - `indicator-item` is only valid as the single direct template child of `indicator`.
170
+ - Self-scoped template state is only valid inside `choice-item` or `indicator-item` subtrees.
171
+ - If a screenshot visually resembles a native control, prefer the native control.