feat: first-run install prompt on bare failproofai

[NiveditJain]

Summary

• PostHog (last 90d) confirms 470 npm-installers → only 48 ran failproofai policies --install (~10% conversion, 89.7% drop-off). Median time-to-install when it does happen is ~4 min, so the funnel fails on awareness, not friction.
• Adds a first-run prompt on bare failproofai (no-args) invocations: when no hooks are installed across any detected CLI, offer to run the existing interactive policy-selection inline. Covers all 7 supported CLIs (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini).
• Non-TTY (CI, piped) prints a short hint and falls through to the dashboard. Opt-out via FAILPROOFAI_NO_FIRST_RUN=1.
• Postinstall now prints a "Next steps" block for the brand-new-user case (!configured && !registered) that the existing printHooksWarning didn't cover.
• New PostHog events for measuring uplift: first_run_nudge_{shown,accepted,declined,skipped_noninteractive}. Funnel to query post-merge: package_installed → first_run_nudge_shown → first_run_nudge_accepted → hooks_installed.

Files

• New: src/hooks/first-run-nudge.ts, __tests__/hooks/first-run-nudge.test.ts, __tests__/scripts/postinstall.test.ts
• Modified: bin/failproofai.mjs (args.length===0 guard before launch("start")), scripts/postinstall.mjs (Next steps block), README.md + docs/introduction.mdx quickstart snippets, docs/cli/environment-variables.mdx (new First-run prompt section), CHANGELOG.md

Test plan

• bun run test:run — 1644/1644 pass (16 new)
• bunx tsc --noEmit clean
• bun run lint clean (1 pre-existing unrelated warning)
• Local TTY smoke: node bin/failproofai.mjs → prompt appears; y runs installHooks and exits 0; n falls through to dashboard
• Non-TTY smoke: echo "" | node bin/failproofai.mjs → 2-line hint then dashboard
• Opt-out smoke: FAILPROOFAI_NO_FIRST_RUN=1 node bin/failproofai.mjs → straight to dashboard, no prompt, no telemetry
• Already-installed smoke: after failproofai policies --install, re-run failproofai → no prompt
• Docker clean-install per repo testing protocol
• Post-merge: confirm package_installed → first_run_nudge_shown → first_run_nudge_accepted → hooks_installed conversion materially exceeds the current 10% baseline

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@NiveditJain has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 2 minutes and 41 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6a12597c-5ac5-4a31-98b2-7f380598cc79

📥 Commits

Reviewing files that changed from the base of the PR and between eb22935 and 25fdda1.

📒 Files selected for processing (9)

• CHANGELOG.md
• README.md
• __tests__/hooks/first-run-nudge.test.ts
• __tests__/scripts/postinstall.test.ts
• bin/failproofai.mjs
• docs/cli/environment-variables.mdx
• docs/introduction.mdx
• scripts/postinstall.mjs
• src/hooks/first-run-nudge.ts

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}