feat(web): get new users from sign-in to a first useful result before widening access

This is an epic collecting a whole onboarding programme, explicitly to be split into sub-issues, so nothing here is startable directly; wait for or pick one sub-issue (for example the first-run checklist or the provider ordering). For orientation, the walkthrough names src/app/w/[workspace]/page.tsx as the landing redirect, src/components/sections/hero.tsx and src/lib/site.ts for the landing action, src/lib/adapters/registry.ts for the provider cards, and src/lib/dashboard/headline.ts for the "No comparison" states. Read the two review comments linked in the body before proposing anything; done means Eddie's options-table decisions land on the relevant sub-issue.

Context

An MVP readiness review on 2026-11-13 asked one question: what has to happen before DevMacro asks people beyond today's invited testers to use it, and what would make a new user think "I need this"?

Short answer: a new user cannot reach what DevMacro already does. They cannot get in without an invite, cannot connect a real account, and when they do, the first days show empty states and "No comparison" messages. The parts that set DevMacro apart (week comparisons, unusual day detection, projections, trend markers, MCP, badges) need one to two weeks of history or sit three or four clicks deep. #141 found the category has no leader and named Vantage as the real threat; reaching value fast is how DevMacro competes.

Eddie's call on 2026-11-13: do all of this next. That reverses the 2026-11-04 deferral recorded on #141, which moved #78, #88, #8, #121, #143, and #145 to Backlog. This issue collects the work and is split into sub-issues next. Work that already has an issue is linked, not restated.

Reviewed by Fable before splitting, two rounds: https://github.com/eddiejaoude/DevMacro/issues/411#issuecomment-6856151734 and https://github.com/eddiejaoude/DevMacro/issues/411#issuecomment-6856311386. This body applies both.

How the evidence was gathered

On the local dev server (localhost:3000, provider simulation on, viewport 1366 by 900), a throwaway invited account ([email protected]) was signed in through /auth/confirm and walked through every workspace tab, first empty, then after Explore with sample data. The account, its workspace, and its invite were deleted afterwards; its sign-in log entries remain (#359).

Findings

A. What stops people beyond the invited testers (existing issues)

B. Onboarding friction seen in the walkthrough

1. No first-run guidance. A new account lands on an empty Timeline; src/app/w/[workspace]/page.tsx only redirects there. Timeline, Dashboard, Alerts, and Projects each show their own empty state, and none shows progress through setup.
2. Provider choice is hard. Connections shows 11 provider cards of equal weight (12 locally with the fake provider, src/lib/adapters/registry.ts:86-88), each with 2 to 7 bullets under Data collected. Nothing suggests where a solo developer should start.
3. Connecting does not protect you. A new workspace has no alert rules, by design: #36 decided defaults are never enabled without the user seeing them (src/components/alerts/add-suggested-alerts.tsx:13). Suggested alerts needs Add these alerts selected once per provider (5 rows with sample data). Allowance suggestions exist only for providers that report allowances: Vercel, GitHub, Stripe, Polar, DigitalOcean, and Sentry declare allowance: false, so they get none. A user who connects and leaves never hears from DevMacro.
4. The first one to two weeks are mostly "can't tell you yet".
   • All six headline cards on the sample data dashboard said "No comparison: ... could not report the same days last week" (src/lib/dashboard/headline.ts:849).
   • A usage snapshot's day is the day it was retrieved (src/lib/jobs/ingest.ts:50), so no adapter can store a past day's value today.
   • Deploy and signup cards stay unavailable for any window that started before the connection's first reading (src/lib/dashboard/headline.ts:640), so even backfilled events do not fill them.
   • Event backfill on the first sync exists for some adapters (FIRST_SYNC_LOOKBACK_MS of 7 days in src/lib/adapters/vercel/index.ts:57, EVENTS_BACKFILL_MS of 30 days in src/lib/adapters/polar/index.ts:93); GitHub and Resend write no events on a first sync (src/lib/adapters/github/repositories.ts:115-116, src/lib/adapters/resend/index.ts:352).
   • Unusual day detection needs ANOMALY_MIN_HISTORY_DAYS = 7 (src/lib/alerts/anomaly.ts:74); projections need MIN_PROJECTION_DAYS = 3 (src/lib/dashboard/projection.ts:56).
5. The dashboard is very long. 14,396 CSS pixels at 1366 pixels wide with sample data. EUR and USD totals sit side by side with no explanation.
6. Sample data shows the weaker version of the product. It replays only the current week and the day before, at most nine steps "so it fits in a request" (src/lib/demo/workspace.ts:216-219, recorded on #257), so comparisons and the "what was unusual" summary never appear. npm run demo builds 90 days, but users cannot reach it.
7. Small things. The workspace URL is a generated id (/w/zmr5u7by3x); #258 added claimable handles for public pages only (src/lib/workspaces/handles.ts). The empty dashboard still offers Your 2026 so far.

C. Moments that would make a new user think "I need this"

D. Open bugs a tester would hit

• #336: a dashboard snapshot read can be cut at the row cap with no visible notice.
• #369: a failed alert delete is hidden after its confirmation dialog closes.
• #287: Explore with sample data can connect the simulated providers twice from two tabs.
• #297: allowance alert titles do not name the metric.
• #291: the dashboard's two lists of unusual days disagree.
• #358: a link's fragment is lost through sign-in.
• #325, #316, #240, #366: dialog errors, alert pagers, blank tab title, workspace switcher at small widths.
• #376: CSP missing on mis-cased proxied prefixes.
• Not tester-visible but blocks merging: #404 (six failing e2e tests).

Plan

Only step 1 needs hosted infrastructure. Steps 3, 8, and 11 can be built now on the local stack; steps 4, 5, 6, 7, 9, and 10 start with an options table for Eddie's decision. Each new-work step becomes a sub-issue of this one. Existing issues are linked as "blocked by", not re-parented, because most already have a parent (#78, #88, #89 under #3; #8 under #1; #90, #91, #93, #94 under #73).

1. Reachability (existing issues): #78, #88, #89, #90, #91 then #143, #8, #145, and the bugs in section D. New sub-issues: configure the alert email sender on the hosted app (docs/operations/deploy.md:146-147), and record product events for time to first value (sign-in, first connection, first alert rule). Depends on: nothing in this list.
2. Landing page call to action: no new sub-issue. Reopen Eddie's 2026-10-31 decision on #121 (options table already there) and deliver the demo link under #145. Depends on: #8, step 7.
3. First-run checklist: a setup panel on the Timeline (the workspace's landing page) with four steps: connect a provider, choose where alerts go, connect your assistant (C4), share a badge (C5). Each step shows done or not done from real workspace state and links to the control that does it. Dismissal is stored per member. Depends on: steps 5 and 11 for the step targets.
4. Recommended providers: order the catalog with a short Start here group and collapse Data collected behind a disclosure. Depends on: #141 question 3.
5. Alerts at connect (C2): in the connection's success state, offer that provider's suggested allowance rules preselected and ask where alerts go, with a test message. For providers with no allowance, offer a spend amount or budget rule (the rule kinds are allowance_percent, budget_percent, and spend_amount, src/lib/alerts/rule-schema.ts:135-158) and say that unusual day detection is already on (src/lib/alerts/anomaly.ts:2-3). Revisit the As each alert happens email default in the same decision. Depends on: the C2 decision, #297. Shares src/lib/jobs/sync-connection.ts with step 6.
6. Day one value (C1):
   • 6a. Decide how a backfilled past day is stored and read, since snapshot_date is the retrieval day (src/lib/jobs/ingest.ts:50) and the headline drops ended periods (src/lib/dashboard/headline.ts:248) and windows before the first reading (:640). Options table. Depends on: nothing.
   • 6b. Backfill usage history where the API allows it (table below), and add a GitHub first-sync event backfill. Depends on: 6a.
   • 6c. Show a first sync summary on the timeline, and where a comparison cannot exist yet, say the date it will appear instead of repeating "No comparison". Depends on: 6a for the date rule; the summary can ship on events alone.
7. Sample data that shows the product: build about 3 weeks of history for Explore with sample data and the #145 sandbox, enough for week comparisons, unusual days, and projections, built outside the request (a queued job) rather than inside it. Depends on: #287, the decision on where simulation may run (src/lib/adapters/simulated/index.ts:56).
8. Dashboard focus: at 1366 by 900, the headline, the unusual week summary, and the three allowances closest to their limit sit above the fold, with per-provider detail one level down. Explain mixed currencies beside the totals. Depends on: nothing.
9. Deploy to incident correlation (C3): when new Sentry issues are first seen within a window after a production deploy, mark it on the timeline and in Event details, linking the deploy. Sentry's error volume is a rolling 24 hour total stored daily (src/lib/adapters/sentry/index.ts:122-124, :646), so the trigger is new issues, not volume. Depends on: #155 (deployment environment), the window and count decision.
10. Small fixes: decide whether workspace URLs use the #258 handle; hide Your 2026 so far until the year has data. Depends on: nothing.
11. Badge from onboarding (C5): a one-step "Add a badge to your README" from the checklist that shows exactly what becomes public, then creates the project, publishes one metric, and shows the Markdown, under #147. Depends on: step 3, the default metric decision.
12. Weekly email (C6): a new sub-issue for the weekly stack email without the rank section, reusing the #152 digest. #157 keeps rank movement and stays behind the leaderboard (#156), which is a non-goal here. Depends on: the sender in step 1.
13. AI spend (C7): record Eddie's admin API key decision on #159 and #160; if approved, ship both adapters. #172 stays blocked and is tracked outside this issue.

Which providers can backfill usage history (from docs/providers/*.md)

Decisions needed

Eddie's, each with an options table on its sub-issue before code:

• C2: the status quo is #36's rule that no default is enabled without the user seeing it. Options: status quo, suggested and preselected at connect but confirmed once, or on by default with a visible opt-out.
• Step 2 (#121): the landing call to action while the repository is private, including whether a request-access form stores emails.
• Step 4: which providers make up Start here (#141 question 3).
• Step 6a: backfill storage and read model, and how many days back.
• Step 7: where simulation may run for the #145 sandbox. The guard refuses only a Vercel production deployment (VERCEL_ENV === "production", src/lib/adapters/simulated/index.ts:56); a preview deployment already allows it.
• Step 9: correlation window and minimum new-issue count.
• Step 10: whether /w/ URLs use the workspace handle.
• Step 1, activation measurement: which tool records time to first value (#94 names the options).
• Step 11: which metric and rounding the one-step badge publishes by default, given #147's "private until published, one metric at a time".
• C7: admin API keys for OpenAI and Anthropic (#159, #160).

Acceptance criteria

• Each new-work step (step 1's email sender and activation events, steps 3 to 12) is a sub-issue linked through Parent issue, with labels, Priority, Size, and a "Depends on" line. Existing issues in steps 1, 2, 9, and 13 are recorded as blocked-by on this issue.
• A visitor to the hosted landing page can open a demo or ask for access without a GitHub 404.
• A new invited user who connects Vercel (Pro), Stripe, or Polar on the hosted app sees backfilled events, a first sync summary, and an offer of a spend rule within 5 minutes of connecting.
• A user who connects Resend or Supabase is offered that provider's allowance rules at connect.
• Time from sign-in to first connected provider and to first alert rule is recorded.
• The first-run checklist reflects real workspace state, stays dismissed per member, and is keyboard operable with real links and buttons.
• Every headline card shows either a figure or the date its comparison will appear; none says only "No comparison".
• Explore with sample data and the #145 sandbox show week comparisons, unusual days, projections, and trend markers.
• At 1366 by 900 the dashboard shows the headline, the unusual week summary, and the three allowances closest to their limit without scrolling.
• The connections catalog opens with a Start here group, and Data collected sits behind a disclosure that works by keyboard.
• The dashboard does not link to Your 2026 so far when the year has no data.
• New Sentry issues first seen within the chosen window after a production deploy are linked to that deploy on the timeline and in Event details.
• An alert arrives by email and by a Slack or Discord channel on the hosted app.
• A README badge can be copied from the checklist in one step, after the user sees what becomes public.
• A weekly stack email arrives on the hosted app.
• The admin API key decision is recorded on #159 and #160, and if approved both adapters are merged.
• Every bug in section D is closed.
• Playwright e2e coverage added or updated for every changed screen, with an axe scan and a keyboard pass.

Files and areas

• Landing: src/components/sections/hero.tsx, src/components/github-button.tsx, src/lib/site.ts
• Workspace entry and empty states: src/app/app/page.tsx, src/app/w/[workspace]/page.tsx, src/app/w/[workspace]/timeline/page.tsx, src/lib/timeline/empty-state.ts
• Connections: src/app/w/[workspace]/connections/page.tsx, src/app/w/[workspace]/connections/new/[provider]/page.tsx, src/components/connections/
• Alerts: src/components/alerts/add-suggested-alerts.tsx, src/components/alerts/alert-settings.tsx, src/app/w/[workspace]/alerts/settings/page.tsx, src/lib/alerts/
• Dashboard: src/app/w/[workspace]/dashboard/page.tsx, src/lib/dashboard/headline.ts, src/lib/dashboard/projection.ts
• Ingest, adapters, jobs: src/lib/jobs/ingest.ts, src/lib/jobs/sync-connection.ts, src/lib/adapters/*/index.ts
• Demo: src/lib/demo/workspace.ts, src/lib/demo/history.ts, src/lib/adapters/simulated/index.ts
• Settings and sharing: src/app/w/[workspace]/settings/assistant-setup.tsx, src/components/public-metrics/share-dialog.tsx, src/lib/workspaces/handles.ts

Non-goals: billing and plans (#73, #74, #75), the leaderboard (#154), team management (#105).

Verification

Per sub-issue. For this parent: the acceptance criteria checked on the hosted app with one real provider, plus the walkthrough repeated with a fresh invited account, with screenshots.

Branch: per sub-issue.

Model: anthropic/claude-opus-5-5 | Reasoning effort: unknown