From bdc25e0c5893164afac6ec61efaef45485b8d888 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 6 Jun 2026 18:03:55 +0000
Subject: [PATCH] Document Drizzle migration journal requirement in AGENTS.md

---
 AGENTS.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 6cb048b..4cd373c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -273,6 +273,25 @@ export const exampleRouter = createTRPCRouter({
 - **User Relations**: All business data linked to users
 - **Indexes**: Proper indexing for performance
 
+### Migrations
+When adding a new migration:
+1. Create the SQL file in `drizzle/` following the numbering sequence (e.g. `0011_my_change.sql`)
+2. **Always update `drizzle/meta/_journal.json`** to include the new entry — Drizzle's migrate runner uses this file to determine which migrations to apply. If the entry is missing, the migration will be silently skipped on deploy.
+
+The journal entry format:
+```json
+{
+  "idx": 10,
+  "version": "7",
+  "when": 1780704000000,
+  "tag": "0010_my_change",
+  "breakpoints": true
+}
+```
+Use a Unix timestamp in milliseconds for `when`, incrementing `idx` by 1 from the previous entry.
+
+Migrations run automatically at container startup via `bun migrate.ts` (see Dockerfile `CMD`). Do not run them manually.
+
 ### Relationships
 - **Users → Clients**: One-to-many
 - **Users → Businesses**: One-to-many