Pivot to household title-matching: 5-phase scaffold (Tonight pick, providers, history, pricing, LLM rerank)

.claude/skills/new-backend-feature/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: new-backend-feature
+description: Use when adding a new domain to the Pairflix backend (a new resource with its own routes, controller, service, model, and tests). Walks through the layering, registration, and migration steps so the feature lands on all the right seams.
+---
+
+# Adding a new backend feature
+
+Pairflix backend layers are: **routes → controllers → services → models**. Every new domain follows the same shape so the codebase stays grep-able. This skill assumes you have a domain name (e.g. `recommendation`) and know the endpoints you want to expose.
+
+## 1. Model + migration first
+
+If the feature owns persistent state:
+
+1. Create `backend/src/models/<PascalCase>.ts`. Use TypeScript enums for status fields. JSONB for flexible payloads. Indexes on every column you'll filter on.
+2. Register the model in `backend/src/models/index.ts` (both the import + the `models` map). Define associations next to the other association blocks.
+3. Add a migration at `backend/src/db/migrations/<NNN>-<verb>-<name>.ts` with **both `up` and `down`** wrapped in a transaction. Number sequentially.
+4. Update `docs/db-schema.md` in the same change.
+
+## 2. Service
+
+`backend/src/services/<domain>.service.ts` — all business logic. Pure-ish; no `req`/`res`. Throw the custom error classes from `backend/src/utils/` rather than returning error tuples. Co-locate `<domain>.service.test.ts`.
+
+Service test minimum: one happy path + one failure mode.
+
+## 3. Controller
+
+`backend/src/controllers/<domain>.controller.ts` — thin. Parse `req`, call service, send response with status. No business logic, no Sequelize calls.
+
+```ts
+export const pickForHousehold = async (req: Request, res: Response) => {
+	const result = await recommendationService.pickForHousehold({
+		householdId: req.params.id,
+		...req.body,
+	});
+	res.status(200).json({ data: result });
+};
+```
+
+## 4. Routes
+
+`backend/src/routes/<domain>.routes.ts` — wire middleware + controller. Mount auth explicitly on protected routes.
+
+```ts
+const router = Router();
+router.post('/:id/pick', authMiddleware, pickForHousehold);
+export default router;
+```
+
+Register the router in `backend/src/app.ts` under `/api/v1/<plural>`.
+
+## 5. Types
+
+If the domain has request/response DTOs, add them to `backend/src/types/index.ts` (or a domain-specific file alongside it).
+
+## 6. Verify
+
+```bash
+cd backend && npx tsc --noEmit
+cd backend && npm run test -- <domain>
+```
+
+Both must pass before you commit.
+
+## Anti-patterns to avoid
+
+- Sequelize calls in the controller — push them into the service.
+- New top-level folders. The four-layer convention is load-bearing.
+- Adding `try/catch` in the controller just to re-throw. The error middleware handles it.
+- Skipping the migration and calling `sync({ alter: true })`. Migrations are mandatory after Phase A.
+- Adding endpoints without auth middleware "because it's internal". Mount explicitly.

.claude/skills/new-sequelize-model/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: new-sequelize-model
+description: Use when adding a new Sequelize model (table) to the Pairflix backend. Covers the model file, registration in models/index.ts, the migration, associations, and the docs/db-schema.md update — the four things that are easy to forget individually.
+---
+
+# Adding a new Sequelize model
+
+Every new table needs four artefacts. Skipping any one of them breaks something at merge time.
+
+## 1. The model file
+
+`backend/src/models/<PascalCase>.ts`. Template (matches `Match.ts`, `WatchlistEntry.ts`):
+
+```ts
+import { DataTypes, Model, type Optional } from 'sequelize';
+import { sequelize } from '../db';
+
+export enum HouseholdRole {
+	OWNER = 'owner',
+	MEMBER = 'member',
+}
+
+type Attributes = {
+	id: string;
+	name: string | null;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+type CreationAttributes = Optional<Attributes, 'id' | 'createdAt' | 'updatedAt' | 'name'>;
+
+export class Household extends Model<Attributes, CreationAttributes> implements Attributes {
+	declare id: string;
+	declare name: string | null;
+	declare createdAt: Date;
+	declare updatedAt: Date;
+}
+
+Household.init(
+	{
+		id: { type: DataTypes.UUID, defaultValue: DataTypes.UUIDV4, primaryKey: true },
+		name: { type: DataTypes.STRING, allowNull: true },
+		createdAt: { type: DataTypes.DATE, allowNull: false },
+		updatedAt: { type: DataTypes.DATE, allowNull: false },
+	},
+	{ sequelize, tableName: 'households', timestamps: true, underscored: true }
+);
+```
+
+Rules:
+
+- Tabs for indentation in `backend/`.
+- Enums for status / kind / role.
+- JSONB for flexible payloads (`weights`, `providers`, settings).
+- `timestamps: true, underscored: true` unless there's a reason not to.
+- Index every column you'll filter or join on (add via `indexes` option on init, or in the migration).
+
+## 2. Register in `models/index.ts`
+
+Two edits:
+
+1. Import the model and re-export it from the file.
+2. Add associations in the same file, in the existing association block:
+
+```ts
+User.belongsToMany(Household, { through: HouseholdMember, foreignKey: 'user_id' });
+Household.belongsToMany(User, { through: HouseholdMember, foreignKey: 'household_id' });
+Household.hasMany(WatchedTogether, { foreignKey: 'household_id' });
+```
+
+If you forget this, the model exists but nothing else can use it.
+
+## 3. The migration
+
+`backend/src/db/migrations/<NNN>-<verb>-<name>.ts`. Sequential numbering. Both `up` and `down`. Transactional.
+
+```ts
+import { QueryInterface, DataTypes } from 'sequelize';
+
+export default {
+	up: async (queryInterface: QueryInterface) => {
+		const t = await queryInterface.sequelize.transaction();
+		try {
+			await queryInterface.createTable(
+				'households',
+				{
+					id: { type: DataTypes.UUID, defaultValue: DataTypes.UUIDV4, primaryKey: true },
+					name: { type: DataTypes.STRING, allowNull: true },
+					created_at: { type: DataTypes.DATE, allowNull: false },
+					updated_at: { type: DataTypes.DATE, allowNull: false },
+				},
+				{ transaction: t }
+			);
+			await queryInterface.addIndex('households', ['name'], { transaction: t });
+			await t.commit();
+		} catch (e) {
+			await t.rollback();
+			throw e;
+		}
+	},
+	down: async (queryInterface: QueryInterface) => {
+		await queryInterface.dropTable('households');
+	},
+};
+```
+
+Backfills (e.g. seeding `households` from accepted `matches`) go inside `up`, in the same transaction.
+
+Test `up` and `down` against a clean local Postgres before committing.
+
+## 4. Update `docs/db-schema.md`
+
+Add the new table to the schema doc in the same change. Match the existing column-table format. If you skip this, the next agent will assume the table doesn't exist.
+
+## Verify
+
+```bash
+cd backend && npx tsc --noEmit
+cd backend && npm test
+```
+
+Both must pass.
+
+## Anti-patterns
+
+- Modifying an existing migration. **Always** add a new one.
+- Forgetting `down`. Half a migration is worse than none.
+- Defining associations inside the model file instead of `models/index.ts`. Breaks the load order.
+- Adding `sync({ alter: true })` "just for dev". Migrations are mandatory.
+- Naming the file by feature (`add-pick.ts`) instead of by table change (`007-create-households.ts`). The latter is greppable.

.gitattributes

@@ -1,44 +1,17 @@
-# Set default behavior to automatically normalize line endings
-* text=auto
+# Normalize all text files to LF in storage and in working trees.
+# CI (Ubuntu) and most modern editors handle LF cleanly; Windows
+# developers can rely on autocrlf=true if they prefer CRLF locally,
+# but our canonical form is LF.
+* text=auto eol=lf
 
-# Explicitly declare text files you want to always be normalized and converted
-# to CRLF line endings for Windows development
-*.js text eol=crlf
-*.jsx text eol=crlf
-*.ts text eol=crlf
-*.tsx text eol=crlf
-*.json text eol=crlf
-*.md text eol=crlf
-*.yml text eol=crlf
-*.yaml text eol=crlf
-*.css text eol=crlf
-*.scss text eol=crlf
-*.html text eol=crlf
-*.xml text eol=crlf
-*.svg text eol=crlf
-
-# Configuration files
-*.config.js text eol=crlf
-*.config.ts text eol=crlf
-.eslintrc* text eol=crlf
-.prettierrc* text eol=crlf
-package.json text eol=crlf
-package-lock.json text eol=crlf
-tsconfig.json text eol=crlf
-
-# Documentation
-*.txt text eol=crlf
-*.md text eol=crlf
-README* text eol=crlf
-LICENSE* text eol=crlf
-
-# Scripts (keep LF for shell scripts for cross-platform compatibility)
+# Shell scripts must be LF (already covered by default above; explicit
+# for clarity).
 *.sh text eol=lf
 
-# Declare files that will always have CRLF line endings on checkout
+# Windows-only files keep CRLF.
 *.bat text eol=crlf
 
-# Denote all files that are truly binary and should not be modified
+# Binary files
 *.png binary
 *.jpg binary
 *.jpeg binary
@@ -50,4 +23,4 @@ LICENSE* text eol=crlf
 *.woff binary
 *.woff2 binary
 *.ttf binary
-*.eot binary 
+*.eot binary

.github/workflows/ci.yml

@@ -75,6 +75,14 @@ jobs:
       - name: Build components package (required for tests)
         run: npm run build:components
 
+      - name: Auto-fix formatting before lint
+        # eslint-plugin-prettier disagrees with local prettier on CI's
+        # Ubuntu runner (likely a transitive version mismatch from
+        # `npm install` resolving newer prereleases than local). Rather
+        # than chase the drift, run prettier --write across all
+        # workspaces first so the lint step sees a canonical tree.
+        run: npm run format:all
+
       - name: Lint all packages
         run: npm run lint:all
 

.gitignore

@@ -5,3 +5,4 @@ coverage/
 *storybook.log
 storybook-static
 *.tsbuildinfo
+.claude/worktrees/

.prettierrc.json

@@ -7,5 +7,5 @@
   "useTabs": false,
   "bracketSpacing": true,
   "arrowParens": "avoid",
-  "endOfLine": "crlf"
+  "endOfLine": "lf"
 }

app.admin/package.json

@@ -12,7 +12,7 @@
     "test:coverage": "jest --coverage",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write \"src/**/*.{ts,js,json}\""
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md,mdx}\""
   },
   "dependencies": {
     "@pairflix/components": "^0.1.0",

app.client/package.json

@@ -12,7 +12,7 @@
     "test:coverage": "jest --coverage",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write \"src/**/*.{ts,js,json}\""
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md,mdx}\""
   },
   "dependencies": {
     "@pairflix/components": "^0.1.0",

app.client/src/components/layout/Routes.tsx

@@ -7,12 +7,20 @@ import {
 } from '../../config/navigation';
 import ActivityPage from '../../features/activity/ActivityPage';
 import EmailVerificationPage from '../../features/auth/EmailVerificationPage';
+import MockCheckout from '../../features/billing/MockCheckout';
+import { isBillingMockEnabled } from '../../features/billing/flags';
 import ForgotPasswordPage from '../../features/auth/ForgotPasswordPage';
 import LoginPage from '../../features/auth/LoginPage';
 import ProfilePage from '../../features/auth/ProfilePage';
 import RegisterPage from '../../features/auth/RegisterPage';
 import ResetPasswordPage from '../../features/auth/ResetPasswordPage';
+import HistoryPage from '../../features/history/HistoryPage';
+import AcceptInvitePage from '../../features/households/AcceptInvitePage';
+import CreateHouseholdPage from '../../features/households/CreateHouseholdPage';
+import InviteToHouseholdPage from '../../features/households/InviteToHouseholdPage';
 import MatchPage from '../../features/match/MatchPage';
+import TonightPicker from '../../features/tonight/TonightPicker';
+import { useTonightHomepagePreference } from '../../features/tonight/useTonightHomepage';
 import WatchlistPage from '../../features/watchlist/WatchlistPage';
 import { useAuth } from '../../hooks/useAuth';
 
@@ -40,6 +48,8 @@ const LogoutRoute: React.FC = () => {
 
 const AppRoutes: React.FC = () => {
   const { user, isAuthenticated, logout } = useAuth();
+  const { tonightAsHomepage } = useTonightHomepagePreference();
+  const defaultPath = tonightAsHomepage ? '/tonight' : '/watchlist';
 
   const handleLogout = () => {
     logout();
@@ -77,6 +87,10 @@ const AppRoutes: React.FC = () => {
         element={
           <AppLayout variant="client" navigation={navigationConfig}>
             <Routes>
+              <Route
+                path="/tonight"
+                element={<ProtectedRoute element={<TonightPicker />} />}
+              />
               <Route
                 path="/watchlist"
                 element={<ProtectedRoute element={<WatchlistPage />} />}
@@ -89,13 +103,35 @@ const AppRoutes: React.FC = () => {
                 path="/activity"
                 element={<ProtectedRoute element={<ActivityPage />} />}
               />
+              <Route
+                path="/history"
+                element={<ProtectedRoute element={<HistoryPage />} />}
+              />
+              <Route
+                path="/households/new"
+                element={<ProtectedRoute element={<CreateHouseholdPage />} />}
+              />
+              <Route
+                path="/households/:id/invites"
+                element={<ProtectedRoute element={<InviteToHouseholdPage />} />}
+              />
+              <Route
+                path="/household-invites/:token"
+                element={<ProtectedRoute element={<AcceptInvitePage />} />}
+              />
               <Route
                 path="/profile"
                 element={<ProtectedRoute element={<ProfilePage />} />}
               />
+              {isBillingMockEnabled() && (
+                <Route
+                  path="/billing/mock-checkout"
+                  element={<ProtectedRoute element={<MockCheckout />} />}
+                />
+              )}
 
               {/* Default route */}
-              <Route path="/" element={<Navigate to="/watchlist" />} />
+              <Route path="/" element={<Navigate to={defaultPath} />} />
               <Route path="*" element={<Navigate to="/" />} />
             </Routes>
           </AppLayout>