Add Daily Five friend challenges and measure referred play

README.md

@@ -38,7 +38,7 @@ Free. No login. No downloads. No sound needed.
 
 - **One shared Daily Five.** Five different puzzle types, determined by your device’s date. Players on the same date get the same challenge.
 - **Close counts.** Every round is worth 100 points. See your guess and the target together, then inspect small comparisons in your final results.
-- **Compare with friends.** Share a compact scorecard with the date, puzzle emojis, and your total. No answer spoilers.
+- **Compare with friends.** Share your Daily Five results as a compact scorecard with the date, puzzle emojis, and your total. No answer spoilers.
 - **Practice when you feel like it.** Open the Practice menu for a fresh mix or an individual skill. Trivia practice draws from past Daily Fives, keeping upcoming questions out of the pool.
 - **Pick your atmosphere.** Night Lab or Focus. Your choice sticks between visits.
 - **Come back later.** Daily progress, streaks, and recent results stay in your browser. No account required; no cross-device sync.

docs/ANALYTICS.md

@@ -15,10 +15,14 @@ requests are sent:
 | Pageview | First visit in a browser on a device-calendar day | None |
 | `daily_started` | First puzzle interaction in Daily Five | None |
 | `daily_completed` | Fifth answer committed in Daily Five | `total`, plus one score keyed by each of the five puzzle types |
-| `results_share_clicked` | First Share results click per browser per calendar day, in any game mode | None |
+| `results_share_clicked` | First Share results click per browser per calendar day, in Daily Five | None |
+| `challenge_share_clicked` | First Challenge a friend click per browser per calendar day | None |
+| `challenge_visit` | First visit through a valid challenge for today's Daily Five | None |
+| `challenge_start` | First Daily Five interaction through that challenge | None |
+| `challenge_complete` | First Daily Five completion through that challenge | None |
 
-Individual mini games, practice and retries do not send playing events. Their
-share clicks count toward the same single daily share event. Controls, rounds,
+Individual mini games, practice and retries do not send playing events. Practice
+results have no share or friend-challenge controls. Controls, rounds,
 theme changes, timing and performance are not tracked. Sharing measures intent
 (button click), including clipboard fallback, rather than proving an external post.
 Opening a completed saved game does not emit completion. Theme switches and
@@ -29,7 +33,7 @@ scores. This minimal schema cannot show abandonment by round or time per puzzle.
 
 The browser ledger keeps only seven days of four flags, capped on read at 4 KB.
 No growing event backlog is stored. Tracking failures never stop play. At most
-four requests are held in memory while the script loads, with no retries or
+eight requests are held in memory while the script loads, with no retries or
 historical uploads. A blocked or failed request can therefore be undercounted.
 Storage clearing, unavailable storage across reloads and simultaneous tabs can
 also affect deduplication; these are approximate analytics, not authoritative
@@ -47,5 +51,19 @@ Umami's usage dashboard, especially if this account tracks other websites.
 References: https://umami.is/pricing and
 https://docs.umami.is/docs/tracker-configuration.
 
+Friend challenges contain only a Central-calendar date and a self-reported total
+in the URL. No answers, player ID, or individual referral identifier is included.
+Query strings remain excluded from analytics. Challenge events have no custom
+properties; an incoming completed-and-shared challenge can add four requests to
+the existing ten-unit daily budget. Expired or invalid challenges do not contribute
+challenge visit/start/completion events. A shared score is a friendly comparison,
+not an authenticated leaderboard entry.
+
+Challenge events count browser days and share intent, not verified delivery or
+unique invitees. Ratios across these counts are directional: repeat visitors,
+cross-day arrivals, cancelled shares, lost parameters, tracker blocking and links
+received after an earlier daily completion can affect them. Loading saved results
+never re-emits completion. Use the same date window when comparing counts.
+
 Run `node tests/verify-analytics.cjs` after building. The regular game checks
 also cover analytics integration without contacting Umami.

docs/GROWTH.md

@@ -0,0 +1,78 @@
+# Perception growth experiment
+
+## Starting evidence
+
+Umami shared-dashboard aggregate snapshot, October 9, 2026 at approximately
+5:35 p.m. Central, queried over the preceding 30 days:
+
+| Recorded activity | Count |
+| --- | ---: |
+| Visits / visitors / pageviews | 28 each |
+| Daily starts | 19 |
+| Daily completions | 17 |
+| Share-button clicks | 13 |
+| Mobile visits | 19 |
+| Laptop / desktop visits | 7 / 2 |
+
+Start-to-completion is approximately 89%; visits-to-start is 68%. This is a very
+small sample of deduplicated browser-day activity, not evidence of stable rates
+or a causal funnel. Share clicks may include practice and cancelled native sheets.
+No referrers were returned; messaging apps often remove referrer information.
+There is no measured referral conversion in the existing data.
+
+## First experiment: a score worth challenging
+
+The current completion screen offers **Challenge a friend** above ordinary result
+sharing. It produces a clickable HTTPS link carrying today's date and score.
+Recipients go straight into the Daily Five with a score to beat. Completion shows
+the difference, including a tie or loss, and invites a challenge back. A link from
+an earlier day explains that the challenge has ended and offers today's game.
+Practice results offer neither score sharing nor friend challenges. Existing daily puzzles,
+scoring, saved first attempts and compact result cards remain intact.
+
+This tests one hypothesis: a concrete score to beat will turn sharing into more
+completed daily games. It does not depend on accounts, a public leaderboard,
+fabricated popularity, or promises of viral growth.
+
+## Launch material
+
+Short post, ready to adapt for an audience the owner already participates in:
+
+> You think you can remember a colour. You know what 10 seconds feels like.
+> …Right? Perception tests that confidence with five daily puzzles and a score
+> out of 500. Free, no login, and silent. Play today's five, then send me your
+> challenge: https://perception.thedanktank.com/
+
+For a group chat, play today's game and use its generated challenge message:
+“I scored [your actual score]/500 on Perception. Can you beat me?” The generated
+link includes the real date and total. Do not reuse an old challenge as today's.
+
+For a short video, record one surprising missed guess and its reveal; keep
+today's answers out of public clips by recording practice. End with the actual
+score and “Five puzzles. Can you beat me?” Direct viewers to the public game.
+
+Distribution order: start with an existing friend group; invite participants to
+send their own challenges; then use one relevant puzzle community that permits
+self-promotion. Tailor each post and follow its rules. None of this outreach has
+been posted or sent by the agent.
+
+## Evaluate after seven days of real exposure
+
+Compare `challenge_share_clicked`, `challenge_visit`, `challenge_start`, and
+`challenge_complete` in Umami over the same window. Also watch overall Daily Five
+starts/completions so increased traffic does not hide a worse playing experience.
+
+- Few challenge clicks: improve the completion-screen invitation and share copy.
+- Clicks but few arrivals: check native sharing and link visibility in the apps
+  players actually use; ask consenting players what recipients saw.
+- Arrivals but few starts: simplify the first puzzle's instructions using player
+  feedback before adding another landing screen.
+- Starts but few completions: inspect feedback about confusing puzzles; the
+  current analytics cannot locate abandonment by round.
+- More completed challenges: keep the flow, expand exposure gradually, and check
+  returning-player retention before adding more features.
+
+Do not declare a winner from a handful of visits or divide these aggregate
+browser-day counts into an asserted viral coefficient. Actual growth requires
+continued distribution and repeated observations. Review Umami quota use if
+traffic rises. Publishing and outbound promotion are separate next actions.