diff --git a/backend/README.md b/backend/README.md
index 22e1fd6e..7cc15b5d 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -31,6 +31,31 @@ We use Prisma as our ORM to interact with PostgreSQL.
 - Schema is located at `prisma/schema.prisma`.
 - Run `npx prisma studio` to view the database through a web UI.
 
+### `prisma.config.ts` vs `prisma/schema.prisma`
+
+There are two Prisma files, and they do different jobs:
+
+| File | Owns |
+| ---- | ---- |
+| `prisma/schema.prisma` | The **data model** — models, enums, relations, the `datasource` and `generator` blocks. This is what `prisma generate` turns into the client. |
+| `prisma.config.ts` | The **Prisma CLI configuration** — where the CLI looks for things and how it connects when you run `prisma generate`, `prisma migrate`, `prisma db push`, or `prisma studio`. |
+
+`prisma.config.ts` exists as a separate file because it is TypeScript that Node evaluates before the CLI runs, so it can do things `schema.prisma` cannot — most importantly read environment variables. Prisma 7 (this project is on `prisma@^7.4.1`) no longer auto-loads `.env` for CLI commands, which is why the file starts with `import "dotenv/config"`.
+
+What it currently sets:
+
+- `schema: "prisma/schema.prisma"` — path to the schema, so CLI commands work from the `backend/` directory without a `--schema` flag.
+- `migrations.path: "prisma/migrations"` — where migration folders are read from and written to.
+- `datasource.url: process.env["DATABASE_URL"]` — the connection string the CLI uses.
+
+### Troubleshooting
+
+If a `prisma generate` / `prisma migrate` command misbehaves, check `prisma.config.ts` before assuming the schema is at fault:
+
+- **"Environment variable not found: DATABASE_URL"** or the CLI connecting to the wrong database — the config resolves `DATABASE_URL` at load time via `dotenv/config`, so it reads `backend/.env`. A variable exported only in your shell after the process starts, or set in a `.env` outside `backend/`, will not be picked up.
+- **CLI can't find the schema or migrations** — these paths are relative to `backend/`. Running `prisma` from the repo root will not resolve them.
+- **`npm run prisma:seed` not running the seed script** — the seed command is declared in the legacy `prisma.seed` field in `package.json`. Prisma 7 expects it as `migrations.seed` in `prisma.config.ts`, so if seeding silently does nothing, check both places.
+
 ## /v1 API
 
 All REST API endpoints are prefixed with `/v1`. Refer to the API Documentation in the root `README.md` and the `docs/` folder for versioning and authentication details.
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index e285382f..10c39a4a 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -68,6 +68,8 @@ npm run prisma:generate
 npm run prisma:migrate
 ```
 
+These commands read their paths and connection string from `backend/prisma.config.ts`, which configures the Prisma CLI separately from the data model in `backend/prisma/schema.prisma`. See [Prisma Database](../backend/README.md#prismaconfigts-vs-prismaschemaprisma) in the backend README for what each file owns and what to check when a `generate`/`migrate` command misbehaves.
+
 Start backend:
 
 ```bash
@@ -199,6 +201,7 @@ Configure in `.env`:
 * Check `DATABASE_URL`
 * Run `prisma generate`
 * Reset DB if schema drift occurs
+* Check `backend/prisma.config.ts` — it sets the schema path, migrations path, and the `DATABASE_URL` the CLI uses ([details](../backend/README.md#troubleshooting))
 
 ---