diff --git a/packages/db/README.md b/packages/db/README.md
new file mode 100644
index 00000000..742af7c4
--- /dev/null
+++ b/packages/db/README.md
@@ -0,0 +1,24 @@
+# @atomcms/db
+
+Typed data-access layer over the **emulator-owned** MySQL database.
+
+## Hard rule: introspect-only
+
+The database schema is owned and written live by the Habbo game emulator.
+**Never** run `drizzle-kit push`, `generate`, or `migrate` against it. The only
+allowed schema command is introspection:
+
+    DATABASE_URL=mysql://user:pass@host:3306/db pnpm --filter @atomcms/db db:pull
+
+`db:pull` reads the live schema and writes a snapshot to `./drizzle`. The
+hand-authored files in `src/schema/` cover only the tables the web tier needs
+first (users, users_currency, bans, website_settings); regenerate the full
+122-table set from the live DB with `db:pull` when you need more tables.
+
+## Usage
+
+    import { createDb, makeUsersRepo } from "@atomcms/db";
+    const { db, pool } = createDb(process.env.DATABASE_URL!);
+    const users = makeUsersRepo(db);
+    const sysacc = await users.findByUsername("Systemaccount");
+    await pool.end();
diff --git a/packages/db/drizzle.config.ts b/packages/db/drizzle.config.ts
new file mode 100644
index 00000000..40417a8d
--- /dev/null
+++ b/packages/db/drizzle.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from "drizzle-kit";
+
+// INTROSPECT-ONLY. We never generate or push migrations against this database —
+// it is owned and written live by the game emulator. Use only `drizzle-kit pull`.
+export default defineConfig({
+  dialect: "mysql",
+  schema: "./src/schema/index.ts",
+  out: "./drizzle", // where `pull` writes the introspected schema snapshot
+  dbCredentials: {
+    url: process.env.DATABASE_URL ?? "",
+  },
+});