From 88a9571d9c4d38fad58354a2eea3d7758b201165 Mon Sep 17 00:00:00 2001
From: "kiloconnect[bot]" <240665456+kiloconnect[bot]@users.noreply.github.com>
Date: Wed, 19 Aug 2026 13:56:55 +0000
Subject: [PATCH] docs(db): note user IDs are not always UUIDs

---
 packages/db/AGENTS.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/db/AGENTS.md b/packages/db/AGENTS.md
index c34bf481b9..b47f44650c 100644
--- a/packages/db/AGENTS.md
+++ b/packages/db/AGENTS.md
@@ -34,6 +34,15 @@ When adding user or account PII to shared PostgreSQL, update `softDeleteUser` in
 `apps/web/src/lib/user/index.ts` to delete or anonymize it and add corresponding
 coverage in `apps/web/src/lib/user/index.test.ts`.
 
+## User IDs
+
+A user ID is NOT always a UUID. It is an arbitrary string that may be a UUID or
+another format; OAuth user IDs usually start with the prefix `oauth/`. This is
+why `kilocode_users.id` and every user-ID reference (for example
+`kilo_user_id`, `user_id`) is a `text()` column rather than `uuid()`. Do not
+assume the UUID shape: avoid UUID validation, parsing, or `uuid()`-typed
+columns and `::uuid` casts on user IDs, since they break for OAuth users.
+
 ## Timestamp boundaries
 
 Drizzle/PostgreSQL `timestamp({ withTimezone: true, mode: 'string' })` values