ship-create 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ship-create",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Scaffold a new project the SHIP Method way — Structure, Human Flow, Instruction, Publish. No git clone, no API key, just one command.",
   "type": "module",
   "license": "MIT",

package/templates/.claude/commands/ship.md

@@ -0,0 +1,46 @@
+---
+description: Drive this project through the SHIP Method — Structure, Human Flow, Instruction, Publish.
+argument-hint: "[status | structure | human-flow | instruction | publish]"
+---
+
+You are driving this project through **The SHIP Method** via the `/ship` shortcut. FIRST invoke the `ship-method` skill — it owns the gate definitions, the "never invent business facts" rule, and the Theme & First Screen procedure. This command is a thin orchestrator on top of it; do not duplicate or contradict the skill.
+
+Argument passed: "$ARGUMENTS"
+
+## Step 1 — Locate the docs
+
+Determine where this project's SHIP docs live and use whichever set exists:
+- `ship-create`-generated project: `docs/PROJECT.md`, `docs/HUMAN_FLOW.md`, `docs/AI_BUILD_SPEC.md`.
+- The SHIP Method OS repo itself: `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, `03-INSTRUCTION/AI_BUILD_SPEC.md`.
+
+## Step 2 — Detect the current phase
+
+Walk the gates in order and find the FIRST one not yet satisfied. A gate is unsatisfied if its file is missing OR its core sections still contain `[bracket placeholders]` or unedited template / "Worked Mini-Example" content instead of this project's real content.
+
+1. **S — Structure** — `PROJECT.md` core sections filled: Vision, Problem Statement, Target Audience, MVP Scope.
+2. **H — Human Flow** — `HUMAN_FLOW.md` core sections filled: Core Screens, Happy Path, and at least one error/empty state.
+3. **I — Instruction** — `AI_BUILD_SPEC.md` exists with functional requirements, data model, and API contract.
+4. **P — Publish** — Theme & First Screen done, feature code built from the spec, and the pre-launch checklist walked.
+
+## Step 3 — Handle the argument
+
+- `status` → report each gate as pass/fail with one line on what's missing, then STOP (do not drive).
+- `structure`/`s`, `human-flow`/`h`, `instruction`/`i`, `publish`/`p` → jump to that phase regardless of detection (used to revisit an earlier phase).
+- empty or anything else → resume at the first incomplete gate from Step 2.
+
+## Step 4 — Drive the phase
+
+Announce the phase and what is missing, e.g. "You're at **S — Structure**. `PROJECT.md` has N unfilled sections — let's fill them."
+
+Then, **one question at a time** (pull questions from the relevant section headers):
+- Ask → wait for the answer → **draft the real content into the doc** for that section.
+- Never invent business facts (market size, pricing, metrics, quotes). If the user doesn't know, write a clearly-labeled placeholder like `[TBD: ...]` and move on.
+- When the phase's required sections are filled, summarize what was written, confirm with the user, then advance to the next phase by re-running this flow.
+
+For **P — Publish**, follow the `ship-method` skill's Theme & First Screen step (use `theme-guide.md`): derive 2-3 themes from `PROJECT.md`, let the user pick one, apply it, build the real homepage from `HUMAN_FLOW.md`, then build the remaining feature code from the spec, then walk `QA_CHECKLIST.md` / `LAUNCH_CHECKLIST.md`.
+
+## Rules
+
+- Ask exactly one question per message.
+- Do not generate feature/business-logic code until Gates 1-3 pass (scaffolding/config is fine anytime).
+- `/ship` keeps no saved state — it re-detects the phase every run, so it always resumes correctly.

package/templates/.claude/skills/ship-method/SKILL.md

@@ -20,6 +20,7 @@ The single most common reason AI-built products end up broken, scope-creeped, or
 - The user asks you to generate code for a feature that doesn't have a filled spec yet
 - The user asks "is this ready to build?" or "is this ready to ship?"
 - You're about to scaffold, design a schema, or write business logic and no `PROJECT.md` / `HUMAN_FLOW.md` exists yet for it
+- The user runs the `/ship` shortcut — drive them through the gates below one phase at a time, drafting their answers into the docs
 
 ## The Checklist
 
@@ -28,7 +29,8 @@ Work through these gates in order. Do not let scope, urgency, or the user saying
 - [ ] **Gate 1 — Structure exists.** Find or create `PROJECT.md` (template: `01-STRUCTURE/PROJECT.md` in this repo, or `docs/PROJECT.md` if this is a `ship-create`-generated project). Vision, Problem Statement, Target Audience, and MVP Scope must be filled — not placeholder brackets.
 - [ ] **Gate 2 — Human Flow exists.** Find or create `HUMAN_FLOW.md`. Every core screen needs a happy path and at least one error/empty state defined before it gets built.
 - [ ] **Gate 3 — Instruction exists.** Functional requirements, data model, and API contract are written somewhere concrete (`AI_BUILD_SPEC.md` / `docs/PROJECT.md`'s feature section) before you generate feature code.
-- [ ] **Gate 4 — Publish readiness.** Before telling the user something is "done," check it against the relevant checklist (`QA_CHECKLIST.md`, `LAUNCH_CHECKLIST.md`) rather than declaring success from a clean build alone.
+- [ ] **Gate 4 — Theme & First Screen.** Once Gates 1-3 pass and before final polish/ship: derive 2-3 business-appropriate themes from `PROJECT.md`, let the user pick one, apply it (`app/globals.css`, `app/layout.tsx`), and record it in the design system; then read `HUMAN_FLOW.md` and replace the starter's generic `app/page.tsx` ("Pick your area") with the real entry point. See `theme-guide.md` in this skill folder.
+- [ ] **Gate 5 — Publish readiness.** Before telling the user something is "done," check it against the relevant checklist (`QA_CHECKLIST.md`, `LAUNCH_CHECKLIST.md`) rather than declaring success from a clean build alone.
 
 ## How to Apply This
 
@@ -37,6 +39,26 @@ Work through these gates in order. Do not let scope, urgency, or the user saying
 3. **If all gates are filled:** proceed normally — generate code straight from the spec, and flag if a code request contradicts what's already written in `PROJECT.md` or `HUMAN_FLOW.md` rather than silently overriding it.
 4. **When asked "is this ready to build/ship?":** walk the checklist above explicitly and report which gates pass/fail, rather than giving a vague yes/no.
 
+## Theme & First Screen (Gate 4)
+
+Run this once Gates 1-3 pass, before final polish or shipping. The agent already
+knows the business from `PROJECT.md`, so it can theme and build the front door
+accurately.
+
+1. **Derive & choose a theme.** From `PROJECT.md`, produce 2-3 candidate themes
+   (palette as HSL token values + a font pairing). Present them and let the user
+   pick — never pick silently, never require brand assets the user didn't give.
+2. **Apply it.** Write the chosen tokens into `app/globals.css` (`:root` and
+   `.dark`), set fonts in `app/layout.tsx`, and record the choice in
+   `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md` (or `docs/DESIGN_SYSTEM.md`).
+3. **Build the first screen.** Read `HUMAN_FLOW.md`, decide the real entry point
+   for this business, and replace the starter's `app/page.tsx` ("Pick your
+   area") with it — landing/sale for marketing-led products, app home/dashboard
+   redirect for tools. Adjust each area's main page to match.
+
+Full procedure and the business-type → palette/font table: `theme-guide.md` in
+this skill folder. (In this OS repo the app lives under `starter-kit/`.)
+
 ## Reference Files (when present in this repo)
 
 | Need | File |
@@ -47,6 +69,7 @@ Work through these gates in order. Do not let scope, urgency, or the user saying
 | Pre-launch checks | `04-PUBLISH/QA_CHECKLIST.md`, `04-PUBLISH/LAUNCH_CHECKLIST.md` |
 | Product-type starter pack | `06-TEMPLATES/<TYPE>_TEMPLATE.md` |
 | Design consistency | `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md` |
+| Business-type → palette/font theme guide | `theme-guide.md` (this skill folder) |
 | Stack decisions | `13-TECH-STACK/STACK_DECISION_MATRIX.md` |
 
 If this is a project generated by `ship-create`, the same files exist under `docs/` instead of the numbered folders above.

package/templates/.claude/skills/ship-method/theme-guide.md

@@ -0,0 +1,72 @@
+# Theme & First Screen — Reference Guide
+
+Used by the SHIP Method's **Theme & First Screen** step (first step of the
+PUBLISH phase). It tells you how to turn the business described in `PROJECT.md`
+into (a) 2-3 theme candidates the user can choose from, and (b) a real homepage.
+
+## Where things live
+
+In a `ship-create`-generated project the Next.js app is at the repo root:
+- `app/globals.css` — theme tokens (HSL triplets) under `:root` and `.dark`
+- `app/layout.tsx` — fonts via `next/font/google`, mapped to `--font-*` variables
+- `app/page.tsx` — the root page (ships as a generic "Pick your area" screen)
+
+In **this OS repo**, the same app lives under `starter-kit/` (e.g.
+`starter-kit/app/globals.css`). Adjust paths accordingly.
+
+Record the chosen theme in the design system doc:
+`12-DESIGN-SYSTEM/DESIGN_SYSTEM.md` (or `docs/DESIGN_SYSTEM.md` in generated
+projects).
+
+## Step 1 — Derive 2-3 theme candidates
+
+Read `PROJECT.md` (vision, business type, target audience, any stated brand
+colors). Map the business to a palette direction and a font pairing using the
+table below as a starting point — then tailor, don't copy blindly.
+
+| Business / mood | Palette direction | Font pairing (display / sans) |
+|---|---|---|
+| Finance, B2B, trust | Cool navy/slate base, restrained single accent | Serif or grotesk display / neutral sans |
+| Legal, premium, luxury | Deep neutral (ink/charcoal), gold or burgundy accent | Classic serif / humanist sans |
+| Kids, play, consumer fun | Bright, high-saturation, multiple accents | Rounded geometric sans / rounded sans |
+| Health, wellness, calm | Soft greens/teals, low saturation | Humanist serif / soft sans |
+| Tech, SaaS, developer | Dark base, one electric accent | Geometric sans / mono accents |
+| Food, hospitality, warm | Warm earth tones, appetizing accent | Editorial serif / friendly sans |
+| Creative, agency, bold | High-contrast, expressive accent | Display serif or bold grotesk / clean sans |
+
+Each candidate MUST specify, as HSL triplets, values for every token in
+`globals.css`: `--background --foreground --card --card-foreground --primary
+--primary-foreground --secondary --secondary-foreground --accent
+--accent-foreground --muted --muted-foreground --destructive
+--destructive-foreground --success --success-foreground --border --input --ring`
+plus a `--radius`, and a font pairing for `--font-display`, `--font-sans`,
+`--font-mono`.
+
+Present the candidates to the user (a one-line mood + the key colors each).
+Let the user pick one. Do NOT pick silently. Do NOT require brand assets — use
+them only if `PROJECT.md` provides them.
+
+## Step 2 — Apply the chosen theme
+
+1. In `app/globals.css`, set the token values under BOTH `:root` and `.dark`
+   (this kit keeps them identical). Keep the HSL-triplet format (e.g.
+   `--primary: 14 92% 58%;`) so `hsl(var(--x))` keeps working.
+2. In `app/layout.tsx`, swap the `next/font/google` imports to the chosen
+   fonts, keeping the variable names `--font-display`, `--font-sans`,
+   `--font-mono`. The starter uses `Fraunces` (display), `Work_Sans` (sans),
+   `JetBrains_Mono` (mono) as the reference pattern.
+3. Record the final palette + fonts in the design system doc as the source of
+   truth for later UI work.
+
+## Step 3 — Build the real first screen
+
+Read `HUMAN_FLOW.md` and decide the true entry point for THIS business:
+- Marketing-led (course, membership, leadgen) → root `app/page.tsx` becomes the
+  landing/sale page.
+- Tool/dashboard/internal → root becomes the app home, or redirects to the
+  primary dashboard route.
+
+Replace the generic "Pick your area" content in `app/page.tsx` with real content
+drawn from the spec (no lorem). Adjust the main page of each area's route to
+match. Then remind the user to update `FEATURE_MATRIX.md` and `QA_CHECKLIST.md`
+if scope changed.

package/templates/.cursorrules

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/.windsurfrules

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/AGENTS.md

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/CLAUDE.md

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/starter-kit/.env.example

@@ -0,0 +1,32 @@
+# Pick exactly one provider. This is a setup-time choice, not runtime-switchable.
+DB_PROVIDER=supabase # supabase | neon | cloudflare-d1 | postgres
+
+# --- supabase | postgres | neon (Postgres-family — all use DATABASE_URL) ---
+# Supabase: Project Settings -> Database -> Connection string (use the "Transaction pooler" URI for serverless)
+# Neon: Project Dashboard -> Connection Details -> select "Pooled connection"
+# Plain Postgres: your host's connection string, e.g. postgres://user:pass@host:5432/dbname
+DATABASE_URL=
+
+# --- cloudflare-d1 only ---
+# D1 has no connection string at runtime — the binding comes from wrangler.toml
+# and the Cloudflare Workers runtime, not an env var. The vars below are only
+# used by `drizzle-kit` migration commands run from your local machine.
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_D1_DATABASE_ID=
+CLOUDFLARE_API_TOKEN=
+
+# IMPORTANT: DB_PROVIDER=cloudflare-d1 requires deploying this app to
+# Cloudflare Workers/Pages via @opennextjs/cloudflare. It will NOT work on
+# Vercel. See 13-TECH-STACK/DB_PROVIDER_GUIDE.md before picking this option.
+
+# --- Auth.js (required regardless of DB_PROVIDER) ---
+AUTH_SECRET=
+# Add at least one provider's keys here once chosen, e.g.:
+# AUTH_GITHUB_ID=
+# AUTH_GITHUB_SECRET=
+
+# --- Storage (optional — only needed once you wire up file uploads) ---
+STORAGE_PROVIDER=supabase # supabase | cloudflare-r2 | vercel-blob (only supabase is implemented)
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=
+SUPABASE_STORAGE_BUCKET=uploads

package/templates/starter-kit/README.md

@@ -1,15 +1,16 @@
 # SHIP Starter Kit
 
-This is the code foundation for **The SHIP Method OS** — a Next.js 14 (App
+This is the code foundation for **The SHIP Method OS** — a Next.js 16 (App
 Router) + TypeScript + Tailwind CSS starter that gives every downstream agent
 a consistent, working UI shell to build on top of.
 
-It is currently **mock-data only**. There is no backend wired up — no
-Supabase, no auth, no payments. Every list, table, and metric you see is
-sourced from `lib/mock-data.ts`. That's intentional: the goal of this layer
-is a correct, consistent shared foundation (design tokens, primitives,
-layout) that other agents can build real features on without re-deciding
-button styles or color values per screen.
+It is currently **mock-data only**. Backend code (`lib/db/`, `lib/auth.ts`,
+`lib/storage.ts`) is included but has no live database connection configured
+by default. Every list, table, and metric you see is sourced from
+`lib/mock-data.ts`. That's intentional: the goal of this layer is a correct,
+consistent shared foundation (design tokens, primitives, layout) that other
+agents can build real features on without re-deciding button styles or color
+values per screen.
 
 ## Running it
 
@@ -51,14 +52,23 @@ shared primitives in `components/ui/` and the `cn()` helper in
 
 ## Next step: real data
 
-When it's time to move off mock data, replace the contents of
-`lib/mock-data.ts` (or the call sites that import from it) with real
-Supabase queries. Before doing that, read:
+This kit ships with a real, pluggable backend in `lib/db/`, `lib/auth.ts`,
+and `lib/storage.ts` — but it has no live database connection configured
+yet. To turn it on:
 
-- `../13-TECH-STACK/TECH_STACK.md` — the chosen stack and why.
-- `../03-INSTRUCTION/DATABASE_SPEC.md` — the database schema this app
-  should query against.
+1. Copy `.env.example` to `.env` and pick a `DB_PROVIDER`: `supabase`,
+   `neon`, `cloudflare-d1`, or `postgres`. Read
+   `../13-TECH-STACK/DB_PROVIDER_GUIDE.md` first if you're unsure which —
+   it covers free-tier limits and which providers can deploy where.
+2. Fill in that provider's connection details in `.env` (see the comments
+   in `.env.example`).
+3. Run `npx drizzle-kit generate` then apply the generated migration to
+   create the `user`/`account`/`session`/`verificationToken` tables.
+4. Add at least one Auth.js provider (OAuth or credentials) to the empty
+   `providers: []` array in `lib/auth.ts` — auth won't work until you do.
+5. Replace the contents of `lib/mock-data.ts` (or its call sites) with
+   real queries against `getDb()` from `lib/db`.
 
-Keep the typed interfaces (`MockUser`, `MockMemberContent`, `MockMetric`)
-as the contract — swap the data source, not the shape, unless the database
-spec requires otherwise.
+Before writing your own tables, also read
+`../03-INSTRUCTION/DATABASE_SPEC.md` for the schema-design template this
+app's data model should follow.

package/templates/starter-kit/drizzle.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "drizzle-kit"
+
+const provider = process.env.DB_PROVIDER
+
+const config =
+  provider === "cloudflare-d1"
+    ? defineConfig({
+        dialect: "sqlite",
+        schema: "./lib/db/schema.sqlite.ts",
+        out: "./drizzle/sqlite",
+        driver: "d1-http",
+        dbCredentials: {
+          accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "",
+          databaseId: process.env.CLOUDFLARE_D1_DATABASE_ID ?? "",
+          token: process.env.CLOUDFLARE_API_TOKEN ?? "",
+        },
+      })
+    : defineConfig({
+        dialect: "postgresql",
+        schema: "./lib/db/schema.pg.ts",
+        out: "./drizzle/postgres",
+        dbCredentials: {
+          url: process.env.DATABASE_URL ?? "",
+        },
+      })
+
+export default config

package/templates/starter-kit/lib/auth.ts

@@ -0,0 +1,30 @@
+import NextAuth from "next-auth"
+import { DrizzleAdapter } from "@auth/drizzle-adapter"
+import { getDb } from "./db"
+import * as pgSchema from "./db/schema.pg"
+import * as sqliteSchema from "./db/schema.sqlite"
+
+const provider = process.env.DB_PROVIDER
+const schema = (provider === "cloudflare-d1" ? sqliteSchema : pgSchema) as any
+
+// D1's binding only exists inside a Cloudflare request context, so the
+// adapter is built per-request via NextAuth's config-function form instead
+// of once at module scope (which is enough for every other provider).
+export const { handlers, signIn, signOut, auth } = NextAuth(async () => {
+  if (provider === "cloudflare-d1") {
+    const { getCloudflareContext } = await import("@opennextjs/cloudflare")
+    const { env } = getCloudflareContext()
+    return {
+      adapter: DrizzleAdapter(getDb((env as { DB: unknown }).DB), schema),
+      // No providers configured yet — add at least one (OAuth or
+      // credentials) before this auth setup is functional.
+      providers: [],
+      session: { strategy: "database" },
+    }
+  }
+  return {
+    adapter: DrizzleAdapter(getDb(), schema),
+    providers: [],
+    session: { strategy: "database" },
+  }
+})

package/templates/starter-kit/lib/db/index.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
+import { getDb } from "./index"
+
+describe("getDb", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it("throws when DB_PROVIDER is missing", () => {
+    vi.stubEnv("DB_PROVIDER", "")
+    expect(() => getDb()).toThrow(/DB_PROVIDER/)
+  })
+
+  it("throws when DB_PROVIDER is invalid", () => {
+    vi.stubEnv("DB_PROVIDER", "mongodb")
+    expect(() => getDb()).toThrow(/DB_PROVIDER/)
+  })
+
+  it("throws when DB_PROVIDER=postgres and DATABASE_URL is missing", () => {
+    vi.stubEnv("DB_PROVIDER", "postgres")
+    vi.stubEnv("DATABASE_URL", "")
+    expect(() => getDb()).toThrow(/DATABASE_URL/)
+  })
+
+  it("constructs a client for DB_PROVIDER=postgres given a connection string", () => {
+    vi.stubEnv("DB_PROVIDER", "postgres")
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@localhost:5432/db")
+    expect(() => getDb()).not.toThrow()
+  })
+
+  it("constructs a client for DB_PROVIDER=supabase given a connection string", () => {
+    vi.stubEnv("DB_PROVIDER", "supabase")
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@localhost:5432/db")
+    expect(() => getDb()).not.toThrow()
+  })
+
+  it("constructs a client for DB_PROVIDER=neon given a connection string", () => {
+    vi.stubEnv("DB_PROVIDER", "neon")
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@neon.example.com/db")
+    expect(() => getDb()).not.toThrow()
+  })
+
+  it("throws when DB_PROVIDER=cloudflare-d1 and no binding is passed", () => {
+    vi.stubEnv("DB_PROVIDER", "cloudflare-d1")
+    expect(() => getDb()).toThrow(/d1Binding/)
+  })
+
+  it("constructs a client for DB_PROVIDER=cloudflare-d1 given a binding", () => {
+    vi.stubEnv("DB_PROVIDER", "cloudflare-d1")
+    const fakeBinding = {} as never
+    expect(() => getDb(fakeBinding)).not.toThrow()
+  })
+})

package/templates/starter-kit/lib/db/index.ts

@@ -0,0 +1,64 @@
+import { drizzle as drizzlePg } from "drizzle-orm/postgres-js"
+import postgres from "postgres"
+import { drizzle as drizzleNeon } from "drizzle-orm/neon-http"
+import { neon } from "@neondatabase/serverless"
+import { drizzle as drizzleD1 } from "drizzle-orm/d1"
+import * as pgSchema from "./schema.pg"
+import * as sqliteSchema from "./schema.sqlite"
+
+export type DbProvider = "supabase" | "neon" | "cloudflare-d1" | "postgres"
+
+function getProvider(): DbProvider {
+  const provider = process.env.DB_PROVIDER
+  if (
+    provider !== "supabase" &&
+    provider !== "neon" &&
+    provider !== "cloudflare-d1" &&
+    provider !== "postgres"
+  ) {
+    throw new Error(
+      `Invalid or missing DB_PROVIDER env var: "${provider}". Must be one of: supabase, neon, cloudflare-d1, postgres. See .env.example.`
+    )
+  }
+  return provider
+}
+
+// D1's binding only exists inside a Cloudflare request context (there is no
+// connection string for it), so callers on that path must pass it in.
+export function getDb(d1Binding?: unknown) {
+  const provider = getProvider()
+
+  switch (provider) {
+    case "supabase":
+    case "postgres": {
+      const connectionString = process.env.DATABASE_URL
+      if (!connectionString) {
+        throw new Error(
+          `DATABASE_URL is required when DB_PROVIDER is "${provider}". See .env.example.`
+        )
+      }
+      const client = postgres(connectionString)
+      return drizzlePg(client, { schema: pgSchema })
+    }
+    case "neon": {
+      const connectionString = process.env.DATABASE_URL
+      if (!connectionString) {
+        throw new Error(
+          'DATABASE_URL is required when DB_PROVIDER is "neon". See .env.example.'
+        )
+      }
+      const client = neon(connectionString)
+      return drizzleNeon(client, { schema: pgSchema })
+    }
+    case "cloudflare-d1": {
+      if (!d1Binding) {
+        throw new Error(
+          'DB_PROVIDER is "cloudflare-d1" but no d1Binding was passed to getDb(). ' +
+            "D1's binding comes from the Cloudflare runtime context (e.g. getCloudflareContext().env.DB " +
+            "from @opennextjs/cloudflare) — it cannot be constructed from an env var alone."
+        )
+      }
+      return drizzleD1(d1Binding as never, { schema: sqliteSchema })
+    }
+  }
+}

package/templates/starter-kit/lib/db/schema.pg.ts

@@ -0,0 +1,58 @@
+import { integer, timestamp, pgTable, primaryKey, text } from "drizzle-orm/pg-core"
+import type { AdapterAccountType } from "next-auth/adapters"
+
+export const users = pgTable("user", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  name: text("name"),
+  email: text("email").unique(),
+  emailVerified: timestamp("emailVerified", { mode: "date" }),
+  image: text("image"),
+})
+
+export const accounts = pgTable(
+  "account",
+  {
+    userId: text("userId")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").$type<AdapterAccountType>().notNull(),
+    provider: text("provider").notNull(),
+    providerAccountId: text("providerAccountId").notNull(),
+    refresh_token: text("refresh_token"),
+    access_token: text("access_token"),
+    expires_at: integer("expires_at"),
+    token_type: text("token_type"),
+    scope: text("scope"),
+    id_token: text("id_token"),
+    session_state: text("session_state"),
+  },
+  (account) => ({
+    compoundKey: primaryKey({
+      columns: [account.provider, account.providerAccountId],
+    }),
+  })
+)
+
+export const sessions = pgTable("session", {
+  sessionToken: text("sessionToken").primaryKey(),
+  userId: text("userId")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  expires: timestamp("expires", { mode: "date" }).notNull(),
+})
+
+export const verificationTokens = pgTable(
+  "verificationToken",
+  {
+    identifier: text("identifier").notNull(),
+    token: text("token").notNull(),
+    expires: timestamp("expires", { mode: "date" }).notNull(),
+  },
+  (verificationToken) => ({
+    compositePk: primaryKey({
+      columns: [verificationToken.identifier, verificationToken.token],
+    }),
+  })
+)

package/templates/starter-kit/lib/db/schema.sqlite.ts

@@ -0,0 +1,58 @@
+import { sqliteTable, text, integer, primaryKey } from "drizzle-orm/sqlite-core"
+import type { AdapterAccountType } from "next-auth/adapters"
+
+export const users = sqliteTable("user", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  name: text("name"),
+  email: text("email").unique(),
+  emailVerified: integer("emailVerified", { mode: "timestamp_ms" }),
+  image: text("image"),
+})
+
+export const accounts = sqliteTable(
+  "account",
+  {
+    userId: text("userId")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").$type<AdapterAccountType>().notNull(),
+    provider: text("provider").notNull(),
+    providerAccountId: text("providerAccountId").notNull(),
+    refresh_token: text("refresh_token"),
+    access_token: text("access_token"),
+    expires_at: integer("expires_at"),
+    token_type: text("token_type"),
+    scope: text("scope"),
+    id_token: text("id_token"),
+    session_state: text("session_state"),
+  },
+  (account) => ({
+    compoundKey: primaryKey({
+      columns: [account.provider, account.providerAccountId],
+    }),
+  })
+)
+
+export const sessions = sqliteTable("session", {
+  sessionToken: text("sessionToken").primaryKey(),
+  userId: text("userId")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  expires: integer("expires", { mode: "timestamp_ms" }).notNull(),
+})
+
+export const verificationTokens = sqliteTable(
+  "verificationToken",
+  {
+    identifier: text("identifier").notNull(),
+    token: text("token").notNull(),
+    expires: integer("expires", { mode: "timestamp_ms" }).notNull(),
+  },
+  (verificationToken) => ({
+    compositePk: primaryKey({
+      columns: [verificationToken.identifier, verificationToken.token],
+    }),
+  })
+)

package/templates/starter-kit/lib/storage.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect, afterEach, vi } from "vitest"
+import { createStorageClient } from "./storage"
+
+describe("createStorageClient", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it("throws when STORAGE_PROVIDER=supabase and SUPABASE_URL is missing", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "supabase")
+    vi.stubEnv("SUPABASE_URL", "")
+    vi.stubEnv("SUPABASE_SERVICE_ROLE_KEY", "")
+    expect(() => createStorageClient()).toThrow(/SUPABASE_URL/)
+  })
+
+  it("constructs a client when STORAGE_PROVIDER=supabase with credentials set", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "supabase")
+    vi.stubEnv("SUPABASE_URL", "https://example.supabase.co")
+    vi.stubEnv("SUPABASE_SERVICE_ROLE_KEY", "fake-key")
+    expect(() => createStorageClient()).not.toThrow()
+  })
+
+  it("throws a clear not-implemented error for cloudflare-r2", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "cloudflare-r2")
+    expect(() => createStorageClient()).toThrow(/not implemented/)
+  })
+
+  it("throws a clear not-implemented error for vercel-blob", () => {
+    vi.stubEnv("STORAGE_PROVIDER", "vercel-blob")
+    expect(() => createStorageClient()).toThrow(/not implemented/)
+  })
+})

package/templates/starter-kit/lib/storage.ts

@@ -0,0 +1,62 @@
+import { createClient } from "@supabase/supabase-js"
+
+export interface StorageClient {
+  upload(
+    path: string,
+    file: Blob | Buffer,
+    contentType: string
+  ): Promise<{ path: string; publicUrl: string }>
+  getPublicUrl(path: string): string
+  remove(path: string): Promise<void>
+}
+
+class SupabaseStorageClient implements StorageClient {
+  private client: ReturnType<typeof createClient>
+  private bucket: string
+
+  constructor(supabaseUrl: string, supabaseKey: string, bucket: string) {
+    this.client = createClient(supabaseUrl, supabaseKey)
+    this.bucket = bucket
+  }
+
+  async upload(path: string, file: Blob | Buffer, contentType: string) {
+    const { data, error } = await this.client.storage
+      .from(this.bucket)
+      .upload(path, file, { contentType, upsert: true })
+    if (error) throw error
+    return { path: data.path, publicUrl: this.getPublicUrl(data.path) }
+  }
+
+  getPublicUrl(path: string): string {
+    const { data } = this.client.storage.from(this.bucket).getPublicUrl(path)
+    return data.publicUrl
+  }
+
+  async remove(path: string): Promise<void> {
+    const { error } = await this.client.storage.from(this.bucket).remove([path])
+    if (error) throw error
+  }
+}
+
+export type StorageProvider = "supabase" | "cloudflare-r2" | "vercel-blob"
+
+export function createStorageClient(): StorageClient {
+  const storageProvider = (process.env.STORAGE_PROVIDER || "supabase") as StorageProvider
+
+  if (storageProvider === "supabase") {
+    const url = process.env.SUPABASE_URL
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY
+    const bucket = process.env.SUPABASE_STORAGE_BUCKET || "uploads"
+    if (!url || !key) {
+      throw new Error(
+        "SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are required when STORAGE_PROVIDER=supabase. See .env.example."
+      )
+    }
+    return new SupabaseStorageClient(url, key, bucket)
+  }
+
+  throw new Error(
+    `STORAGE_PROVIDER="${storageProvider}" is not implemented yet — only "supabase" is wired up. ` +
+      "See 13-TECH-STACK/DB_PROVIDER_GUIDE.md for how to add Cloudflare R2 or Vercel Blob."
+  )
+}

package/templates/starter-kit/package.json

@@ -6,18 +6,25 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "vitest run"
   },
   "dependencies": {
+    "@auth/drizzle-adapter": "^1.7.4",
+    "@neondatabase/serverless": "^0.10.3",
     "@radix-ui/react-avatar": "^1.1.0",
     "@radix-ui/react-dialog": "^1.1.1",
     "@radix-ui/react-dropdown-menu": "^2.1.1",
     "@radix-ui/react-slot": "^1.1.0",
     "@radix-ui/react-tabs": "^1.1.0",
+    "@supabase/supabase-js": "^2.46.1",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.1",
+    "drizzle-orm": "^0.36.0",
     "lucide-react": "^0.439.0",
     "next": "^16.2.9",
+    "next-auth": "5.0.0-beta.25",
+    "postgres": "^3.4.5",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "tailwind-merge": "^2.5.2"
@@ -27,10 +34,12 @@
     "@types/react": "^18.3.4",
     "@types/react-dom": "^18.3.0",
     "autoprefixer": "^10.4.20",
+    "drizzle-kit": "^0.28.1",
     "eslint": "^8.57.0",
     "eslint-config-next": "14.2.5",
     "postcss": "^8.4.41",
     "tailwindcss": "^3.4.10",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.5"
   }
 }

package/templates/starter-kit/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+})