Boring Docs

Convention over configuration. If it is not in this map, it does not exist yet.

BoringPush is an agent-first shipping kit for Next.js with one-switch database (SQLite / MongoDB / Supabase) and one-switch billing (Dodo / Stripe / LemonSqueezy), gated by a single paywall verb: requirePaidUser().

Agent-first means two things here: coding agents can build your app without breaking it (the .agents/ rules, read-only production handles, additive migrations), and AI assistants can use your app on behalf of your users (the built-in MCP server; see AI assistants (MCP)).

Read in this order

1. 01-get-started.md — clone, env, dev server, first login (SQLite, zero setup).
2. 02-project-structure.md — where everything lives (providers/, libs/, models/, app/api/, components/, config/, data/).
3. 03-config-env.md — .env.example keys: app, auth, DB_PROVIDER, BILLING_PROVIDER, analytics, GitHub delivery.
4. 04-auth.md — Google OAuth, magic links, dev login, JWT sessions, stale-session guard, admin allowlist.
5. 05-database.md — tri-DB parity, registry delegation, verbs, migrations, backups.
6. 06-payments.md — tri-rail billing, checkout, portal, cancel, webhooks, idempotency.
7. 07-paywall.md — hasAccess / planType, PaywallGate, vault/pro guards, claim-repo.
8. 08-emails.md — Resend send + NextAuth magic link authentication.
9. 09-seo-analytics-blog.md — SEO tags, analytics beacon, markdown blog.
10. 10-security.md — IDOR bindings, open-redirect allowlists, rate limits, headers, deps.
11. 11-deployment.md — Zero-CI git push, private Tailscale mesh, PM2, nginx, SSL, swap, ops.
12. 12-lock-checklist.md — freeze criteria: what must be green before v1.0-locked.
13. 13-build-features.md — the data-first engineering manual for humans & autonomous agents.
14. 14-ditch-vercel-vps-guide.md — Why ditch Vercel ($5/mo VPS), Cloudflare Tunnel + Tailscale zero-port setup, and battle-tested troubleshooting.
15. 15-agent-cage.md — SQLite is a file: OS-user + staging-copy cage so agents physically cannot delete prod data.
16. 16-background-jobs.md — zero-Redis workers: time-bucket folders, file locks, and adding your own job in five minutes.
17. 17-cli.md — CLI first: log a machine in, scoped tokens for agents, and a terminal command for every feature.
18. 18-ai-assistants-mcp.md — connect your app to Claude (and other MCP assistants): OAuth sign-in, read-only by default, how to add a tool.
19. 19-background-workers.md — event-driven background jobs: instant execution, retries with exponential backoff, delayed delivery, zero Redis.

Conventions (memorize these)

• Data first: schema on all backends → provider → registry → thin route → UI.
• Thin routes (≤ 40 lines): validate → auth → one provider call → JSON.
• Money rules: price comes from the product row, never the client; webhooks dedupe on providerPaymentRef.
• Shims are frozen: models/*.js and libs/mongoose.js re-export only.
• No new top-level folders without updating CONVENTIONS.md.

Next step

Open 01-get-started.md.