# launch-quickly

> An opinionated SaaS starter whose conventions are executable: every convention exists as a generator that writes it, a check that fails when it is broken, and a skill that explains it.

## Documentation

- [What this is](/docs/index.md): An opinionated SaaS starter whose conventions are executable, not documented.
- [Review agents](/docs/agents.md): Three specialist reviewers that read a running app rather than its source — and what they found the first time they were pointed at ours.
- [Driving the factory](/docs/ai-workflow.md): How to get good work out of an agent on this codebase — written from seven agent-built products and the bugs every automated gate approved.
- [AI](/docs/ai.md): The provider seam, streaming, and a usage budget wired into billing.
- [Audit log](/docs/audit.md): Who did what, recorded by the framework and immutable by the database.
- [CLI reference](/docs/cli.md): Every command and flag, generated from the definitions themselves — so a flag cannot exist without appearing here.
- [Components](/docs/components.md): Thirty-one shadcn primitives, thirteen application components with thirty exports between them, thirteen marketing blocks, and the rule about which layer you reach for.
- [The conventions](/docs/conventions.md): What the rules are, and which rung of the enforcement ladder holds each one up.
- [Deployment](/docs/deployment.md): Vercel + Neon, in the order that actually works.
- [The design system](/docs/design-system.md): Three component layers, five structural themes, and one place that formats a date — so two products built on this template do not look like the same product.
- [For agents](/docs/for-agents.md): Every page here as raw Markdown, and how to point an agent at this codebase.
- [Generators](/docs/generators.md): Why you should almost never write a feature by hand.
- [Install](/docs/install.md): From a license key to a running application.
- [Jobs & revalidation](/docs/jobs-and-caching.md): Background work with cron and idempotent steps; page freshness through a typed registry.
- [lq check](/docs/lq-check.md): The only validation verb, and what each of its six checks is for.
- [The marketing surface](/docs/marketing-and-seo.md): One config file holds every word on the public site, thirteen blocks render it, two layouts arrange it, and the SEO helpers keep the structured data agreeing with the page.
- [MCP server](/docs/mcp.md): Your project's conventions, its seventeen skills and its checks, exposed to any editor that speaks MCP — read from the project, never bundled.
- [Observability](/docs/observability.md): Structured logs, request ids on every response, a reporting seam, and a health endpoint.
- [Scaling](/docs/scaling.md): What this stack will hit first, roughly when, and what to do about it — with the honest note about which parts are measured and which are reasoned.
- [Themes](/docs/themes.md): Five presets that move typography, shape, density, elevation and border weight — plus the path for bringing your own brand, which is probably the one you want.
- [Troubleshooting](/docs/troubleshooting.md): Real symptoms from real builds — organised by what you actually see, not by which subsystem is at fault. Every entry here cost someone time.
- [Upgrades](/docs/upgrades.md): How improvements reach a project that was generated months ago.
- [The workflow](/docs/workflow.md): A brief becomes issues, an issue becomes a spec, a spec becomes a pull request — the pipeline that ships with the template, and the work that should never go through it.
- [Decisions](/docs/adr.md): Why this codebase is shaped the way it is — the alternatives that were rejected, and, where there was one, the specific bug that settled the argument.
- [Patterns](/docs/patterns.md): Sixteen guides that ship inside every project, published here as pages. Your agent loads them on demand; this is the same text.
- [0001 — Conventions are executable](/docs/adr/0001-conventions-are-executable.md): A convention that only exists in a document is a convention you have not shipped. The ladder from generator to prose, and why prose is last.
- [0002 — Tenancy is enforced by Postgres](/docs/adr/0002-row-level-security.md): A query that forgets its tenant filter returns zero rows, because the database refuses. Not because a reviewer noticed.
- [0003 — TenantContext is branded](/docs/adr/0003-branded-tenant-context.md): No code outside one module can produce one, not even by writing an object literal with the right shape. And why middleware is not a security boundary.
- [0004 — The action builder is a type-state machine](/docs/adr/0004-type-state-action-builder.md): .mutation() does not exist until you have validated and chosen an auth posture. Not a lint rule — the code does not compile.
- [0005 — The template is vendored, not a dependency](/docs/adr/0005-vendored-not-published.md): Three kinds of code, three upgrade policies. The interesting one is the middle: ours to improve, yours to edit.
- [0006 — Managed files carry a marker, the hash lives elsewhere](/docs/adr/0006-managed-files-by-marker.md): A comment survives every edit that matters. A version inside the file goes stale and becomes a confident lie.
- [0007 — Codemods emit text edits, never a reprinted AST](/docs/adr/0007-codemods-as-text-edits.md): A two-line change buried in a nine-hundred-line reformat is a diff nobody can review, and a diff nobody can review is a diff nobody trusts.
- [0008 — There is one validation verb](/docs/adr/0008-one-validation-verb.md): Five commands means an agent remembers zero. lq check is what the hook runs, what the rules mandate, and what CI runs — the same code path in all three.
- [0009 — A calendar date is a date, not a timestamp](/docs/adr/0009-calendar-dates.md): The best-evidenced decision in the codebase. Two shipped bugs, and both lq check and the generated tests passed throughout.
- [0010 — Offset pagination, deliberately](/docs/adr/0010-offset-pagination.md): Cursor pagination is better at scale and worse at everything a starting product needs.
- [0011 — State management has a single answer](/docs/adr/0011-single-answer-state.md): Server state is RSC and server actions. URL state is nuqs. Local state is useState. Everything else is a lint error.
- [0012 — Integrations are seams, and stay unconfigured until they earn it](/docs/adr/0012-seams-not-vendors.md): Unconfigured is a supported state that fails at the call site with the variable's name — not at build time, and not with an opaque 401.
- [0013 — The stack choices, including the four nobody wrote down](/docs/adr/0013-stack-choices.md): Drizzle, Better Auth, Server Actions and Inngest. What the code proves about each, and where the honest answer is that the reasoning was never recorded.
- [AI patterns](/docs/patterns/ai-patterns.md): How AI features work here — the provider seam, metered entry points, streaming route vs one-shot action, and the usage budget wired into billing. Use when adding any model call, or when AI spend and entitlements are involved.
- [Audit logging](/docs/patterns/audit-logging.md): How the audit trail works — the .audit() stage on the action client, what gets recorded and what must not, immutability via RLS, and the lint rule on destructive actions. Use when adding mutations, when the require-audit-on-destructive rule fires, or when compliance questions come up.
- [Authorization](/docs/patterns/authorization.md): Who may do what — role permissions with can(), and resource-level rules (owner, assignee) in a slice's policy.ts. Use when a rule depends on the ROW and not just the role, or when tempted to compare ctx.userId in a component.
- [Background jobs](/docs/patterns/background-jobs.md): Defining, enqueueing and scheduling jobs — defineJob, the typed registry, cron triggers, step.run idempotency, and where withSystem is sanctioned. Use when work should not happen in the request, when adding a cron, or when a job retries strangely.
- [Caching and revalidation](/docs/patterns/caching-and-revalidation.md): How mutations refresh pages — the typed revalidate registry, why importing next/cache is a lint error, and where the generator registers new features. Use when a list is stale after a mutation, or when the next/cache restriction fires.
- [Data access and tenancy](/docs/patterns/data-layer-and-tenancy.md): How to read and write data in this project — withTenant, withPublic, withSystem, TenantContext, and the row-level security that backs them. Use when adding a query or mutation, when a query returns no rows unexpectedly, or when deciding where an authorization check belongs.
- [Data tables and pagination](/docs/patterns/data-tables-and-pagination.md): The list convention — Paginated queries, URL-state filters and pagination with nuqs, tables, empty states. Use when building or changing any list of records, or when pagination/filtering behaves oddly.
- [Designing app UI](/docs/patterns/designing-app-ui.md): Which application component to use for which job, how to lay out a page, and the hierarchy, density and copy rules that make a screen look finished. Use when building or reviewing any signed-in screen.
- [Fixing lq check](/docs/patterns/fixing-lq-check.md): What each lq check failure means and the recipe that fixes it — every custom lint rule, the boundaries graph, the structure checks, and the type errors that encode conventions. Use whenever lq check fails and the fix is not immediately obvious.
- [Forms](/docs/patterns/forms.md): How to build a form in this project — useActionForm, the Field primitive, where the schema comes from, and how server-side field errors get back to the right input. Use when adding or changing any form, or when RHF's error types will not line up.
- [Marketing and SEO](/docs/patterns/marketing-and-seo.md): The public site — marketing.ts as the single copy declaration, which block to use where, the two landing layouts, and the SEO helpers (page metadata, canonicals, JSON-LD, sitemap). Use when editing the landing page, adding a public page, or changing anything a crawler sees.
- [Observability](/docs/patterns/observability.md): Logging, request ids, error reporting and the health endpoint — the structured logger, why console is a lint error, requestLog/reportError, and the job-run logger. Use when adding log lines, when no-console fires, or when wiring a reporter like Sentry.
- [The software factory](/docs/patterns/software-factory.md): The pipeline from a brief to a merged pull request — the label states, which command runs at each one, and when to stay in the driver's seat instead. Use when planning work or wondering how a ticket should move.
- [Testing](/docs/patterns/testing.md): How to test in this project — the unit/integration/e2e split, the tenant-isolation test every feature needs, the signed-in Playwright fixture, and how to tell a real pass from a test that never checked anything. Use when adding tests or when a test passes and you are not sure it should have.
- [UI and navigation](/docs/patterns/ui-and-navigation.md): How the signed-in shell works — nav.ts as the single navigation declaration, permission-gated sidebar, breadcrumbs, theme presets, and how a new page becomes reachable. Use when adding a route, changing navigation, or theming.
- [Writing product copy](/docs/patterns/writing-product-copy.md): Voice, microcopy, empty states, error messages and enum labels — the words in the product, as opposed to the words on the landing page. Use when writing any user-visible string.
- [Server actions](/docs/patterns/writing-server-actions.md): How to write a mutation in this project — the typed action client, its staged builder, ActionResult, and the AppError taxonomy. Use when adding or changing anything in an actions.ts file, or when the compiler says .mutation() does not exist.