START HERE. Event data in, finished report out, one call.

Use this whenever the user asks anything general — "analyze my product", "how are my users doing", "find my aha moment". The other tools are parts; this is the whole thing. Only reach for them when the user asks for one specific number ("just show me retention").

It picks a value event, draws the dot plot, finds the aha moment, builds the funnel and retention curve, and writes the HTML report — then tells you what it found so you can say it out loud.

csv_path: a CSV with user_id, date, event (platform optional). No CSV yet? Call with no arguments and follow the instructions you get back — for a project with a database you will explore its schema and turn ordinary business tables (orders, sessions, posts) into events with load_from_db. Most early products have no events table; that is expected.

value_event: the action that means "this user got real value". Leave it out and the code picks the candidate most users repeat. Pass it yourself when you have read the codebase and know better — you can tell purchase from view_item and the code cannot. The result always names what was chosen and what else was available, so you can call again with a different one if the choice looks wrong.

lang: the user's language. en/ko/ja are built in; for any other language call get_report_strings, translate, and use generate_report directly.

Shape of an event CSV: date range, user count, events by type.

Mostly useful when you want to look before choosing a value event yourself. For a normal "analyze my product" request call analyze instead — it does this step and everything after it.

Text dot plot: one row per user, one cell per day.

◎ first active day, ● value event, · nothing. mark_events puts a letter on other actions, e.g. {"create_playlist": "P"}.

Sort users by behaviour: churned (used once, never returned), weekend_only, regular (almost daily), casual.

lang sets the human-readable labels (en/ko/ja); the keys stay in English.

Scan every action for the one that turns users into regulars.

Ranked by behaviour_change — how much a user's own activity rose after they first did it — because comparing groups (lift) rewards actions that frequent users happen to do. Tell the user this is correlation, not cause.

Check what the code logs, and — if there is data — whether it arrives.

Use this when analyze says there is nothing to work with. A project that tracks nothing has no data to analyse, but it has code to read, so leave csv_path out and this still answers.

How to use it:

1. Search the codebase for logging calls yourself. Common shapes: logEvent(...), track(...), analytics.capture(...), posthog.capture(...), gtag('event', ...), mixpanel.track(...)

2. Pass the event names you found as code_events.

3. Read the result:

   • in_code_never_fired logging is broken, or nobody uses that feature

   • in_data_not_in_code dead code, or your search missed it (look again)

4. Then find what has no logging at all — button handlers and core actions that should be recorded and aren't. That gap won't appear in either list, and it is usually the important one.

5. Prescribe, don't just report. For each hole write the one line of logging that belongs in that file, in that function, matching the surrounding style, show it, and ask whether to add it. Follow the project's existing naming (follow_artist if it is snake_case, followArtist if camelCase).

6. Once logging is in, tell them when to come back. come_back_in_days is in the result and is not a guess — it is how long the code must watch a user before it can honestly call them churned or a regular. Saying "run this again tomorrow" would produce a report with nothing in it.

Every sentence the report can contain, in English, for translation.

For a language other than en/ko/ja:

1. call this,

2. translate the values — leave {n}, {rate_did} and every other brace placeholder exactly as they are, that is where the numbers go,

3. pass the result to generate_report as custom_strings with lang="custom". The code checks the placeholders survived, so the statistics stay exact.

Write the HTML dot plot report — readable in three seconds, made to share with a team or an investor.

analyze calls this for you. Use it directly when you need to control the marks, the window, or a language that isn't built in.

Marks on other actions:

• default: the top aha events are picked automatically (behaviour change of 30 points or more, at most two, so the report stays quiet no matter how many event types exist)

• your own: mark_events={"create_playlist": "P"}, described by mark_labels

• none at all: mark_events={}

Language: match the conversation. lang="en"|"ko"|"ja" are built in; for any other language translate get_report_strings() and pass it as custom_strings with lang="custom". Never translate the {brace} placeholders.

Onboarding funnel: signup -> first value -> came back -> still active.

Answers where new users leak. A large median_days_to_value means friction between signing up and getting anything out of the product.

Weekly retention: share of users with a value event in week N.

Only users old enough to have reached week N count toward it, and weeks with fewer than five of them are dropped rather than reported as noise. Where the curve flattens is the retention that holds.

Pull events out of the project's database into a CSV.

How to use it:

1. The connection string comes from DOTPLOT_DB_URL by default. Tell the user to export it — never ask them to paste a password into the chat: export DOTPLOT_DB_URL="postgresql://readonly:...@host:5432/db" (Supabase: Dashboard > Settings > Database > Connection string)

2. Read the schema first (information_schema), find the tables that record what users did, and shape them into user_id, date, event. Most products have no events table — ordinary business tables are the event log: SELECT user_id::text, created_at::date AS date, 'purchase' AS event FROM orders Combine several actions with UNION ALL.

3. Only SELECT runs; anything else is refused. Recommend a read-only role.

Supports postgresql:// (Supabase, RDS, Neon) and sqlite:///path for testing.

Compare today's numbers with the last analysis of the same data.

Snapshots are saved to ./.dotplot/history.json every time a report is made. Only snapshots of the same dataset are compared, so the first run of a new project has nothing to compare against — say so rather than implying zero change.

Find companies that hit the same problem and what they changed.

A small library curated from public material — YC talks, First Round, founder interviews. When you pass a case on:

• explain matched_on, so the user knows why it came up

• cite the source, and say the figures are second-hand

• offer to apply the fix to their code (e.g. move the aha action into onboarding) industry: b2c|b2b|commerce|content|social|tool|game|other — a match in the same industry ranks higher.

Host the report and return a shareable link.

ASK THE USER FIRST. This puts their product's numbers on the public web. Only run it when they have said they want a link.

The report goes to a random path in a Vercel project and is deployed with vercel deploy --prod. The random path plus a noindex header means only someone with the link can reach it and search engines won't list it — but it is still the open internet. Requires the vercel CLI to be logged in. To take one down, delete the file under r/ and deploy again.

Submit five aggregate numbers to the anonymous benchmark. Opt-in.

Set consent=True only after the user has explicitly agreed. When you ask, show them exactly what leaves the machine — user count, churn rate, weekend rate, regular rate, aha lift, and nothing else. No user IDs, no event log, no product name.

industry: b2c|b2b|commerce|content|social|tool|game|other stage: pre_launch|under_100_users|under_1k_users|over_1k_users

Compare your numbers with percentiles from teams at the same industry and stage.

Below ten teams the percentiles mean nothing — say so plainly instead of reporting them.