tangent

/tangent — paywall test results, with the paywalls in view

One command discovers every running experiment in the app, pulls the Results-tab numbers for each through readout.py (a port of the dashboard's own SQL, so the figures equal what the client sees in Superwall), renders each paywall, and produces a finished report. Your job is to run it, publish what it produced, and give a short digest. Never re-derive numbers, never hand-build panels.

Step 0 — first run only

Python 3.9+ must exist (python3 --version).
Superwall CLI: superwall --help. Missing → npm install -g superwall (Node 18+).
Login: superwall whoami --json. If not authenticated, ask the person to run superwall bootstrap in their own terminal and sign in with their Superwall account, then pick their organization. The login is a browser flow. Never ask for, accept, echo, or store a password or API key. (Scripted setups may instead export SUPERWALL_API_KEY and SUPERWALL_ORG_ID in the shell — that is their choice, not something you set up or read back.)
App id: pass --app <id> (the number in the Superwall URL) or set app_id in config.json next to this file. With one app in the account it is found automatically.

Step 1 — run

python3 "<this folder>/tangent.py" --app <id>

Options: --filter <text> (only campaigns/audiences whose name contains it), --include-paused, --no-images, --refresh-images (re-render cached screenshots), --compare (what moved since the last run). Takes roughly one minute per experiment.

Outputs in out/<app_id>/ next to the script (the script prints the exact path):

artifact.html — the report as an Artifact fragment (screenshots embedded, light + dark themes)
report.html — same page, standalone; open locally if there is no Artifact tool
widgets/overview.html — numbers-only overview for an inline chat widget
read.json — every number; history/ — one snapshot per run

Step 2 — show it (both parts, every run)

Overview in the chat. Render out/<app_id>/widgets/overview.html verbatim as an inline widget (the widget/visualization tool, e.g. show_widget). One line per experiment with its verdict. This is what the person reads first.
Full report as a link. Publish out/<app_id>/artifact.html with the Artifact tool by file path (title is inside the file; favicon 📊 on the first publish; reuse the same path, or pass the earlier URL, so the link stays stable per app). The report carries the paywall screenshots and per-experiment panels. Images never go through the chat — a report with screenshots is around 1 MB.

Fallbacks: no inline widget tool → skip part 1 and describe the table in text. No Artifact tool → tell the person to open out/<app_id>/report.html. Never paste per-experiment panels or images into the chat, never edit numbers, never restyle or combine panels by hand.

Step 3 — digest

Five lines max, from the console table the script printed: one per experiment — name, status, the one number that matters (APPU gap and confidence %), then any skipped ones. Recommend action only on act (promote), lost (stop the challenger) or applied rows; watch, tie, thin and dark get no recommendation beyond "keep it running". Always mention the source table: line the script printed. Statuses are defined in PRINCIPLES.md.

Troubleshooting

not logged in → superwall bootstrap in their terminal.
app … is not visible to org → the login belongs to a different organization; log in with the account that owns the app.
A readout row skipped → the audience has no production data yet, or a query timed out; rerun once.
no running experiments found → every audience has one paywall (nothing to compare) or all are paused; try --include-paused.
Screenshots missing → Superwall's renderer was busy; the report falls back to the static preview or a link. Rerun later; results are cached per paywall version. Paywall images come from GET /v2/paywalls/{id}/preview-images only (server-side render with real prices; exit/abandon sheets arrive as kind: "overlay" pages and are shown after their host page). Never add a browser or Playwright step here.

Read-only: the script issues GET requests and SELECT queries. It cannot change paywalls, campaigns or weights. Nothing is sent anywhere except to Superwall.