diff --git a/AGENTS.md b/AGENTS.md
index a1c641a..852f127 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,15 +15,15 @@ accepted ISAM 2026 demo paper.
 
 > [!IMPORTANT]
 > **This repository is in maintenance mode.** v5 is the live Cornell Tech
-> deployment and stays on Notion. Active development continues in a separate
-> repository — see below. Changes here should be fixes and operational
-> improvements, not new architecture.
+> deployment. Active development continues in a separate repository — see
+> below. Changes here should be fixes and operational improvements, not new
+> architecture.
 
 ## Repository layout — two apps
 
 | Path | Version | Status | Data layer |
 |---|---|---|---|
-| `v5/` | v5 | **Live — work here** | Notion (`NOTION_DB_*`) |
+| `v5/` | v5 | **Live — work here** | Postgres (`DATABASE_URL`); Notion read only by the one-time import |
 | `src/` (root) | v4 | Legacy, frozen | AirTable (`AIRTABLE_TABLE_*`) |
 
 **Default to `v5/` unless a task explicitly names v4.** The root app is retained
@@ -62,7 +62,7 @@ Run from `v5/`:
 
 ```bash
 npm run dev          # dev server (:3000)
-npm run build        # production build
+npm run build        # runs db:migrate, then production build
 npm run lint         # eslint
 npm run typecheck    # tsc --noEmit
 npm test             # vitest (unit + integration + component)
@@ -70,8 +70,9 @@ npm run test:e2e     # playwright (needs: npx playwright install chromium)
 npm run test:all     # lint + typecheck + vitest + playwright
 ```
 
-`npm run test:all` must pass before any merge. It needs no credentials — the
-mock catalog and MSW cover every external service.
+`npm run test:all` must pass before any merge. It needs no credentials — an
+in-process PGlite database (seeded with demo data) covers Postgres and MSW
+covers every other external service.
 
 ## Conventions
 
@@ -90,8 +91,11 @@ mock catalog and MSW cover every external service.
   the default Node runtime.
 - The in-memory rate limiter is a per-process singleton and resets on cold start.
   Upstash backs it only when **both** `UPSTASH_REDIS_REST_*` vars are set.
-- The mock-catalog fallback triggers when **any** Notion env var is missing *or* a
-  fetch throws. Great for tests; means a misconfigured deploy fails soft and
-  silently serves mock data. Check the logs before concluding the catalog is empty.
+- `DATABASE_URL` unset serves an in-process PGlite database seeded with demo
+  data — great for tests and a fresh clone, but check that it's actually set
+  in a real deploy before concluding the catalog is empty. Unlike the old
+  Notion fallback, a **configured but unreachable** Postgres never falls back
+  to demo data — it fails toward stale cache or an explicit error state
+  (constitution Article 4).
 - Scripts under `v5/scripts/` run via `node --experimental-strip-types`. They are
   migration and maintenance tools, not part of the app build.
diff --git a/CLAUDE.md b/CLAUDE.md
index 7bdc9be..7f3751b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,9 +7,9 @@ one place stops the two documents from drifting apart.
 
 Two things to know before anything else:
 
-1. **The active app is `v5/`** (Notion-backed), not the root `src/` tree (v4,
-   AirTable, frozen). When working in `v5/`, also read
-   [`v5/AGENTS.md`](./v5/AGENTS.md).
+1. **The active app is `v5/`** (Postgres-backed, with Notion read only by the
+   one-time import), not the root `src/` tree (v4, AirTable, frozen). When
+   working in `v5/`, also read [`v5/AGENTS.md`](./v5/AGENTS.md).
 2. **This repository is in maintenance mode.** v5 is the live Cornell Tech
    deployment. Next-generation development happens in a separate repository —
    see `AGENTS.md`.
diff --git a/docs/handover.md b/docs/handover.md
index 676826c..a96b648 100644
--- a/docs/handover.md
+++ b/docs/handover.md
@@ -13,19 +13,24 @@
 ## 1. What this system is, in operational terms
 
 A website that lists the lab's machines and answers questions about them. The data lives in
-**Notion** — seven databases that staff edit directly. The website reads from Notion and
-adds an AI assistant on top.
+**Postgres** (Neon, provisioned through Vercel) and the website reads from there, with an AI
+assistant on top. **The website no longer reads Notion.** Notion was the source of truth
+before this phase; its seven databases were read once, by a developer, to move everything
+into Postgres, and are not read again. A one-way mirror back into an admin's own Notion
+workspace is planned for a later phase.
 
-**Editing the catalogue means editing Notion.** There is no admin login and no dashboard,
-by design. If a machine's description is wrong, you fix it in Notion, and the website
-catches up within minutes.
+**There is no admin login or dashboard yet, so there is currently no way to edit the
+catalogue from the website.** Editing the old Notion databases no longer has any effect —
+the website stopped reading them. Until inventory editing ships on the website, a wrong
+record needs a developer **[dev]** to fix directly in Postgres.
 
 Three moving parts, and it is worth knowing which is which when something is wrong:
 
 | Part | What it is | Who provides it |
 |---|---|---|
 | **The website** | The app itself | Hosted on Vercel |
-| **The data** | Seven databases | Notion workspace |
+| **The data** | Tools, units, categories, locations, resources, tickets, projects | Neon Postgres (provisioned through Vercel) |
+| **Files** | Tool images, manuals, project photos | Vercel Blob |
 | **The assistant** | The AI | Anthropic API (Claude) |
 
 ---
@@ -38,14 +43,15 @@ owner.
 | Thing | Where | Who owns it | Notes |
 |---|---|---|---|
 | Vercel project | vercel.com | ⬜ **TBD** | Hosting, deploys, env vars, logs |
-| Notion workspace | notion.so | ⬜ **TBD** | The seven databases |
-| Notion integration token | Notion settings | ⬜ **TBD** | `NOTION_API_KEY` |
+| Neon Postgres | Vercel → Storage → Marketplace | ⬜ **TBD** | **The catalogue's source of truth.** Provisioned through the Vercel Marketplace; sets `DATABASE_URL` automatically |
+| Notion workspace | notion.so | ⬜ **TBD** | The seven original databases. No longer read by the website — kept for reference until a one-way mirror is set up |
+| Notion integration token | Notion settings | ⬜ **TBD** | `NOTION_API_KEY`. Needed only to re-run the one-time import; not required for the website to run |
 | `AI_GATEWAY_API_KEY` | Vercel → AI Gateway | ⬜ **TBD** | **The intended production path.** Model spend on the hosting invoice, with a platform spend limit |
 | Anthropic API key | console.anthropic.com | ⬜ **TBD** | **Fallback.** Costs money per use. Keep it — it is the lever back if the gateway fails |
 | GitHub repository | github.com | ⬜ **TBD** | The code |
 | Domain / DNS | ⬜ | ⬜ **TBD** | |
 | `ADMIN_REVALIDATE_SECRET` | Vercel env vars | ⬜ **TBD** | Forces the site to refresh |
-| Vercel Blob store | Vercel → Storage | ⬜ **TBD** | Holds the nightly Notion backup. Sets `BLOB_READ_WRITE_TOKEN`. **Contains student PII — keep private** |
+| Vercel Blob store | Vercel → Storage | ⬜ **TBD** | Holds tool images, manuals and project photos (public) alongside maintenance photos and the nightly backup (private). Sets `BLOB_READ_WRITE_TOKEN`. **The private files contain student PII — keep those private** |
 | `CRON_SECRET` | Vercel env vars | ⬜ **TBD** | Lets the nightly backup cron prove it is Vercel (§3) |
 
 > [!WARNING]
@@ -96,20 +102,29 @@ for what remains to verify before production traffic goes through it.
 
 ### Add a machine to the catalogue
 
-1. In Notion, add a row to the **Tools** database.
-2. Fill in at least: name, description, category, location.
-3. Add units in the **Units** database, linked to the tool — one row per physical machine,
-   with serial and status.
-4. Add manuals or SOPs to **Resources**, linked to the tool.
-5. Tick **published**. Until you do, it will not appear on the site.
-6. Wait a few minutes, or force a refresh (§4).
-
-**The assistant picks it up automatically.** No deploy, no developer.
+> [!WARNING]
+> **This no longer works.** The steps below edited Notion, which the website read. The
+> website now reads Postgres and does not read Notion at all, and the on-website editor that
+> replaces this is not built yet. Adding a machine today needs a developer **[dev]** to
+> insert it directly in Postgres. Once inventory editing ships on the website, this section
+> will be rewritten to match it.
+>
+> ~~1. In Notion, add a row to the **Tools** database.~~
+> ~~2. Fill in at least: name, description, category, location.~~
+> ~~3. Add units in the **Units** database, linked to the tool — one row per physical machine,
+>    with serial and status.~~
+> ~~4. Add manuals or SOPs to **Resources**, linked to the tool.~~
+> ~~5. Tick **published**. Until you do, it will not appear on the site.~~
+> ~~6. Wait a few minutes, or force a refresh (§4).~~
 
 ### Mark a machine out of service
 
-Change the unit's **status** in the Units database to `Under Maintenance` or `Out of
-Service`. The site shows it as offline, and the assistant stops recommending it.
+> [!WARNING]
+> **This no longer works** — editing Notion has no effect on the website (see above).
+> ~~Change the unit's **status** in the Units database to `Under Maintenance` or `Out of
+> Service`. The site shows it as offline, and the assistant stops recommending it.~~ Until
+> inventory editing ships on the website, this needs a developer **[dev]** to change directly
+> in Postgres.
 
 ### Handle a maintenance ticket
 
@@ -125,10 +140,12 @@ it and how often, and write that down here:
 
 ### Fix something the assistant got wrong
 
-Almost always a data problem, not an AI problem. The assistant answers from Notion, so a
-wrong answer usually means a wrong or empty field. Fix the record; the answer changes.
+Almost always a data problem, not an AI problem. The assistant answers from Postgres, so a
+wrong answer usually means a wrong or empty field there — which, until inventory editing
+ships on the website, needs a developer **[dev]** to fix directly. Editing the old Notion
+record does nothing; the website does not read it.
 
-If it is wrong *and* the Notion record is right, that is a real bug — see §6.
+If it is wrong *and* the underlying record is right, that is a real bug — see §6.
 
 ### Change branding, colours, or the assistant's name
 
@@ -185,7 +202,8 @@ There is no automated restore, on purpose — it is far more work than the failu
 
 ## 4. Forcing the site to refresh
 
-The site caches Notion data for a few minutes. To make a change appear immediately:
+The site caches catalogue data from Postgres for a few minutes. To make a change appear
+immediately:
 
 ```
 POST https://<your-site>/api/admin/revalidate
@@ -204,7 +222,8 @@ effect.
 |---|---|---|
 | Anthropic console | **Spend.** Set a limit and an alert. | Weekly, at minimum |
 | Vercel dashboard | Failed deploys, function errors | When something looks wrong |
-| Vercel logs | `Falling back to mock catalog` | Whenever the catalogue looks odd |
+| Vercel logs | `DbUnavailableError` (Postgres unreachable) | Whenever the catalogue looks odd |
+| Vercel → Storage | The Neon database is reachable | Whenever the catalogue looks odd |
 | Vercel → Cron Jobs | The nightly backup ran green | Monthly — see §3 |
 | Notion: Maintenance_Logs | Open tickets | Per §3 |
 
@@ -217,25 +236,33 @@ recoverable; an unbounded bill is not.
 
 ### The site shows machines the lab doesn't own
 
-**Most likely cause, and it is not obvious.** The app falls back to a built-in demo
-catalogue whenever it cannot reach Notion — a missing or misspelled environment variable, an
-expired integration token, or a database that stopped being shared with the integration.
+**Now much less likely, and it no longer fails silently.** Before this phase, the app fell
+back to a built-in demo catalogue whenever it could not reach Notion, with no visible error.
+That is no longer how a database problem shows up:
 
-The site does **not** show an error. It looks perfectly healthy while serving fictional
-equipment.
+- If `DATABASE_URL` is missing from the Vercel project — a genuine misconfiguration — the
+  site serves the same small built-in demo catalogue used in development and testing, and
+  shows a banner saying so.
+- If `DATABASE_URL` is set but Postgres cannot be reached, the site keeps serving whatever it
+  last cached rather than switching to demo data, and any page that isn't cached shows an
+  error instead of inventing machines.
 
-1. Check the Vercel logs for `Falling back to mock catalog`.
-2. Check every `NOTION_DB_*` variable and `NOTION_API_KEY` in Vercel.
-3. In Notion, confirm each database is still shared with the integration.
+1. Check the Vercel logs for `DbUnavailableError`.
+2. Check `DATABASE_URL` is set in the Vercel project's environment variables.
+3. Check the Neon dashboard (Vercel → Storage) — a suspended or deleted branch is the usual
+   cause. **[dev]**
 
 ### A machine is missing from the site
 
-Check `published` is ticked in Notion. Then force a refresh (§4).
+Check `published` is set on the tool in Postgres. Then force a refresh (§4). Until inventory
+editing ships on the website, changing `published` needs a developer **[dev]**.
 
-### A field is empty on the site but filled in Notion
+### A field is empty on the site but filled in the old Notion databases
 
-Someone probably renamed the property in Notion. The app matches property names and cannot
-follow a rename. Compare against `v5/.env.example` and the other rows. **[dev]** if unclear.
+The website reads Postgres, not Notion, so this means the one-time import either mapped that
+field differently than expected or the field has since been edited in Postgres. **[dev]**:
+compare the row in Postgres against the Notion page it was imported from
+(`notion_page_id` on the row) to see where the two diverge.
 
 ### The assistant is down or erroring
 
@@ -279,10 +306,14 @@ The live app is `v5/`. The root `src/` directory is the old v4 app and is not us
 
 Nothing about Cornell is hardcoded.
 
-1. Duplicate the seven Notion databases into the new workspace.
-2. Create a Notion integration and share all seven databases with it.
-3. Deploy the repo to Vercel.
-4. Set `NOTION_API_KEY`, the seven `NOTION_DB_*` IDs, and `ANTHROPIC_API_KEY`.
+1. Deploy the repo to Vercel.
+2. Add Neon Postgres and a Blob store to the project through the Vercel Marketplace /
+   Storage tab — this sets `DATABASE_URL` and `BLOB_READ_WRITE_TOKEN` automatically. Run
+   `npm run db:migrate` once to apply the schema.
+3. Set `ANTHROPIC_API_KEY` (or `AI_GATEWAY_API_KEY`, §2).
+4. **Only if migrating an existing Notion-based catalogue:** set `NOTION_API_KEY` and the
+   seven `NOTION_DB_*` IDs, and run `npm run import:notion` once against the new database. A
+   brand-new lab with no existing data skips this step entirely.
 5. Override the `NEXT_PUBLIC_*` branding variables.
 6. Replace the logo in `v5/public/`.
 
@@ -293,9 +324,13 @@ Full variable list with explanations: `v5/.env.example`.
 ## 9. Known limitations — say these out loud at handover
 
 - **No sign-in yet.** The assistant is open to anyone with the URL. Specced, not built.
-- **The fallback is silent** (§6). Fix specced in the operational-hardening spec.
-- **No analytics.** Notion cannot aggregate, so there is no way to see which machines get
-  asked about most. This is the main reason a successor project exists.
+- **No catalogue editing on the website yet.** Postgres is the source of truth, but the
+  admin inventory pages that let staff edit it there are a later phase (§6, §8). Until then, a
+  wrong or missing record needs a developer.
+- **The old silent fallback is fixed.** A configured-but-unreachable database now fails
+  toward stale cached data or an explicit error, never toward invented equipment (§6).
+- **No analytics.** There is no way to see which machines get asked about most. This is the
+  main reason a successor project exists.
 - **No backup beyond Notion's own version history.** Notion keeps page history; there is no
   separate export. Consider a periodic manual export of the databases.
 - **One person built this.** That is the risk this document exists to reduce. If something
diff --git a/docs/specs/2026-09-14-v5-data-platform-design.md b/docs/specs/2026-09-14-v5-data-platform-design.md
index 65d5c54..c9cfa90 100644
--- a/docs/specs/2026-09-14-v5-data-platform-design.md
+++ b/docs/specs/2026-09-14-v5-data-platform-design.md
@@ -1012,3 +1012,20 @@ Appended per [`DRIFT.md`](DRIFT.md). Original text above is never edited — the
 - **`db:migrate` is not yet part of the Vercel build.** Phase 2 adds it to the build command when Neon exists; until then a build needs no database.
 
 **Status.** Accepted. Each is a detail the spec left to implementation.
+
+### 2026-09-15 — Phase 2 built, with as-built details
+
+**What changed.** Phase 2 (§9) is implemented: every read path is on Postgres through `src/lib/data/` (catalogue, projects, resources, maintenance history), `src/lib/catalog.ts` and `src/lib/projects.ts` keep their exports and their `"use cache"` tags over the new modules, the health route probes Postgres, `/tools/<notion-page-id>` redirects to the slug, the QR-label script reads Postgres, and the repo docs say Postgres. `npm run build` now runs `db:migrate` first. Details the spec did not name:
+
+- **A bridge from Postgres ids to Notion page ids, for the writes that are still on Notion.** Every id the app hands around is now a Postgres uuid, but a correction, a maintenance ticket and a project submission still create Notion pages whose relations address Notion *page* ids, and Notion refuses a relation it cannot find. `src/lib/data/notion-ids.ts` reads the page id the import recorded on `tools` and `units`; a row that has none (created after the import, or the demo seed) is written *without* the relation and logged, never with an id Notion would reject. The module leaves with those writes in Phase 3.
+- **Tool and project pages are no longer prerendered at build.** `generateStaticParams` needed a reachable database during `next build`, which §3.2 says a build must not need, and Cache Components rejects an empty list. The pages render on first request and are then served from the `catalog` / `projects` cache tags. Two visible consequences: an unknown slug and a legacy-id redirect are resolved inside the dynamic part of a partially prerendered page, so the HTTP status is 200 and the browser performs the not-found render or the redirect; printed QR labels still land on the right page. A real 404 status and a real 308 are a follow-up, not a Phase 2 goal.
+- **E2E runs against a production build, with one retry.** Under `next dev`, Playwright's fourteen parallel workers triggered first compiles of several routes at once and Turbopack rewrote the root layout's client chunk mid-response (`ERR_CONTENT_LENGTH_MISMATCH`), so pages intermittently never hydrated and four tests failed on every run. The Playwright web server is now `npm run build && next start` with `DATABASE_URL` and the Notion env blanked, which also exercises the bundled server with PGlite — the same configuration a Vercel preview without a database runs. That leaves about one test execution in a hundred failing, always the same shape: a `Link` click or the locale switch whose request is sent and answered within milliseconds (the trace shows the RSC fetch completing) but whose result the App Router never commits — the URL or the rendered locale stays put for the full assertion timeout. The server is not the bottleneck (56 concurrent requests answer in ~150 ms), no console error is logged, and a hydration-marker wait made no difference, so it is filed as a client-router race under load rather than an app defect. `retries: 1` keeps the gate green and Playwright reports such a test as *flaky*, so the count stays visible instead of hidden. Worth revisiting on the next Next.js upgrade.
+- **`/api/health` reports `database: "ok" | "unreachable" | "demo"`** and `catalog: "live" | "demo"` in place of the Notion fields; a demo substrate is `status: "ok"`, an unreachable database `degraded`, and no error text ever reaches the body.
+- **Cache tags.** Every catalogue read is tagged `catalog` only; §3.9's `tool:<id>` tag on detail reads waits for the write paths that would invalidate it, which is also where the choice of key (slug or uuid) belongs.
+- **`src/lib/data/uuid.ts`** guards every id lookup so free text from a tool call never reaches Postgres as a bad uuid cast. `listResources()` has no production caller yet; the chat route uses `listResourcesForTool()`.
+- **Retired but not deleted:** `src/components/mock-catalog.ts` (only the offline eval fixtures still pin its data), the Notion read helpers in `src/lib/notion.ts`, `test/fixtures/catalog.ts`, and the four Notion maintenance scripts §3.10 lists. Each deletion is proposed separately (constitution working agreements).
+- **English fallback for messages is in** (§6, Article 6 as amended): `src/i18n/request.ts` lays each locale file over `en.json`, so a string added only to English renders in English elsewhere. The first such strings are the sign-in notices in the header, which now say why a click on *Sign in* went nowhere instead of doing nothing (this deployment has no sign-in configured, or the request failed).
+- **Project URLs use the slug.** `MakerLabProject` gains `slug`, the gallery and a tool's "built with this" link to `/projects/<slug>`, and the project page accepts either the slug or the uuid.
+- **The demo seed has one published sample project** (a laser-cut lamp built with both demo tools, with two bundled photos under `public/sample-projects/`, materials and an outside link) and gives the Trotec a photo attachment, since its bundled image file is not named after the tool. The gallery, the project page and "built with this" are therefore exercised end to end without a database.
+
+**Status.** Accepted. The bridge and the prerender change are the two a reader should know about before Phase 3.
diff --git a/v5/.gitignore b/v5/.gitignore
index ed3d3e8..a354760 100644
--- a/v5/.gitignore
+++ b/v5/.gitignore
@@ -10,3 +10,5 @@ tsconfig.tsbuildinfo
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+.vercel
+.env*
diff --git a/v5/AGENTS.md b/v5/AGENTS.md
index e2b8f56..fe0b927 100644
--- a/v5/AGENTS.md
+++ b/v5/AGENTS.md
@@ -6,8 +6,8 @@ active application. Everything below is scoped to the `v5/` directory.
 > [!IMPORTANT]
 > The **root `CLAUDE.md` describes v4** — an AirTable-backed app with
 > `AIRTABLE_TABLE_*` env vars. **That does not apply to v5.** v5's data layer is
-> **Notion** (`NOTION_DB_*`). When working in `v5/`, follow this file, not the
-> root v4 doc.
+> **Postgres** (`DATABASE_URL`), not Notion and not AirTable. When working in
+> `v5/`, follow this file, not the root v4 doc.
 
 ## What this is
 
@@ -24,23 +24,54 @@ the catalog to external agents. White-labelled via env vars.
 - **MCP:** `@modelcontextprotocol/sdk` (HTTP JSON-RPC server at `/api/mcp`).
 - **Validation:** `zod`. **Search:** `match-sorter` (fuzzy, ranked).
 
-## Data layer — Notion (not AirTable)
-
-Seven Notion databases, IDs supplied via env (`NOTION_DB_TOOLS`, `_CATEGORIES`,
-`_LOCATIONS`, `_UNITS`, `_RESOURCES`, `_MAINTENANCE_LOGS`, `_FLAGS`) plus
-`NOTION_API_KEY`. See `.env.example` for the full list and defaults.
-
-- `src/lib/notion.ts` — server-only Notion REST client: page→record parsers, pagination, 429 retry, `createMaintenanceLog`. Tolerant of snake_case **and** Title-case property names.
-- `src/lib/catalog.ts` — orchestration: fetch + join + derive `MakerLabTool`s, cached with `cacheTag("catalog")` / `cacheLife("minutes")`.
-- **Mock-catalog fallback (important):** `getCatalogTools()` / `getCatalogTool(id)` return the built-in `src/components/mock-catalog.ts` data whenever `hasNotionCatalogEnv()` is false (**any** Notion env var missing) **or** a fetch throws. So the app — and the whole E2E/test suite — runs with no Notion creds.
+## Data layer — Postgres (not Notion, not AirTable)
+
+**Postgres is the source of truth (constitution Article 7).** Neon Postgres,
+provisioned through the Vercel Marketplace, reached through Drizzle ORM.
+`DATABASE_URL` set → Neon. `DATABASE_URL` unset → an in-process PGlite
+database, migrated and seeded with demo data on first use (two tools: "Form
+4", "Trotec Speedy 400"), so a fresh clone, local dev, and the whole test
+suite run with no credentials and no network. See `.env.example` for the full
+variable list.
+
+- `src/lib/db/client.ts` — the one entry point: `getDb()` (a Drizzle handle),
+  `dataSubstrate()` (`"neon" | "pglite-demo"`), `pingDb()` (throws
+  `DbUnavailableError`), `resetDbForTests()`.
+- `src/lib/db/schema/index.ts` — tables and vocabulary constants (stored
+  snake_case, e.g. `in_use`; display text is derived, never stored).
+- `src/lib/catalog.ts` — orchestration: fetch + join + derive `MakerLabTool`s
+  from Postgres, cached with `cacheTag("catalog")` / `cacheLife("minutes")`.
+- `src/lib/data/*.ts` — the query modules underneath: `catalog.ts`,
+  `projects.ts`, `maintenance.ts`, `resources.ts`, plus `uuid.ts` (the shape
+  guard every untrusted id passes before it reaches a uuid column) and
+  `notion-ids.ts`. Relative imports with `.ts` extensions, no `@/` alias, no
+  `"server-only"` — `scripts/` loads them under plain Node.
+- **Notion is read only by the one-time import** (`npm run import:notion`).
+  No request path reads Notion. A one-way mirror (app → an admin's own Notion
+  workspace) is a later phase, not built yet.
+- **The three writes still on Notion address pages, not rows.** A correction,
+  a maintenance ticket and a project submission create Notion pages whose
+  `relation` properties need *Notion page ids*, while everything the app hands
+  around is now a Postgres uuid. `src/lib/data/notion-ids.ts` translates
+  through `notion_page_id`, and a row that has none is written without the
+  relation rather than with an id Notion would reject — a ticket a human has
+  to link by hand beats a ticket that never arrived (Article 4). It goes away
+  with those writes in Phase 3.
+- **Files** (tool images, manuals, project photos) live in **Vercel Blob**,
+  not Notion attachments — see `next.config.ts`'s `images.remotePatterns`.
+- **Failing toward stale, not wrong (Article 4).** `DATABASE_URL` unset serves
+  the PGlite demo seed with `DemoDataBanner` shown. `DATABASE_URL` set but
+  unreachable never falls back to demo or invented data — cached pages keep
+  serving and an uncached read renders the error state.
 
 ## Key files
 
 | Path | Purpose |
 |---|---|
 | `src/lib/site-config.ts` | White-label branding (env-driven, all have defaults) |
-| `src/lib/notion.ts` | Notion API client (server-only) |
-| `src/lib/catalog.ts` | Catalog orchestration + cache + mock fallback |
+| `src/lib/db/client.ts` | `getDb()`, `dataSubstrate()`, `pingDb()` — the one entry point to Postgres/PGlite |
+| `src/lib/notion.ts` | Notion API client — write paths still on Notion until Phase 3 (tickets, corrections, project submission); no request path reads it |
+| `src/lib/catalog.ts` | Catalog orchestration + cache, reading Postgres |
 | `src/lib/rate-limit.ts` | In-memory (or Upstash) sliding-window limiter |
 | `src/lib/types.ts` / `src/components/catalog-types.ts` | Notion record types / resolved view types |
 | `src/app/api/chat/route.ts` | Claude chat: streaming, tools (`get_unit_details`, `report_issue`, `web_fetch`), PDF manual attach |
@@ -62,8 +93,8 @@ Seven Notion databases, IDs supplied via env (`NOTION_DB_TOOLS`, `_CATEGORIES`,
 
 ## Testing
 
-Comprehensive, **fully-mocked** suite (no live Notion/Anthropic/Redis). Run
-everything with one command:
+Comprehensive, **fully-mocked** suite (no live Notion/Anthropic/Redis/Postgres —
+Article 3). Run everything with one command:
 
 ```bash
 npm run test:all     # lint + typecheck + vitest + playwright
@@ -74,7 +105,10 @@ Or individually: `npm test` (Vitest: unit + integration + component),
 first), `npm run test:coverage`.
 
 - **Vitest** (jsdom) + React Testing Library + MSW; **Playwright** for E2E.
-- E2E boots its own server on **port 3100** with `NOTION_*` unset (mock catalog) and intercepts `/api/chat` — it never touches your `:3000` dev server or real services.
+- Catalogue reads run against an in-process PGlite database seeded with demo
+  data (`getCatalogTools()` needs no Notion env at all); write paths still on
+  Notion (§ above) are covered with `vi.stubEnv` + MSW as before.
+- E2E boots its own server on **port 3100** with `DATABASE_URL` unset (PGlite demo catalog) and intercepts `/api/chat` — it never touches your `:3000` dev server or real services.
 - Tests are colocated (`*.test.ts(x)` next to source); shared harness in `test/`.
 - **Read these before writing tests:** `TESTING.md` (runbook), `test/README.md` (harness internals + the `streamText`-capture and env-stubbing patterns), and `docs/specs/2026-05-29-v5-test-suite-design.md` (design + coverage matrix). The harness deps/scripts are already wired — don't hand-edit `package.json` for them.
 
@@ -82,7 +116,7 @@ first), `npm run test:coverage`.
 
 ```bash
 npm run dev          # dev server (:3000)
-npm run build        # production build
+npm run build        # runs db:migrate, then production build
 npm run lint         # eslint
 npm run typecheck    # tsc --noEmit
 npm run test:all     # full test suite
diff --git a/v5/TESTING.md b/v5/TESTING.md
index 43bced1..2babbef 100644
--- a/v5/TESTING.md
+++ b/v5/TESTING.md
@@ -9,15 +9,15 @@ import paths), see [`test/README.md`](./test/README.md).
 ## Overview
 
 The suite has four layers, all **fully mocked — no live services**. Tests never
-hit Notion, Anthropic, or Upstash; there are no API keys and no network cost.
-Everything is deterministic and offline.
+hit Postgres, Notion, Anthropic, or Upstash; there are no API keys and no
+network cost. Everything is deterministic and offline.
 
 | Layer | What | Where it lives | Runner |
 |---|---|---|---|
 | Unit | `src/lib`, `src/i18n` pure logic | colocated `*.test.ts` next to source | Vitest |
 | Integration | API routes (`/api/*`) with HTTP + module mocks | colocated `route.test.ts` next to the route | Vitest |
 | Component | React UI via React Testing Library | colocated `*.test.tsx` next to the component | Vitest |
-| E2E | Full app against the mock catalog | `e2e/*.spec.ts` | Playwright |
+| E2E | Full app against the PGlite demo catalog | `e2e/*.spec.ts` | Playwright |
 
 Shared infra lives in `test/` (MSW server + handlers, fixtures, mocks, the RTL
 `render` helper). Tests import from there; **don't edit `package.json` or run
@@ -58,16 +58,21 @@ Playwright boots its own dev server (see E2E notes below), so no separate
   `test/mocks/next-cache.ts`.
 - **`server-only`** is aliased to an empty stub (`test/mocks/server-only.ts`) in
   `vitest.config.ts`, so `rate-limit.ts` and its importers load under Vitest.
-- **Mock-catalog fallback rule.** `getCatalogTools()` / `getCatalogTool(id)`
-  return the built-in `src/components/mock-catalog.ts` data when
-  `hasNotionCatalogEnv()` is false — i.e. **any** of the 8 Notion env vars
-  (`NOTION_API_KEY` + the 7 `NOTION_DB_*`) is missing — and also on any thrown
-  error during fetch. So:
-  - **Mock path** (default in tests): leave `NOTION_*` unset → mock data, no MSW
-    needed.
-  - **Real Notion path**: `vi.stubEnv` all 8 vars (set `NOTION_DB_*` to the
-    `DB_IDS` sentinels from `test/msw/handlers.ts`) → MSW serves
-    `api.notion.com`. See the `stubNotionEnv()` helper in `test/README.md`.
+- **The PGlite rule.** `getCatalogTools()` / `getCatalogTool(id)` read from an
+  in-process **PGlite** database — real Postgres, compiled to WebAssembly,
+  migrated and seeded with demo data (two tools: `form-4`,
+  `trotec-speedy-400`) — whenever `DATABASE_URL` is unset, which is the
+  default in every test. So:
+  - **Demo-seed path** (default in tests): leave `DATABASE_URL` unset → the
+    seeded PGlite database, no MSW needed, no Notion env at all. Put
+    `// @vitest-environment node` at the top of any file that touches PGlite.
+  - **An isolated database**: `createPgliteDb()` from `src/lib/db/pglite.ts`
+    returns a fresh instance for a test that seeds its own rows.
+  - **Write paths still on Notion this phase** (tickets, corrections, project
+    submission, uploads, intake): `vi.stubEnv` all 8 Notion vars (set
+    `NOTION_DB_*` to the `DB_IDS` sentinels from `test/msw/handlers.ts`) → MSW
+    serves `api.notion.com`. See the `stubNotionEnv()` helper in
+    `test/README.md`.
 
 ## How to add a test
 
@@ -147,18 +152,17 @@ directly. Also mock `@ai-sdk/anthropic`. The full verified snippet is in
 
 ## E2E notes
 
-- Playwright's `webServer` boots `npx next dev -p 3100` with all `NOTION_*` vars
-  set to `""`, so `hasNotionCatalogEnv()` is false and the app serves the
-  built-in mock catalog (`src/components/mock-catalog.ts`) regardless of your
+- Playwright's `webServer` boots `npx next dev -p 3100` with `DATABASE_URL`
+  unset, so the app serves the seeded PGlite demo database regardless of your
   dev shell's environment. `testDir` is `./e2e`; `baseURL` is
   `http://localhost:3100`.
 - `/api/chat` is intercepted **inside each spec** at the network layer via
   `page.route()` returning a UI-message stream chunk — no real Anthropic call.
 - `reuseExistingServer: false` — Playwright **always** boots its own fresh
-  mock-backed server on the dedicated port 3100. This means E2E never collides
-  with (or accidentally reuses) a `next dev` you have running on the default
-  port 3000 against real Notion, so results are deterministic no matter what you
-  have running locally. Port 3000 is left untouched.
+  PGlite-backed server on the dedicated port 3100. This means E2E never
+  collides with (or accidentally reuses) a `next dev` you have running on the
+  default port 3000 against a real database, so results are deterministic no
+  matter what you have running locally. Port 3000 is left untouched.
 
 ## Coverage
 
diff --git a/v5/e2e/corrections.spec.ts b/v5/e2e/corrections.spec.ts
index 31d9b44..dadd94c 100644
--- a/v5/e2e/corrections.spec.ts
+++ b/v5/e2e/corrections.spec.ts
@@ -10,11 +10,12 @@ import { test, expect } from "@playwright/test";
 // intercepts that request with page.route() instead — the same technique
 // chat.spec.ts uses — so nothing leaves the machine.
 //
-// Mock catalog: "Form 4" is slug `form-4`, Notion id `tool-form-4`
-// (src/components/mock-catalog.ts). Strings are `flag.*` in messages/en.json.
+// Demo catalogue: "Form 4" is slug `form-4`; its id is the Postgres uuid the
+// seed assigned (src/lib/db/demo-seed.ts). Strings are `flag.*` in
+// messages/en.json.
 
 const FLAG_ENDPOINT = "**/api/flags";
-const TOOL_ID = "tool-form-4";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 test.describe("Report a correction", () => {
   test("the control is reachable from a tool detail page", async ({ page }) => {
@@ -102,9 +103,9 @@ test.describe("Report a correction", () => {
     ).toHaveCount(0);
 
     // The report identifies the specific field, not just the tool (spec §2), and
-    // carries the tool's Notion id rather than its slug.
+    // carries the tool's database id rather than its slug.
     expect(submitted).toMatchObject({
-      tool_id: TOOL_ID,
+      tool_id: expect.stringMatching(UUID),
       field_flagged: "description",
       issue_description: "The build volume says 220 mm, but it is 256 mm.",
     });
diff --git a/v5/e2e/gallery.spec.ts b/v5/e2e/gallery.spec.ts
index cc71e35..ed833f7 100644
--- a/v5/e2e/gallery.spec.ts
+++ b/v5/e2e/gallery.spec.ts
@@ -1,11 +1,11 @@
 import { test, expect } from "@playwright/test";
 
-// The app boots with NOTION_* unset (see playwright.config.ts webServer.env),
-// so getCatalogTools() serves the built-in mock catalog
-// (src/components/mock-catalog.ts): "Form 4" and "Trotec Speedy 400".
+// The app boots with DATABASE_URL and NOTION_* unset (see playwright.config.ts
+// webServer.env), so getCatalogTools() serves the PGlite demo seed
+// (src/lib/db/demo-seed.ts): "Form 4" and "Trotec Speedy 400".
 
 test.describe("Gallery", () => {
-  test("loads at / and shows the mock-catalog tools", async ({ page }) => {
+  test("loads at / and shows the demo-catalogue tools", async ({ page }) => {
     await page.goto("/");
 
     // Gallery heading from messages/en.json gallery.title => "TOOLS // MACHINES".
@@ -34,7 +34,7 @@ test.describe("Gallery", () => {
   test("shows the catalog status strip count", async ({ page }) => {
     await page.goto("/");
     // GlobalChrome status strip renders status.toolsInInventory:
-    // "{count} TOOLS IN INVENTORY" with count=2 (mock catalog has 2 tools).
+    // "{count} TOOLS IN INVENTORY" with count=2 (the demo seed has 2 tools).
     await expect(page.getByText("2 TOOLS IN INVENTORY")).toBeVisible();
   });
 });
diff --git a/v5/e2e/projects.spec.ts b/v5/e2e/projects.spec.ts
index beb43a3..c5a09ba 100644
--- a/v5/e2e/projects.spec.ts
+++ b/v5/e2e/projects.spec.ts
@@ -1,11 +1,10 @@
 import { test, expect } from "@playwright/test";
 
-// The app boots with NOTION_* unset (see playwright.config.ts webServer.env),
-// so `hasProjectsEnv()` is false: `getPublishedProjects()` returns [] without
-// ever calling Notion, and `POST /api/projects` answers 503 "not configured".
-// That is the correct production behaviour for a lab that has not created the
-// Projects database yet — so the gallery here is asserted as an *intentional*
-// empty state, not a broken one.
+// The app boots with no DATABASE_URL and NOTION_* unset (see
+// playwright.config.ts webServer.env), so the gallery reads the PGlite demo
+// seed — one published sample project, "Laser-cut plywood lamp"
+// (src/lib/db/demo-seed.ts) — and `POST /api/projects`, still a Notion write
+// until Phase 3, would answer 503 "not configured".
 //
 // The submit path is therefore exercised with `page.route("**/api/projects")`
 // standing in for the route handler, exactly as chat.spec.ts stands in for
@@ -31,9 +30,7 @@ async function fillRequiredFields(page: import("@playwright/test").Page) {
 }
 
 test.describe("Projects gallery", () => {
-  test("renders an intentional empty state with no Projects database", async ({
-    page,
-  }) => {
+  test("renders the sample project and opens its page", async ({ page }) => {
     await page.goto("/projects");
 
     // projects.title => "STUDENT PROJECTS".
@@ -41,23 +38,31 @@ test.describe("Projects gallery", () => {
       page.getByRole("heading", { name: "STUDENT PROJECTS", level: 1 })
     ).toBeVisible();
 
-    // The lede describes the gallery rather than apologising for it, and its
-    // {institution} placeholder resolved.
+    // The lede describes the gallery, and its {institution} placeholder resolved.
     await expect(
       page.getByText(/Builds, experiments, and course outcomes from/i)
     ).toBeVisible();
 
-    // projects.empty — reads as "nothing published yet", not as an error. No
-    // failure language, and the invitation to submit is still offered.
-    await expect(
-      page.getByText("No projects published yet. Be the first to share your build.")
-    ).toBeVisible();
+    // The demo seed's one published project is listed, with no failure language.
+    const card = page.getByRole("link").filter({ hasText: "Laser-cut plywood lamp" }).first();
+    await expect(card).toBeVisible();
     await expect(
       page.getByText(/error|failed|unavailable|something went wrong/i)
     ).toHaveCount(0);
 
     // Whole-page check: no locale placeholder rendered literally anywhere.
     await expect(page.locator("body")).not.toContainText(PLACEHOLDER_LEAK);
+
+    // Its page shows the write-up, the outside link and the tools it was built with.
+    await card.click();
+    await expect(page).toHaveURL(/\/projects\/laser-cut-plywood-lamp$/);
+    await expect(
+      page.getByRole("heading", { name: "Laser-cut plywood lamp", level: 1 })
+    ).toBeVisible();
+    await expect(
+      page.getByRole("link", { name: /wikipedia/i }).first()
+    ).toHaveAttribute("href", /en\.wikipedia\.org\/wiki\/Laser_cutting/);
+    await expect(page.getByRole("link", { name: "Trotec Speedy 400" })).toBeVisible();
   });
 
   test("the empty state's call to action reaches the submit form", async ({
@@ -105,7 +110,7 @@ test.describe("Project submission form", () => {
       page.getByRole("textbox", { name: "Link (optional)" })
     ).toBeVisible();
 
-    // Tools-used chips come from the mock catalog via getCatalogTools().
+    // Tools-used chips come from the demo catalogue via getCatalogTools().
     await expect(
       page.getByRole("button", { name: "Form 4", exact: true })
     ).toBeVisible();
@@ -223,7 +228,10 @@ test.describe("Project submission form", () => {
     const payload = bodies[0] as Record<string, unknown>;
     expect(payload.title).toBe("Parametric stool");
     expect(payload.author).toBe("Ada Lovelace");
-    expect(payload.tools).toEqual(["tool-trotec-speedy-400"]);
+    // The chosen tool travels as its database id (a uuid), not its slug.
+    expect(payload.tools).toEqual([
+      expect.stringMatching(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/),
+    ]);
     expect(payload).not.toHaveProperty("published");
   });
 
diff --git a/v5/e2e/tool-detail.spec.ts b/v5/e2e/tool-detail.spec.ts
index e00dda9..b8485e3 100644
--- a/v5/e2e/tool-detail.spec.ts
+++ b/v5/e2e/tool-detail.spec.ts
@@ -1,7 +1,9 @@
 import { test, expect } from "@playwright/test";
 
-// Mock catalog: Form 4 (slug "form-4") has one unit "Form 4 // A" (serial
-// ML-F4-001) and two resource links (Form 4 SOP / Resin handling safety).
+// Demo seed: Form 4 (slug "form-4") has one unit "Form 4 // A" (serial
+// ML-F4-001), two resource links (Form 4 SOP / Resin handling safety), and a
+// `notionPageId` of 1f2e3d4c-5b6a-4789-8abc-def012345678 (src/lib/db/demo-seed.ts)
+// used below to exercise the legacy `/tools/<notion-id>` redirect (spec Goal 2).
 
 test.describe("Tool detail", () => {
   test("deep-link /tools/form-4 shows name, units and resources", async ({
@@ -47,4 +49,24 @@ test.describe("Tool detail", () => {
     // Trotec unit serial.
     await expect(page.getByText("ML-LSR-400").first()).toBeVisible();
   });
+
+  test("a legacy Notion-id link redirects permanently to the slug, preserving ?src=qr", async ({
+    page,
+  }) => {
+    // Undashed, as it appears in a printed QR code — lands on the current slug.
+    await page.goto("/tools/1f2e3d4c5b6a47898abcdef012345678");
+    await expect(page).toHaveURL(/\/tools\/form-4$/);
+    await expect(
+      page.getByRole("heading", { name: "Form 4", level: 1 })
+    ).toBeVisible();
+
+    // Dashed, with the QR marker — the marker survives the redirect.
+    await page.goto(
+      "/tools/1f2e3d4c-5b6a-4789-8abc-def012345678?src=qr"
+    );
+    await expect(page).toHaveURL(/\/tools\/form-4\?src=qr$/);
+    await expect(
+      page.getByRole("heading", { name: "Form 4", level: 1 })
+    ).toBeVisible();
+  });
 });
diff --git a/v5/evals/fixtures.ts b/v5/evals/fixtures.ts
index 8b2d6a8..e23b84b 100644
--- a/v5/evals/fixtures.ts
+++ b/v5/evals/fixtures.ts
@@ -2,13 +2,16 @@ import { mockTools } from "@/components/mock-catalog";
 import type { MakerLabTool } from "@/components/catalog-types";
 
 /**
- * Eval fixtures (design spec §3). The eval suite runs with every `NOTION_*`
- * variable unset, so `getCatalogTools()` serves `src/components/mock-catalog.ts`
- * — a fixed, two-machine catalog. This module pins that same data into the
- * shape the assertions need, so an assertion can name exact values instead of
- * guessing what the live catalog happens to contain today.
+ * Eval fixtures (design spec §3). The eval suite runs with `DATABASE_URL`
+ * unset, so `getCatalogTools()` serves the PGlite demo seed — a fixed,
+ * two-machine catalog — and `run.eval.ts` builds the fixture from that same
+ * catalogue, so an assertion can name exact values and can never police a
+ * machine the model was not given.
  *
- * Everything here is pure data derived from the mock catalog plus two small
+ * {@link evalFixture} is the offline default the assertion unit tests use: the
+ * same two machines, pinned as literal data so those tests need no database.
+ *
+ * Everything here is pure data derived from a catalog plus two small
  * hand-maintained lists:
  *
  *  - {@link EXTRA_ALIASES} — other names a catalog machine legitimately goes by
@@ -198,7 +201,7 @@ function toFixtureTool(tool: MakerLabTool): EvalFixtureTool {
   };
 }
 
-/** Build the fixture from a catalog (defaults to the mock catalog). */
+/** Build the fixture from a catalog (defaults to the pinned two machines). */
 export function buildFixture(tools: MakerLabTool[] = mockTools): EvalFixture {
   const fixtureTools = tools.map(toFixtureTool);
 
@@ -213,5 +216,5 @@ export function buildFixture(tools: MakerLabTool[] = mockTools): EvalFixture {
   };
 }
 
-/** The fixture the runner uses: the mock catalog, pinned. */
+/** The offline fixture the assertion tests use: the two machines, pinned. */
 export const evalFixture: EvalFixture = buildFixture();
diff --git a/v5/evals/harness.test.ts b/v5/evals/harness.test.ts
index 35c60a5..0209dba 100644
--- a/v5/evals/harness.test.ts
+++ b/v5/evals/harness.test.ts
@@ -6,9 +6,11 @@ import { composeCase, stubWrites } from "./harness";
 
 vi.mock("next/cache", () => nextCacheMock());
 
-// Blank the Notion contract so the catalog is the mock catalog no matter what
-// the developer has in their shell — the same rail `npm run eval` applies.
+// Blank `DATABASE_URL` so the catalog is the demo seed, and the Notion contract
+// so no write path can reach Notion, no matter what the developer has in their
+// shell — the same rails `npm run eval` applies.
 beforeEach(() => {
+  vi.stubEnv("DATABASE_URL", "");
   for (const key of getNotionEnvContract()) vi.stubEnv(key, "");
 });
 
diff --git a/v5/evals/run.eval.ts b/v5/evals/run.eval.ts
index f732d01..d3bdaa9 100644
--- a/v5/evals/run.eval.ts
+++ b/v5/evals/run.eval.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { anthropic } from "@ai-sdk/anthropic";
 import { generateText, stepCountIs, type LanguageModel } from "ai";
-import { hasNotionCatalogEnv } from "@/lib/catalog";
+import { getCatalogTools, isDemoCatalog } from "@/lib/catalog";
 import {
   CHAT_MODEL_ID,
   GATEWAY_CHAT_MODEL_ID,
@@ -12,7 +12,7 @@ import {
 } from "@/lib/model";
 import { getNotionEnvContract } from "@/lib/notion";
 import { loadCases, type EvalCase } from "./cases";
-import { evalFixture } from "./fixtures";
+import { buildFixture } from "./fixtures";
 import { composeCase } from "./harness";
 import { formatReport, runSuite, type CaseExecution } from "./runner";
 
@@ -30,8 +30,9 @@ import { formatReport, runSuite, type CaseExecution } from "./runner";
  * eval that tested a reimplementation of the prompt would test nothing.
  *
  * Safety rails, in order:
- *  - every `NOTION_*` variable is blanked, so the catalog is the fixed mock
- *    catalog and no Notion request is possible;
+ *  - `DATABASE_URL` and every `NOTION_*` variable are blanked, so the catalog
+ *    is the fixed demo seed in an in-process PGlite database (spec §3.2) and
+ *    neither a real database nor Notion can be reached;
  *  - every `write` capability tool is stubbed, so an eval can never create a
  *    Notion record even if the model decides to call one;
  *  - the provider-native `web_search` / `web_fetch` tools the chat route adds
@@ -79,11 +80,13 @@ async function executeCase(evalCase: EvalCase): Promise<CaseExecution> {
 
 describe("agent evals", () => {
   beforeAll(() => {
-    // Blank the Notion contract so `getCatalogTools()` serves the mock catalog
-    // regardless of what the developer has in their shell.
+    // Blank `DATABASE_URL` so `getCatalogTools()` serves the demo seed, and the
+    // Notion contract so the write paths cannot reach Notion either, regardless
+    // of what the developer has in their shell.
+    vi.stubEnv("DATABASE_URL", "");
     for (const key of getNotionEnvContract()) vi.stubEnv(key, "");
-    if (hasNotionCatalogEnv()) {
-      throw new Error("refusing to run: the Notion environment is still configured");
+    if (!isDemoCatalog()) {
+      throw new Error("refusing to run: the catalog is a real database, not the demo seed");
     }
     if (!process.env.ANTHROPIC_API_KEY && !process.env.AI_GATEWAY_API_KEY) {
       throw new Error(
@@ -96,7 +99,11 @@ describe("agent evals", () => {
     const cases = loadCases();
     console.info(`Running ${cases.length} eval cases against ${MODEL_LABEL}…`);
 
-    const report = await runSuite(cases, executeCase, evalFixture, {
+    // Built from the catalogue the harness actually composes with, so an
+    // assertion can never police a machine or a manual the model was not given.
+    const fixture = buildFixture(await getCatalogTools());
+
+    const report = await runSuite(cases, executeCase, fixture, {
       onCase: (result) => console.info(`  ${result.status.toUpperCase()} ${result.id}`),
     });
 
diff --git a/v5/messages/en.json b/v5/messages/en.json
index 57d88c6..8429f3c 100644
--- a/v5/messages/en.json
+++ b/v5/messages/en.json
@@ -18,6 +18,8 @@
     "addSeed": "I'd like to add new equipment to the inventory.",
     "signIn": "SIGN IN",
     "signInAria": "Sign in with your {institution} account",
+    "signInUnconfigured": "Sign-in isn't set up on this deployment yet.",
+    "signInFailed": "Couldn't start sign-in. Try again.",
     "signOut": "SIGN OUT",
     "signedInAria": "Signed in as {name}"
   },
diff --git a/v5/next.config.ts b/v5/next.config.ts
index 7c730ce..0ba2390 100644
--- a/v5/next.config.ts
+++ b/v5/next.config.ts
@@ -5,11 +5,22 @@ const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");
 
 const nextConfig: NextConfig = {
   cacheComponents: true,
+  // PGlite ships its WASM build and its extension tarballs as files it locates
+  // with `import.meta.url`. Bundled into the server output those become
+  // `/_next/static/media/...` URLs that nothing can read from disk, so a build
+  // or a request without `DATABASE_URL` dies on "Extension bundle not found".
+  // Kept external, it loads from node_modules and the demo database works in a
+  // built app exactly as it does under `next dev` (spec §3.2).
+  serverExternalPackages: ["@electric-sql/pglite"],
   images: {
     localPatterns: [
       {
         pathname: "/tool-images/**",
       },
+      {
+        // Photos for the demo seed's sample project (src/lib/db/demo-seed.ts).
+        pathname: "/sample-projects/**",
+      },
       {
         pathname: "/makerlab-logo-transparent.png",
       },
@@ -18,6 +29,10 @@ const nextConfig: NextConfig = {
       },
     ],
     remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "*.public.blob.vercel-storage.com",
+      },
       {
         protocol: "https",
         hostname: "prod-files-secure.s3.us-west-2.amazonaws.com",
@@ -34,6 +49,9 @@ const nextConfig: NextConfig = {
         protocol: "https",
         hostname: "v5.airtableusercontent.com",
       },
+      // The Notion/S3/Airtable patterns above can go once every image has been
+      // re-imported to Vercel Blob; until then, rows imported before the switch
+      // may still reference them.
     ],
     minimumCacheTTL: 3600,
   },
diff --git a/v5/package.json b/v5/package.json
index 2fde6ec..8e7bd83 100644
--- a/v5/package.json
+++ b/v5/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "dev": "next dev",
-    "build": "next build",
+    "build": "npm run db:migrate && next build",
     "start": "next start",
     "lint": "eslint",
     "typecheck": "tsc --noEmit",
diff --git a/v5/playwright.config.ts b/v5/playwright.config.ts
index a2d2d11..d31f250 100644
--- a/v5/playwright.config.ts
+++ b/v5/playwright.config.ts
@@ -1,22 +1,35 @@
 import { defineConfig, devices } from "@playwright/test";
 
-// E2E runs against the app booted with NO Notion env vars, so getCatalogTools()
-// serves the built-in mock catalog (src/components/mock-catalog.ts). The
-// /api/chat call is intercepted at the network layer inside each spec via
+// E2E runs against a PRODUCTION build (`next build && next start`) booted with
+// no `DATABASE_URL` and no Notion env, so the catalogue is the in-process
+// PGlite database seeded with the two demo tools (src/lib/db/demo-seed.ts).
+// The /api/chat call is intercepted at the network layer inside each spec via
 // page.route(). No real external services are touched.
 //
+// Why not `next dev`: with parallel workers, the first request to each route
+// compiled it on demand and Turbopack rewrote the root layout's client chunk
+// while another worker was downloading it (ERR_CONTENT_LENGTH_MISMATCH), so
+// pages intermittently never hydrated (data platform spec 2026-09-14, Phase 2
+// amendment). A production server has no compiler in the loop, and it is the
+// same bundle a Vercel preview without a database runs.
+//
 // NOTE FOR THE E2E AGENT: run `npx playwright install chromium` once before the
 // first `npm run test:e2e` — the foundation harness does not install browsers.
 export default defineConfig({
   testDir: "./e2e",
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 1 : 0,
+  // One retry everywhere, not only in CI. With fourteen workers on a large
+  // machine a handful of interactions a few hundred milliseconds after a
+  // navigation still occasionally miss (about one test execution in a hundred
+  // as of Phase 2); a retry keeps the gate green and Playwright reports the
+  // test as "flaky" rather than hiding it, so the count stays visible.
+  retries: 1,
   reporter: process.env.CI ? "github" : "list",
   use: {
     // Dedicated test port (not 3000) so the suite never collides with — or
-    // accidentally reuses — a `next dev` you have running locally against real
-    // Notion. The webServer below always boots its own mock-backed instance.
+    // accidentally reuses — a `next dev` you have running locally against a
+    // real database. The webServer below always boots its own demo instance.
     baseURL: "http://localhost:3100",
     trace: "on-first-retry",
   },
@@ -27,17 +40,22 @@ export default defineConfig({
     },
   ],
   webServer: {
-    command: "npx next dev -p 3100",
+    // `npm run build` runs `db:migrate` first, which is a no-op with the
+    // blanked DATABASE_URL below, then `next build`.
+    command: "npm run build && npx next start -p 3100",
     url: "http://localhost:3100",
-    // Always boot a fresh mock-backed server; never reuse whatever is on the
+    // Always boot a fresh demo-backed server; never reuse whatever is on the
     // port. Keeps E2E deterministic regardless of the local dev environment.
     reuseExistingServer: false,
-    timeout: 120_000,
-    // Unset Notion env so the app serves the mock catalog. Spreading
-    // process.env first, then overwriting with "" makes hasNotionCatalogEnv()
-    // return false regardless of the dev shell's environment.
+    // The build is most of this budget; `next start` itself is seconds.
+    timeout: 300_000,
+    // Blank `DATABASE_URL` so the catalogue is the demo seed, and the Notion
+    // env so no write path can reach Notion. Spreading process.env first, then
+    // overwriting with "" wins over both the dev shell and `.env.local`, which
+    // Next will not override for a key that is already present.
     env: {
       ...process.env,
+      DATABASE_URL: "",
       NOTION_API_KEY: "",
       NOTION_DB_TOOLS: "",
       NOTION_DB_CATEGORIES: "",
diff --git a/v5/public/sample-projects/laser-cut-lamp-lit.png b/v5/public/sample-projects/laser-cut-lamp-lit.png
new file mode 100644
index 0000000..9896bfb
Binary files /dev/null and b/v5/public/sample-projects/laser-cut-lamp-lit.png differ
diff --git a/v5/public/sample-projects/laser-cut-lamp-parts.png b/v5/public/sample-projects/laser-cut-lamp-parts.png
new file mode 100644
index 0000000..b70a263
Binary files /dev/null and b/v5/public/sample-projects/laser-cut-lamp-parts.png differ
diff --git a/v5/scripts/generate-qr-labels.test.ts b/v5/scripts/generate-qr-labels.test.ts
index f056c6d..dc32e93 100644
--- a/v5/scripts/generate-qr-labels.test.ts
+++ b/v5/scripts/generate-qr-labels.test.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 import { resolve } from "node:path";
 import {
   buildLabelSheet,
@@ -5,6 +6,7 @@ import {
   deriveLabels,
   formatLabelLocation,
   loadSheetStrings,
+  loadSources,
   MIN_QR_MM,
   parseArgs,
   pickSheetStrings,
@@ -13,7 +15,6 @@ import {
   type LabelSheetStrings,
   type QrLabelSource,
 } from "./generate-qr-labels.ts";
-import { mockTools } from "@/components/mock-catalog";
 import enMessages from "../messages/en.json";
 
 const MESSAGES_DIR = resolve(process.cwd(), "messages");
@@ -173,27 +174,31 @@ describe("renderLabelSheet", () => {
   });
 });
 
-describe("buildLabelSheet (integration, mock catalog)", () => {
-  it("produces one label per tool in the mock catalog", async () => {
-    const html = await buildLabelSheet(mockTools, {
+// The whole script, end to end, over the catalogue it reads in production —
+// the demo seed standing in for a real database (spec §3.2).
+describe("buildLabelSheet (integration, demo catalogue)", () => {
+  it("produces one label per tool in the catalogue", async () => {
+    const sources = await loadSources();
+    const html = await buildLabelSheet(sources, {
       baseUrl: BASE,
       strings: STRINGS,
       encodeQr: fakeEncoder,
     });
 
     const labels = html.match(/class="qr-label"/g) || [];
-    expect(labels).toHaveLength(mockTools.length);
-    expect(mockTools.length).toBeGreaterThan(0);
+    expect(labels).toHaveLength(sources.length);
+    expect(sources.length).toBeGreaterThan(0);
   });
 
   it("encodes each tool's own ?src=qr URL and prints its name", async () => {
-    const html = await buildLabelSheet(mockTools, {
+    const sources = await loadSources();
+    const html = await buildLabelSheet(sources, {
       baseUrl: BASE,
       strings: STRINGS,
       encodeQr: fakeEncoder,
     });
 
-    for (const tool of mockTools) {
+    for (const tool of sources) {
       expect(html).toContain(`${BASE}/tools/${tool.slug}?src=qr`);
       expect(html).toContain(tool.name);
     }
@@ -201,8 +206,9 @@ describe("buildLabelSheet (integration, mock catalog)", () => {
   });
 
   it("drops unpublished tools from the sheet", async () => {
+    const sources = await loadSources();
     const html = await buildLabelSheet(
-      [...mockTools.map((tool) => ({ ...tool, published: false })), source()],
+      [...sources.map((tool) => ({ ...tool, published: false })), source()],
       { baseUrl: BASE, strings: STRINGS, encodeQr: fakeEncoder }
     );
 
@@ -211,6 +217,26 @@ describe("buildLabelSheet (integration, mock catalog)", () => {
   });
 });
 
+describe("loadSources (Postgres, PGlite demo seed)", () => {
+  it("reads published, non-archived tools ordered by name", async () => {
+    const sources = await loadSources();
+
+    expect(sources.map((source) => source.slug)).toEqual(["form-4", "trotec-speedy-400"]);
+    expect(sources.every((source) => source.published)).toBe(true);
+
+    const form4 = sources.find((source) => source.slug === "form-4");
+    expect(form4).toMatchObject({ name: "Form 4", location: "MakerLab", zone: "Resin Bench" });
+  });
+
+  it("produces working label URLs end to end from Postgres", async () => {
+    const sources = await loadSources();
+    expect(deriveLabels(sources, BASE).map((label) => label.url)).toEqual([
+      "https://tools.example.edu/tools/form-4?src=qr",
+      "https://tools.example.edu/tools/trotec-speedy-400?src=qr",
+    ]);
+  });
+});
+
 describe("sheet strings", () => {
   it("picks the qr namespace out of a locale catalog", () => {
     const strings = pickSheetStrings(enMessages);
diff --git a/v5/scripts/generate-qr-labels.ts b/v5/scripts/generate-qr-labels.ts
index bcbdcb5..5d31c21 100644
--- a/v5/scripts/generate-qr-labels.ts
+++ b/v5/scripts/generate-qr-labels.ts
@@ -15,11 +15,15 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { and, asc, eq, isNull } from "drizzle-orm";
 import { getDirection, isSupportedLocale, DEFAULT_LOCALE } from "../src/i18n/config.ts";
+import { getDb } from "../src/lib/db/client.ts";
+import { locations, tools } from "../src/lib/db/schema/index.ts";
 
 /**
  * The minimum a label needs: something to route to, something to print. Both
- * the resolved catalog (`MakerLabTool`) and raw Notion metadata satisfy it.
+ * the resolved catalog (`MakerLabTool`) and a raw Postgres `tools` row (joined
+ * to its location) satisfy it.
  */
 export interface QrLabelSource {
   id: string;
@@ -338,34 +342,37 @@ export function parseArgs(argv: string[]): CliOptions {
 }
 
 /**
- * Catalog source. With Notion configured we read the published Tools DB
- * directly — `src/lib/catalog.ts` caches through `next/cache`, which only
- * works inside a Next runtime. Without credentials we fall back to the mock
- * catalog, so staff can dry-run the layout before wiring anything up.
+ * Catalog source: published, non-archived tools straight from Postgres
+ * (spec §3.10 — old labels still resolve because `notion_page_id` isn't
+ * touched here, and new ones are printed from `slug`). `getDb()` resolves to
+ * the PGlite demo seed when `DATABASE_URL` is unset, so staff can dry-run the
+ * layout before a real database is wired up.
  */
-async function loadSources(): Promise<QrLabelSource[]> {
-  const { getNotionEnvContract, fetchAllTools, fetchAllLocations, resolveTools } =
-    await import("../src/lib/notion.ts");
-
-  if (!getNotionEnvContract().every((key) => Boolean(process.env[key]))) {
-    console.warn("Notion env not configured — generating labels from the mock catalog.");
-    const { mockTools } = await import("../src/components/mock-catalog.ts");
-    return mockTools;
-  }
-
-  const [tools, locations] = await Promise.all([fetchAllTools(), fetchAllLocations()]);
-  // `fetchAllTools` already filters to published records; keep the flag so
-  // `deriveLabels` stays the single place that decides.
-  const publishedById = new Map(tools.map((tool) => [tool.id, tool.fields.published]));
-
-  return resolveTools(tools, [], locations).map((tool) => ({
-    id: tool.id,
-    // Notion-backed tool pages route by page id (catalog.ts sets slug = id).
-    slug: tool.id,
-    name: tool.name,
-    location: tool.location_room,
-    zone: tool.location_zone,
-    published: publishedById.get(tool.id),
+export async function loadSources(): Promise<QrLabelSource[]> {
+  const db = await getDb();
+
+  const rows = await db
+    .select({
+      id: tools.id,
+      slug: tools.slug,
+      name: tools.name,
+      room: locations.room,
+      zone: locations.zone,
+    })
+    .from(tools)
+    .leftJoin(locations, eq(tools.locationId, locations.id))
+    .where(and(eq(tools.published, true), isNull(tools.archivedAt)))
+    .orderBy(asc(tools.name));
+
+  return rows.map((row) => ({
+    id: row.id,
+    slug: row.slug,
+    name: row.name,
+    location: row.room,
+    zone: row.zone,
+    // The query already filters to published tools; the flag stays true so
+    // `deriveLabels` remains the single place that decides.
+    published: true,
   }));
 }
 
diff --git a/v5/src/app/api/chat/rate-limit.route.test.ts b/v5/src/app/api/chat/rate-limit.route.test.ts
index 3f1bc50..5266036 100644
--- a/v5/src/app/api/chat/rate-limit.route.test.ts
+++ b/v5/src/app/api/chat/rate-limit.route.test.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 /**
  * `/api/chat` at and over the tiered ceiling (auth design spec §8, §10).
  *
@@ -6,13 +7,15 @@
  * an anonymous visitor and a signed-in student hitting the same endpoint from
  * the same IP get different allowances, and the refusal offers a way forward.
  *
- * The model is still stubbed at the `streamText` boundary — no network (Art. 3).
+ * The model is still stubbed at the `streamText` boundary, and the catalogue
+ * comes from the demo-seeded PGlite database — no network (Art. 3).
  */
 import {
   SESSION_COOKIE_NAME,
   createSessionPayload,
   signSession,
 } from "@/lib/auth/session-cookie";
+import { resetDbForTests } from "@/lib/db/client";
 
 const AUTH_SECRET = "chat-ceiling-test-secret";
 
@@ -42,19 +45,9 @@ vi.mock("ai", async (importOriginal) => {
   };
 });
 
-// Notion is never reached (NOTION_* unset → mock catalog), but catalog.ts
-// imports it, so stub the module surface it uses.
-vi.mock("@/lib/notion", () => ({
-  fetchMaintenanceLogsByUnit: vi.fn(async () => []),
-  createMaintenanceLog: vi.fn(),
-  fetchAllResources: vi.fn(async () => []),
-  getNotionEnvContract: () => ["NOTION_API_KEY"],
-  fetchAllTools: vi.fn(async () => []),
-  fetchAllCategories: vi.fn(async () => []),
-  fetchAllLocations: vi.fn(async () => []),
-  fetchAllUnits: vi.fn(async () => []),
-  resolveTools: vi.fn(() => []),
-}));
+// Notion is not stubbed here: no request path in this suite reaches it. The
+// catalogue reads Postgres, and the one Notion write left in the capability
+// layer (`report_issue`, spec Phase 3) is never called from a ceiling test.
 
 vi.mock("next/cache", () => ({
   cacheTag: vi.fn(),
@@ -97,6 +90,11 @@ function chatRequest({ ip, cookie }: { ip: string; cookie?: string }): Request {
 
 beforeEach(() => {
   vi.stubEnv("AUTH_SECRET", AUTH_SECRET);
+  vi.stubEnv("DATABASE_URL", "");
+});
+
+afterAll(() => {
+  resetDbForTests();
 });
 
 describe("POST /api/chat — anonymous ceiling", () => {
diff --git a/v5/src/app/api/chat/route.test.ts b/v5/src/app/api/chat/route.test.ts
index d56e5c1..1c0a0c3 100644
--- a/v5/src/app/api/chat/route.test.ts
+++ b/v5/src/app/api/chat/route.test.ts
@@ -1,7 +1,7 @@
+// @vitest-environment node
 /* eslint-disable @typescript-eslint/no-explicit-any -- this suite inspects the
    loosely-typed { system, messages, tools } object captured from the mocked
    streamText call; precise typing here would add noise without value. */
-import type { MaintenanceLogRecord, ResourceRecord } from "@/lib/types";
 
 // ── Captured streamText args ─────────────────────────────────────────
 // streamText is mocked so we can inspect the { system, messages, tools }
@@ -46,16 +46,9 @@ vi.mock("ai", async (importOriginal) => {
 const mocks = vi.hoisted(() => ({
   rateLimitAsync: vi.fn(),
   checkRateLimit: vi.fn(),
-  fetchMaintenanceLogsByUnit: vi.fn(),
   createMaintenanceLog: vi.fn(),
-  fetchAllResources: vi.fn(),
 }));
-const {
-  checkRateLimit,
-  fetchMaintenanceLogsByUnit,
-  createMaintenanceLog,
-  fetchAllResources,
-} = mocks;
+const { checkRateLimit, createMaintenanceLog } = mocks;
 
 // ── Mock the rate limiter (default: allowed, set in beforeEach) ──────
 // The route calls the identity-keyed `checkRateLimit`; the rest of the module
@@ -71,29 +64,14 @@ vi.mock("@/lib/rate-limit", async (importOriginal) => {
   };
 });
 
-// ── Mock Notion calls used by the route's tools / manual collection ──
-vi.mock("@/lib/notion", () => ({
-  fetchMaintenanceLogsByUnit: mocks.fetchMaintenanceLogsByUnit,
-  createMaintenanceLog: mocks.createMaintenanceLog,
-  fetchAllResources: mocks.fetchAllResources,
-  // catalog.ts also imports from notion.ts, but with NOTION_* env unset the
-  // catalog uses the mock fallback and never touches these, so stub the rest.
-  getNotionEnvContract: () => [
-    "NOTION_API_KEY",
-    "NOTION_DB_TOOLS",
-    "NOTION_DB_CATEGORIES",
-    "NOTION_DB_LOCATIONS",
-    "NOTION_DB_UNITS",
-    "NOTION_DB_RESOURCES",
-    "NOTION_DB_MAINTENANCE_LOGS",
-    "NOTION_DB_FLAGS",
-  ],
-  fetchAllTools: vi.fn(async () => []),
-  fetchAllCategories: vi.fn(async () => []),
-  fetchAllLocations: vi.fn(async () => []),
-  fetchAllUnits: vi.fn(async () => []),
-  resolveTools: vi.fn(() => []),
-}));
+// ── Mock the one Notion call left in the route's tools ───────────────
+// `report_issue` still files its ticket in Notion (spec §9, Phase 3). Every
+// other export stays real: nothing else in this request path reads Notion, and
+// a full replacement would have to track every import in the capability layer.
+vi.mock("@/lib/notion", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@/lib/notion")>();
+  return { ...actual, createMaintenanceLog: mocks.createMaintenanceLog };
+});
 
 // next/cache is imported by catalog.ts ("use cache" / cacheTag / cacheLife).
 vi.mock("next/cache", () => ({
@@ -102,29 +80,75 @@ vi.mock("next/cache", () => ({
   revalidateTag: vi.fn(),
 }));
 
+import { eq, inArray } from "drizzle-orm";
 import { POST } from "@/app/api/chat/route";
+import { getDb, resetDbForTests } from "@/lib/db/client";
+import { DEMO_FORM_4_UNIT_NOTION_PAGE_ID } from "@/lib/db/demo-seed";
+import {
+  attachments,
+  maintenanceLogs,
+  resources,
+  tools as toolsTable,
+  units,
+} from "@/lib/db/schema/index";
 import {
   SESSION_COOKIE_NAME,
   createSessionPayload,
   signSession,
 } from "@/lib/auth/session-cookie";
 
-// A mock-catalog resource fixture builder (mirrors ResourceRecord shape).
-function resource(
-  partial: Partial<ResourceRecord["fields"]> & { id?: string }
-): ResourceRecord {
-  const { id = "res-1", ...fields } = partial;
-  return {
-    id,
-    createdTime: "2024-01-01T00:00:00.000Z",
-    lastEditedTime: "2024-01-01T00:00:00.000Z",
-    fields: {
-      title: "Manual",
-      tool: ["tool-form-4"],
-      published: true,
-      ...fields,
-    },
-  } as ResourceRecord;
+/**
+ * The catalogue, the units and the resources all come from the demo-seeded
+ * PGlite database `getDb()` hands out with `DATABASE_URL` unset — the two
+ * tools `Form 4` (unit `Form 4 // A`) and `Trotec Speedy 400`. The seed carries
+ * no maintenance logs and no PDF resources; the tests that need them write
+ * them and clean up after themselves.
+ */
+
+/** Resource rows this file inserted, removed after each test. */
+const insertedResourceIds: string[] = [];
+
+async function toolId(slug: string): Promise<string> {
+  const db = await getDb();
+  const [row] = await db
+    .select({ id: toolsTable.id })
+    .from(toolsTable)
+    .where(eq(toolsTable.slug, slug));
+  return row.id;
+}
+
+async function unitId(label: string): Promise<string> {
+  const db = await getDb();
+  const [row] = await db
+    .select({ id: units.id })
+    .from(units)
+    .where(eq(units.unitLabel, label));
+  return row.id;
+}
+
+/** Add resources to a seeded tool (default: the Form 4). */
+async function addResources(
+  rows: Array<{ title: string; url?: string | null; published?: boolean; slug?: string }>
+): Promise<void> {
+  const db = await getDb();
+  const values = await Promise.all(
+    rows.map(async ({ slug = "form-4", ...row }) => ({
+      toolId: await toolId(slug),
+      type: "Manual",
+      ...row,
+    }))
+  );
+  const created = await db.insert(resources).values(values).returning({ id: resources.id });
+  insertedResourceIds.push(...created.map((row) => row.id));
+}
+
+async function addMaintenanceLogs(
+  label: string,
+  rows: Array<Partial<typeof maintenanceLogs.$inferInsert>>
+): Promise<void> {
+  const db = await getDb();
+  const id = await unitId(label);
+  await db.insert(maintenanceLogs).values(rows.map((row) => ({ title: "Issue", unitId: id, ...row })));
 }
 
 function chatRequest(
@@ -150,6 +174,7 @@ const userMessage = (text: string) => ({
 
 beforeEach(() => {
   captured.args = undefined;
+  vi.stubEnv("DATABASE_URL", "");
   // Undo any `vi.stubGlobal("fetch", …)` from a prior PDF test (the shared
   // setup file does not call vi.unstubAllGlobals).
   vi.unstubAllGlobals();
@@ -161,13 +186,25 @@ beforeEach(() => {
     retryAfterSeconds: 3600,
     role: "student",
   });
-  fetchMaintenanceLogsByUnit.mockReset();
-  fetchMaintenanceLogsByUnit.mockResolvedValue([]);
-  fetchAllResources.mockReset();
-  fetchAllResources.mockResolvedValue([]);
   createMaintenanceLog.mockReset();
 });
 
+afterEach(async () => {
+  const db = await getDb();
+  await db.delete(maintenanceLogs);
+  // The seed carries no attachments, so clearing the table only drops what a
+  // test wrote.
+  await db.delete(attachments);
+  if (insertedResourceIds.length > 0) {
+    await db.delete(resources).where(inArray(resources.id, insertedResourceIds));
+    insertedResourceIds.length = 0;
+  }
+});
+
+afterAll(() => {
+  resetDbForTests();
+});
+
 describe("POST /api/chat — rate limiting", () => {
   it("returns 429 with Retry-After and never calls streamText when denied", async () => {
     checkRateLimit.mockResolvedValueOnce({
@@ -248,7 +285,7 @@ describe("get_unit_details.execute", () => {
       unit_label: "no-such-unit",
     });
     expect(result.found).toBe(false);
-    // Sample list drawn from the mock catalog's units.
+    // Sample list drawn from the seeded catalogue's units.
     expect(result.message).toMatch(/Form 4 \/\/ A|Trotec Speedy 400/);
   });
 
@@ -265,21 +302,18 @@ describe("get_unit_details.execute", () => {
     expect(result.maintenance_logs).toEqual([]);
   });
 
-  it("surfaces maintenance logs, sliced to 10", async () => {
-    const logs: MaintenanceLogRecord[] = Array.from({ length: 12 }, (_, i) => ({
-      id: `log-${i}`,
-      createdTime: "2024-01-01T00:00:00.000Z",
-      lastEditedTime: "2024-01-01T00:00:00.000Z",
-      fields: {
+  it("surfaces maintenance logs, capped at 10 and newest first", async () => {
+    await addMaintenanceLogs(
+      "Form 4 // A",
+      Array.from({ length: 12 }, (_, i) => ({
         title: `Issue ${i}`,
-        type: "Issue Report",
-        priority: "Medium",
-        status: "Open",
-        date_reported: "2024-09-01",
+        type: "issue_report",
+        priority: "medium",
+        status: "open",
         description: `desc ${i}`,
-      },
-    })) as MaintenanceLogRecord[];
-    fetchMaintenanceLogsByUnit.mockResolvedValueOnce(logs);
+        dateReported: `2024-09-${String(i + 1).padStart(2, "0")}`,
+      }))
+    );
 
     const tools = await getTools();
     const result = await tools.get_unit_details.execute({
@@ -288,8 +322,9 @@ describe("get_unit_details.execute", () => {
 
     expect(result.found).toBe(true);
     expect(result.maintenance_logs).toHaveLength(10);
+    // Stored snake_case, shown in the words the assistant has always seen.
     expect(result.maintenance_logs[0]).toMatchObject({
-      title: "Issue 0",
+      title: "Issue 11",
       type: "Issue Report",
       priority: "Medium",
       status: "Open",
@@ -346,13 +381,14 @@ describe("report_issue.execute", () => {
       priority: "High",
     });
 
+    // The caller is told the Postgres uuid the catalogue resolved; the ticket,
+    // still filed in Notion, carries the unit's imported Notion page id — the
+    // only id that database's `unit` relation can address.
+    const form4A = await unitId("Form 4 // A");
     expect(result.success).toBe(true);
-    expect(result.unit_resolved).toEqual({
-      id: "unit-form-4-a",
-      label: "Form 4 // A",
-    });
+    expect(result.unit_resolved).toEqual({ id: form4A, label: "Form 4 // A" });
     expect(createMaintenanceLog).toHaveBeenCalledWith(
-      expect.objectContaining({ unit: ["unit-form-4-a"] })
+      expect.objectContaining({ unit: [DEMO_FORM_4_UNIT_NOTION_PAGE_ID] })
     );
   });
 
@@ -451,11 +487,11 @@ describe("PDF manual collection (focused tool)", () => {
   }
 
   it("attaches small PDFs to the first user message and caps at 3", async () => {
-    fetchAllResources.mockResolvedValueOnce([
-      resource({ id: "r1", title: "Manual 1", url: "https://x.test/m1.pdf" }),
-      resource({ id: "r2", title: "Manual 2", url: "https://x.test/m2.pdf" }),
-      resource({ id: "r3", title: "Manual 3", url: "https://x.test/m3.pdf" }),
-      resource({ id: "r4", title: "Manual 4", url: "https://x.test/m4.pdf" }),
+    await addResources([
+      { title: "Manual 1", url: "https://x.test/m1.pdf" },
+      { title: "Manual 2", url: "https://x.test/m2.pdf" },
+      { title: "Manual 3", url: "https://x.test/m3.pdf" },
+      { title: "Manual 4", url: "https://x.test/m4.pdf" },
     ]);
 
     const fetchMock = vi.fn(async () => okPdf(PDF_SMALL));
@@ -482,12 +518,12 @@ describe("PDF manual collection (focused tool)", () => {
   });
 
   it("skips PDFs that are too large or return non-ok, and skips non-PDF resources", async () => {
-    fetchAllResources.mockResolvedValueOnce([
-      resource({ id: "r1", title: "Good", url: "https://x.test/good.pdf" }),
-      resource({ id: "r2", title: "Huge", url: "https://x.test/huge.pdf" }),
-      resource({ id: "r3", title: "Dead", url: "https://x.test/dead.pdf" }),
+    await addResources([
+      { title: "Good", url: "https://x.test/good.pdf" },
+      { title: "Huge", url: "https://x.test/huge.pdf" },
+      { title: "Dead", url: "https://x.test/dead.pdf" },
       // Non-PDF url → skipped entirely (never fetched).
-      resource({ id: "r4", title: "Webpage", url: "https://x.test/page.html" }),
+      { title: "Webpage", url: "https://x.test/page.html" },
     ]);
 
     const fetchMock = vi.fn(async (url: string) => {
@@ -525,19 +561,9 @@ describe("PDF manual collection (focused tool)", () => {
   });
 
   it("ignores unpublished resources and resources for other tools", async () => {
-    fetchAllResources.mockResolvedValueOnce([
-      resource({
-        id: "r1",
-        title: "Unpublished",
-        url: "https://x.test/u.pdf",
-        published: false,
-      }),
-      resource({
-        id: "r2",
-        title: "OtherTool",
-        url: "https://x.test/o.pdf",
-        tool: ["tool-trotec-speedy-400"],
-      }),
+    await addResources([
+      { title: "Unpublished", url: "https://x.test/u.pdf", published: false },
+      { title: "OtherTool", url: "https://x.test/o.pdf", slug: "trotec-speedy-400" },
     ]);
     const fetchMock = vi.fn(async () => okPdf(PDF_SMALL));
     vi.stubGlobal("fetch", fetchMock);
@@ -550,16 +576,43 @@ describe("PDF manual collection (focused tool)", () => {
     expect(captured.args.system).not.toContain("Available manuals");
   });
 
+  it("attaches a resource's uploaded file when the resource itself has no url", async () => {
+    await addResources([{ title: "Scanned manual", url: null }]);
+    const db = await getDb();
+    const [scanned] = await db
+      .select({ id: resources.id })
+      .from(resources)
+      .where(eq(resources.title, "Scanned manual"));
+    await db.insert(attachments).values({
+      ownerType: "resource",
+      ownerId: scanned.id,
+      blobPathname: "resources/scanned-abc123.pdf",
+      access: "public",
+      publicUrl: "https://blob.test/resources/scanned-abc123.pdf",
+    });
+
+    const fetchMock = vi.fn(async () => okPdf(PDF_SMALL));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await POST(
+      chatRequest({ messages: [userMessage("help")], toolId: "form-4" })
+    );
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://blob.test/resources/scanned-abc123.pdf",
+      expect.anything()
+    );
+    expect(captured.args.system).toContain("Scanned manual");
+  });
+
   it("does not run manual collection when no toolId is provided", async () => {
-    fetchAllResources.mockResolvedValueOnce([
-      resource({ id: "r1", title: "Manual 1", url: "https://x.test/m1.pdf" }),
-    ]);
+    await addResources([{ title: "Manual 1", url: "https://x.test/m1.pdf" }]);
     const fetchMock = vi.fn(async () => okPdf(PDF_SMALL));
     vi.stubGlobal("fetch", fetchMock);
 
     await POST(chatRequest({ messages: [userMessage("hi")] }));
 
-    expect(fetchAllResources).not.toHaveBeenCalled();
     expect(fetchMock).not.toHaveBeenCalled();
+    expect(captured.args.system).not.toContain("Available manuals");
   });
 });
diff --git a/v5/src/app/api/chat/route.ts b/v5/src/app/api/chat/route.ts
index 67f741d..0c983c6 100644
--- a/v5/src/app/api/chat/route.ts
+++ b/v5/src/app/api/chat/route.ts
@@ -13,9 +13,11 @@ import {
   type UserModelMessage,
 } from "ai";
 import { getCatalogTool, getCatalogTools } from "../../../lib/catalog";
-import { fetchAllResources } from "../../../lib/notion";
+import {
+  listResourcesForTool,
+  type ToolResource,
+} from "../../../lib/data/resources";
 import type { MakerLabTool } from "../../../components/catalog-types";
-import type { ResourceRecord } from "../../../lib/types";
 import { checkRateLimit, type RateLimitDecision } from "../../../lib/rate-limit";
 import { resolveIdentity } from "../../../lib/auth/identity";
 import { siteConfig } from "../../../lib/site-config";
@@ -50,7 +52,7 @@ interface ChatRequest {
 
 export async function POST(req: Request) {
   // Who is asking, then how much they are allowed — both before any expensive
-  // work (Notion fetch / model call). Anonymous visitors get a small allowance
+  // work (catalogue read / model call). Anonymous visitors get a small allowance
   // keyed by hashed IP; signed-in callers get a generous one keyed by user id
   // (auth design spec §8).
   const identity = await resolveIdentity(req);
@@ -372,18 +374,15 @@ function uniqueHosts(urls: string[]): string[] {
   return [...set];
 }
 
-function isPdfUrl(url: string | undefined): boolean {
+function isPdfUrl(url: string | null | undefined): boolean {
   if (!url) return false;
   const cleaned = url.split("?")[0].toLowerCase();
   return cleaned.endsWith(".pdf");
 }
 
-function pickPdfUrl(resource: ResourceRecord): string | null {
-  if (isPdfUrl(resource.fields.url)) return resource.fields.url ?? null;
-  const file = (resource.fields.files || []).find(
-    (f) => isPdfUrl(f.filename) || isPdfUrl(f.url)
-  );
-  return file?.url || null;
+function pickPdfUrl(resource: ToolResource): string | null {
+  if (isPdfUrl(resource.url)) return resource.url;
+  return resource.fileUrls.find(isPdfUrl) ?? null;
 }
 
 /**
@@ -429,38 +428,35 @@ async function fetchPdfAsBase64(
 async function collectToolManuals(
   toolId: string
 ): Promise<{ manuals: AttachedManual[]; skipped: number }> {
-  let resources: ResourceRecord[];
+  // Only the focused tool's resources are read (spec §3.10, Article 4's "load
+  // context lazily") — the whole resource table used to come back from Notion
+  // just to be filtered down to one tool's rows here.
+  let forTool: ToolResource[];
   try {
-    resources = await fetchAllResources();
+    forTool = await listResourcesForTool(toolId);
   } catch (err) {
     console.warn("[chat] failed to load resources for manuals", err);
     return { manuals: [], skipped: 0 };
   }
 
-  const forTool = resources.filter(
-    (r) => r.fields.published !== false && (r.fields.tool || []).includes(toolId)
-  );
-
   const manuals: AttachedManual[] = [];
   let skipped = 0;
   try {
     for (const r of forTool) {
       const url = pickPdfUrl(r);
       if (!url) {
-        if (r.fields.url) {
-          console.info(
-            `[chat] skipping non-PDF resource: ${r.fields.title} (${r.fields.url})`
-          );
+        if (r.url) {
+          console.info(`[chat] skipping non-PDF resource: ${r.title} (${r.url})`);
         }
         continue;
       }
       if (manuals.length >= MAX_PDFS_PER_CHAT) {
         console.info(
-          `[chat] PDF cap reached (${MAX_PDFS_PER_CHAT}); skipping: ${r.fields.title}`
+          `[chat] PDF cap reached (${MAX_PDFS_PER_CHAT}); skipping: ${r.title}`
         );
         continue;
       }
-      const title = r.fields.title || "Manual";
+      const title = r.title || "Manual";
       const data = await fetchPdfAsBase64(title, url);
       if (!data) {
         skipped += 1;
diff --git a/v5/src/app/api/flags/route.test.ts b/v5/src/app/api/flags/route.test.ts
index fddc1b0..4ce6754 100644
--- a/v5/src/app/api/flags/route.test.ts
+++ b/v5/src/app/api/flags/route.test.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 import { http, HttpResponse } from "msw";
 import { server } from "../../../../test/msw/server";
 import { DB_IDS } from "../../../../test/msw/handlers";
@@ -6,10 +7,27 @@ import { nextCacheMock } from "../../../../test/mocks/next-cache";
 // The route reaches the catalog (for tool resolution) which imports next/cache.
 vi.mock("next/cache", () => nextCacheMock());
 
+import { getCatalogTools } from "@/lib/catalog";
+import { resetDbForTests } from "@/lib/db/client";
+import { DEMO_FORM_4_NOTION_PAGE_ID } from "@/lib/db/demo-seed";
 import { POST } from "./route";
 
 const NOTION = "https://api.notion.com/v1";
-const FORM_4_ID = "tool-form-4";
+
+// The route resolves the flagged tool against the demo-seeded PGlite database
+// (`DATABASE_URL` unset). Its id is a Postgres uuid minted at seed time, so it
+// is looked up rather than hard-coded.
+let FORM_4_ID = "";
+
+beforeEach(async () => {
+  vi.stubEnv("DATABASE_URL", "");
+  const tools = await getCatalogTools();
+  FORM_4_ID = tools.find((tool) => tool.slug === "form-4")?.id ?? "";
+});
+
+afterAll(() => {
+  resetDbForTests();
+});
 
 // The in-memory limiter is a per-process singleton keyed by IP, so each test
 // gets its own IP to avoid bleeding a spent window into the next one.
@@ -79,6 +97,8 @@ describe("POST /api/flags", () => {
     expect(creates[0].properties).toMatchObject({
       status: { select: { name: "New" } },
       field_flagged: { select: { name: "location" } },
+      // The relation addresses the tool's Notion page, not its Postgres id.
+      tool: { relation: [{ id: DEMO_FORM_4_NOTION_PAGE_ID }] },
     });
   });
 
diff --git a/v5/src/app/api/health/route.test.ts b/v5/src/app/api/health/route.test.ts
index 1d367d0..ef6bb9b 100644
--- a/v5/src/app/api/health/route.test.ts
+++ b/v5/src/app/api/health/route.test.ts
@@ -1,40 +1,18 @@
-import { http, HttpResponse } from "msw";
-
-import { server } from "../../../../test/msw/server";
-import { DB_IDS } from "../../../../test/msw/handlers";
+// @vitest-environment node
+// `nextCacheMock` is imported first on purpose: `vi.mock` is hoisted above
+// every import, and its factory can only reach a module imported before the
+// one it replaces.
 import { nextCacheMock } from "../../../../test/mocks/next-cache";
 
 vi.mock("next/cache", () => nextCacheMock());
 
 import { cacheLife } from "next/cache";
-import { mockTools } from "../../../components/mock-catalog";
 import { HEALTH_CACHE } from "../../../lib/cache";
+import { resetDbForTests } from "../../../lib/db/client";
 import { GET } from "./route";
 
 // ── Helpers ─────────────────────────────────────────────────────────
 
-function stubNotionEnv() {
-  vi.stubEnv("NOTION_API_KEY", "secret_test");
-  vi.stubEnv("NOTION_DB_TOOLS", DB_IDS.tools);
-  vi.stubEnv("NOTION_DB_CATEGORIES", DB_IDS.categories);
-  vi.stubEnv("NOTION_DB_LOCATIONS", DB_IDS.locations);
-  vi.stubEnv("NOTION_DB_UNITS", DB_IDS.units);
-  vi.stubEnv("NOTION_DB_RESOURCES", DB_IDS.resources);
-  vi.stubEnv("NOTION_DB_MAINTENANCE_LOGS", DB_IDS.maintenance_logs);
-  vi.stubEnv("NOTION_DB_FLAGS", DB_IDS.flags);
-}
-
-function unsetNotionEnv() {
-  vi.stubEnv("NOTION_API_KEY", "");
-  vi.stubEnv("NOTION_DB_TOOLS", "");
-  vi.stubEnv("NOTION_DB_CATEGORIES", "");
-  vi.stubEnv("NOTION_DB_LOCATIONS", "");
-  vi.stubEnv("NOTION_DB_UNITS", "");
-  vi.stubEnv("NOTION_DB_RESOURCES", "");
-  vi.stubEnv("NOTION_DB_MAINTENANCE_LOGS", "");
-  vi.stubEnv("NOTION_DB_FLAGS", "");
-}
-
 // The in-memory limiter is a per-process singleton keyed by IP, so every test
 // gets its own address rather than eating a shared window.
 let ipCounter = 0;
@@ -45,196 +23,130 @@ function makeRequest(ip = `10.0.0.${++ipCounter}`) {
 }
 
 beforeEach(() => {
-  // The degraded paths log the real reason server-side; keep it out of the
+  // Force the demo substrate regardless of the host shell's own env, matching
+  // the rest of the catalogue test suite (see src/lib/catalog.test.ts).
+  vi.stubEnv("DATABASE_URL", "");
+  // The degraded path logs the real reason server-side; keep it out of the
   // test output (and prove nothing about it reaches the response body below).
   vi.spyOn(console, "warn").mockImplementation(() => {});
 });
 
-// ── Healthy ─────────────────────────────────────────────────────────
+afterEach(() => {
+  resetDbForTests();
+});
 
-describe("GET /api/health — healthy", () => {
-  it("returns 200 with status ok, notion ok, and a live catalog", async () => {
-    stubNotionEnv();
+// ── Healthy (demo substrate) ────────────────────────────────────────
+//
+// `DATABASE_URL` unset is the default in every test, and it is a normal,
+// expected state — not a failure — so it reports `status: "ok"` with
+// `database: "demo"`, distinct from a real Postgres that is actually down.
 
+describe("GET /api/health — healthy (demo substrate)", () => {
+  it("returns 200 with status ok, database demo, and the seeded tool count", async () => {
     const res = await GET(makeRequest());
 
     expect(res.status).toBe(200);
     const body = await res.json();
     expect(body.status).toBe("ok");
-    expect(body.notion).toBe("ok");
-    expect(body.catalog).toBe("live");
-    expect(body.toolCount).toBeGreaterThan(0);
+    expect(body.database).toBe("demo");
+    expect(body.catalog).toBe("demo");
+    expect(body.toolCount).toBe(2); // the seeded demo catalogue: form-4, trotec-speedy-400
     expect(Number.isNaN(Date.parse(body.checkedAt))).toBe(false);
   });
 
-  it("probes Notion with a single page_size:1 query against the Tools database", async () => {
-    stubNotionEnv();
-
-    const probes: Array<{ db: string; body: unknown }> = [];
-    server.use(
-      http.post(
-        `https://api.notion.com/v1/databases/${DB_IDS.tools}/query`,
-        async ({ request }) => {
-          probes.push({ db: DB_IDS.tools, body: await request.json() });
-          return HttpResponse.json({ results: [], has_more: false, next_cursor: null });
-        }
-      )
-    );
-
-    await GET(makeRequest());
-
-    // First hit is the health probe itself; anything after is the catalog read.
-    expect(probes.length).toBeGreaterThan(0);
-    expect(probes[0].body).toEqual({ page_size: 1 });
-  });
-
   it("caches the probe on the 30s health profile", async () => {
-    stubNotionEnv();
-
     await GET(makeRequest());
 
     expect(vi.mocked(cacheLife)).toHaveBeenCalledWith(HEALTH_CACHE);
   });
 
   it("does not let a client or CDN store the verdict", async () => {
-    stubNotionEnv();
-
     const res = await GET(makeRequest());
 
     expect(res.headers.get("cache-control")).toBe("no-store");
   });
 });
 
-// ── Unconfigured ────────────────────────────────────────────────────
-
-describe("GET /api/health — unconfigured", () => {
-  it("returns 503 with notion unconfigured when the Notion env is empty", async () => {
-    unsetNotionEnv();
-
-    const res = await GET(makeRequest());
-
-    // The status code is the point: an uptime monitor alerts on 503, and would
-    // never notice a 200 carrying "degraded".
-    expect(res.status).toBe(503);
-    const body = await res.json();
-    expect(body.status).toBe("degraded");
-    expect(body.notion).toBe("unconfigured");
-    expect(body.catalog).toBe("mock");
-    expect(body.toolCount).toBe(mockTools.length);
-  });
-
-  it("returns 503 when a single NOTION_DB_* variable is dropped", async () => {
-    stubNotionEnv();
-    vi.stubEnv("NOTION_DB_UNITS", "");
-
-    const res = await GET(makeRequest());
+// ── Unreachable (a configured database that pingDb cannot reach) ────
+//
+// `dataSubstrate()` and `pingDb()` are mocked directly rather than pointed at
+// a real broken connection string, matching the `src/lib/catalog.test.ts`
+// "a database failure" pattern: `vi.doMock` + a fresh dynamic `import()`, so
+// only this one route instance sees the failure and every other test keeps
+// the real module and its memoised PGlite handle.
 
-    expect(res.status).toBe(503);
-    const body = await res.json();
-    expect(body.notion).toBe("unconfigured");
+describe("GET /api/health — unreachable", () => {
+  afterEach(() => {
+    vi.doUnmock("../../../lib/db/client");
+    vi.resetModules();
   });
-});
 
-// ── Unreachable ─────────────────────────────────────────────────────
+  it("returns 503 with database unreachable, degraded status, no live catalog, and no invented count", async () => {
+    vi.resetModules();
+    vi.doMock("../../../lib/db/client", () => ({
+      dataSubstrate: () => "neon",
+      pingDb: () => Promise.reject(new Error("connection terminated unexpectedly")),
+    }));
+    const { GET: GETWithBrokenDb } = await import("./route");
 
-describe("GET /api/health — unreachable", () => {
-  it("returns 503 with notion unreachable when the Notion query throws", async () => {
-    stubNotionEnv();
-    server.use(
-      http.post("https://api.notion.com/v1/databases/:id/query", () => HttpResponse.error())
-    );
-
-    const res = await GET(makeRequest());
+    const res = await GETWithBrokenDb(makeRequest());
 
     expect(res.status).toBe(503);
     const body = await res.json();
     expect(body.status).toBe("degraded");
-    expect(body.notion).toBe("unreachable");
-    expect(body.catalog).toBe("mock");
-    expect(body.toolCount).toBe(mockTools.length);
-  });
-
-  it("returns 503 with notion unreachable when Notion answers non-2xx", async () => {
-    stubNotionEnv();
-    server.use(
-      http.post("https://api.notion.com/v1/databases/:id/query", () =>
-        HttpResponse.json({ object: "error", code: "unauthorized" }, { status: 401 })
-      )
-    );
-
-    const res = await GET(makeRequest());
-
-    expect(res.status).toBe(503);
-    expect((await res.json()).notion).toBe("unreachable");
+    expect(body.database).toBe("unreachable");
+    expect(body.catalog).toBe("demo");
+    // Article 4: never invented data — a Postgres this probe just proved down
+    // is never asked for a tool count.
+    expect(body.toolCount).toBe(0);
   });
 });
 
 // ── Disclosure ──────────────────────────────────────────────────────
 //
-// A health endpoint that names the missing variable or echoes the Notion error
-// hands an attacker the configuration. The body is three enum words, a count,
-// and a timestamp — nothing else, on any path.
+// A health endpoint that echoes a driver error or connection string hands an
+// attacker the configuration. The body is three enum words, a count, and a
+// timestamp — nothing else, on any path.
 
 describe("GET /api/health — leaks nothing", () => {
-  const FORBIDDEN = [
-    "NOTION_",
-    "notion.com",
-    "secret_test",
-    "Bearer",
-    DB_IDS.tools,
-    DB_IDS.units,
-  ];
-
-  it("names no env var, Notion id, or error text when unconfigured", async () => {
-    unsetNotionEnv();
-
-    const raw = await (await GET(makeRequest())).text();
-
-    for (const needle of FORBIDDEN) expect(raw).not.toContain(needle);
-  });
-
-  it("does not echo the Notion error body when unreachable", async () => {
-    stubNotionEnv();
-    server.use(
-      http.post("https://api.notion.com/v1/databases/:id/query", () =>
-        HttpResponse.json(
-          {
-            object: "error",
-            code: "unauthorized",
-            message: "API token is invalid: secret_test against db-tools",
-          },
-          { status: 401 }
-        )
-      )
-    );
-
-    const raw = await (await GET(makeRequest())).text();
-
-    for (const needle of FORBIDDEN) expect(raw).not.toContain(needle);
-    expect(raw).not.toContain("API token is invalid");
-    expect(raw).not.toContain("unauthorized");
+  afterEach(() => {
+    vi.doUnmock("../../../lib/db/client");
+    vi.resetModules();
   });
 
   it("returns exactly the documented fields and nothing more", async () => {
-    unsetNotionEnv();
-
     const body = await (await GET(makeRequest())).json();
 
     expect(Object.keys(body).sort()).toEqual([
       "catalog",
       "checkedAt",
-      "notion",
+      "database",
       "status",
       "toolCount",
     ]);
   });
+
+  it("does not echo the driver error or connection string when unreachable", async () => {
+    const SENSITIVE = "postgres://admin:hunter2@db.internal.example.com/prod";
+    vi.resetModules();
+    vi.doMock("../../../lib/db/client", () => ({
+      dataSubstrate: () => "neon",
+      pingDb: () => Promise.reject(new Error(`could not connect to ${SENSITIVE}: ECONNREFUSED`)),
+    }));
+    const { GET: GETWithBrokenDb } = await import("./route");
+
+    const raw = await (await GETWithBrokenDb(makeRequest())).text();
+
+    for (const needle of [SENSITIVE, "hunter2", "ECONNREFUSED", "postgres://"]) {
+      expect(raw).not.toContain(needle);
+    }
+  });
 });
 
 // ── Rate limiting ───────────────────────────────────────────────────
 
 describe("GET /api/health — rate limiting", () => {
-  it("429s a caller that hammers it, before touching Notion", async () => {
-    unsetNotionEnv();
+  it("429s a caller that hammers it, before touching the database", async () => {
     const ip = "10.9.9.9";
 
     let last = await GET(makeRequest(ip));
diff --git a/v5/src/app/api/health/route.ts b/v5/src/app/api/health/route.ts
index a0c28b7..602accc 100644
--- a/v5/src/app/api/health/route.ts
+++ b/v5/src/app/api/health/route.ts
@@ -1,90 +1,84 @@
 import { cacheLife } from "next/cache";
 import { HEALTH_CACHE } from "../../../lib/cache";
 import { getCatalogTools } from "../../../lib/catalog";
-import { getNotionEnvContract } from "../../../lib/notion";
+import { dataSubstrate, pingDb } from "../../../lib/db/client";
 import { rateLimitAsync } from "../../../lib/rate-limit";
 import { resolveIdentity } from "../../../lib/auth/identity";
-import { mockTools } from "../../../components/mock-catalog";
 
 // `runtime` cannot be set when nextConfig.cacheComponents is enabled.
 // Default Node.js runtime is used.
 
-const NOTION_API_URL = "https://api.notion.com/v1";
-const NOTION_VERSION = "2022-06-28";
 const PROBE_TIMEOUT_MS = 5_000;
 
-type NotionHealth = "ok" | "unreachable" | "unconfigured";
+type DatabaseHealth = "ok" | "unreachable" | "demo";
 
 interface HealthReport {
   status: "ok" | "degraded";
-  notion: NotionHealth;
-  catalog: "live" | "mock";
+  database: DatabaseHealth;
+  catalog: "live" | "demo";
   toolCount: number;
   checkedAt: string;
 }
 
 /**
- * One minimal, uncached Notion call — `page_size: 1` against the Tools database.
- * It deliberately does *not* go through `catalog.ts`, whose day-long cache would
- * happily keep answering through an outage (which is the point of that cache and
- * the reason this probe exists).
+ * `pingDb()` carries no signal of its own (spec §3.2), and a hung connection
+ * must not hang this endpoint — race it against a plain timer instead.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error("Health probe timed out")), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * One `select 1` against Postgres — or `"demo"` with no round trip at all when
+ * `DATABASE_URL` is unset, since that runs the app on the in-process PGlite
+ * demo seed (spec §3.10) rather than on nothing. Demo is a known, expected
+ * substrate, not a failure, so it gets its own word instead of collapsing into
+ * `"ok"` or `"unreachable"`.
  *
- * Nothing about the failure escapes this function: the caller gets one of three
- * words. A health endpoint that reports `NOTION_DB_TOOLS is missing` or echoes a
- * Notion error body hands an attacker the configuration, so the detail is logged
- * server-side and nowhere else.
+ * Nothing about a real failure escapes this function beyond one of three
+ * words — a health endpoint that echoes a connection string or driver error
+ * hands an attacker the configuration, so the detail is logged server-side
+ * and nowhere else.
  */
-async function probeNotion(): Promise<NotionHealth> {
-  const configured = getNotionEnvContract().every((key) => Boolean(process.env[key]));
-  if (!configured) return "unconfigured";
+async function probeDatabase(): Promise<DatabaseHealth> {
+  if (dataSubstrate() === "pglite-demo") return "demo";
 
   try {
-    const res = await fetch(
-      `${NOTION_API_URL}/databases/${process.env.NOTION_DB_TOOLS}/query`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${process.env.NOTION_API_KEY}`,
-          "Content-Type": "application/json",
-          "Notion-Version": NOTION_VERSION,
-        },
-        body: JSON.stringify({ page_size: 1 }),
-        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
-      }
-    );
-
-    if (!res.ok) {
-      console.warn("Health probe: Notion query failed with status", res.status);
-      return "unreachable";
-    }
+    await withTimeout(pingDb(), PROBE_TIMEOUT_MS);
     return "ok";
   } catch (error) {
-    console.warn("Health probe: Notion unreachable:", error);
+    console.warn("Health probe: database unreachable:", error);
     return "unreachable";
   }
 }
 
 /**
- * Cached for ~30s so a monitor polling every minute costs at most one Notion
- * call per 30s and the endpoint cannot be used to hammer Notion. `checkedAt` is
+ * Cached for ~30s so a monitor polling every minute costs at most one probe
+ * per 30s and the endpoint cannot be used to hammer Postgres. `checkedAt` is
  * captured with the cached value, so it reports when the probe actually ran.
  *
- * The tool count comes from the catalog only when Notion answered; otherwise the
- * catalog is on its mock fallback and counting it would mean five more failing
- * Notion calls to learn something already known.
+ * The tool count comes from the catalogue whenever there is one to safely
+ * read: on the demo seed `getCatalogTools()` reads the local PGlite instance,
+ * which costs nothing extra to ask. A configured-but-unreachable Postgres is
+ * the one case that skips it — counting from a database this same probe just
+ * proved was down would mean either inventing a number or making the failing
+ * call twice, and Article 4 rules out the former.
  */
 async function checkHealth(): Promise<HealthReport> {
   "use cache";
   cacheLife(HEALTH_CACHE);
 
-  const notion = await probeNotion();
-  const live = notion === "ok";
-  const toolCount = live ? (await getCatalogTools()).length : mockTools.length;
+  const database = await probeDatabase();
+  const toolCount = database === "unreachable" ? 0 : (await getCatalogTools()).length;
 
   return {
-    status: live ? "ok" : "degraded",
-    notion,
-    catalog: live ? "live" : "mock",
+    status: database === "unreachable" ? "degraded" : "ok",
+    database,
+    catalog: database === "ok" ? "live" : "demo",
     toolCount,
     checkedAt: new Date().toISOString(),
   };
@@ -102,7 +96,7 @@ async function checkHealth(): Promise<HealthReport> {
  * around.
  */
 export async function GET(req: Request) {
-  // Rate limit before the probe — cheap as it is, it still touches Notion.
+  // Rate limit before the probe — cheap as it is, it still touches Postgres.
   const identity = await resolveIdentity(req);
   const { allowed } = await rateLimitAsync(`health:${identity.rateLimitKey}`, {
     limit: 30,
diff --git a/v5/src/app/api/mcp/route.test.ts b/v5/src/app/api/mcp/route.test.ts
index 5cb397b..fa72b54 100644
--- a/v5/src/app/api/mcp/route.test.ts
+++ b/v5/src/app/api/mcp/route.test.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 /**
  * Integration tests for the MCP API route (`src/app/api/mcp/route.ts`).
  *
@@ -7,10 +8,10 @@
  *   the route's `POST` handler and assert the JSON responses.
  * - `enableJsonResponse: true` in the route means the transport returns a single
  *   JSON object (not an SSE stream), so `await res.json()` works directly.
- * - Catalog comes from the mock-catalog fallback (no NOTION_* env set), so tool
- *   results are deterministic and offline.
- * - `@/lib/notion`'s `fetchMaintenanceLogsByUnit` is mocked so the maintenance
- *   tools are deterministic without any network.
+ * - Catalog and maintenance history come from the demo-seeded PGlite database
+ *   `getDb()` hands out with `DATABASE_URL` unset, so results are deterministic
+ *   and offline. The seed has no maintenance logs; the tests that need them
+ *   write them.
  *
  * SDK quirk discovered: the WebStandardStreamableHTTPServerTransport is created
  * with `sessionIdGenerator: undefined` (stateless mode). In that mode the
@@ -23,27 +24,30 @@
  * each method statelessly.
  */
 
+// `nextCacheMock` is imported first on purpose: `vi.mock` is hoisted above every
+// import, and its factory can only reach a module imported before the one it
+// replaces. `catalog.ts` imports `cacheTag`/`cacheLife`, which only work inside
+// the Next build.
+import { nextCacheMock } from "../../../../test/mocks/next-cache";
+import { eq } from "drizzle-orm";
 import { POST, GET } from "@/app/api/mcp/route";
+import { getDb, resetDbForTests } from "@/lib/db/client";
+import { maintenanceLogs, units } from "@/lib/db/schema/index";
 
-// Partial-mock @/lib/notion: override ONLY `fetchMaintenanceLogsByUnit` and keep
-// every other export real. (catalog.ts also imports from this module — e.g.
-// getNotionEnvContract, fetchAllTools — so a full replacement would break the
-// catalog's mock-fallback path.) The catalog itself still comes from the
-// mock-catalog because NOTION_* env stays unset.
-vi.mock("@/lib/notion", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@/lib/notion")>();
-  return {
-    ...actual,
-    fetchMaintenanceLogsByUnit: vi.fn(async () => []),
-  };
-});
-
-import { fetchMaintenanceLogsByUnit } from "@/lib/notion";
-
-const fetchLogsMock = vi.mocked(fetchMaintenanceLogsByUnit);
+vi.mock("next/cache", () => nextCacheMock());
 
 const MCP_URL = "http://localhost/api/mcp";
 
+/** The uuid of a seeded unit — what the capability resolves a label to. */
+async function unitId(label: string): Promise<string> {
+  const db = await getDb();
+  const [row] = await db
+    .select({ id: units.id })
+    .from(units)
+    .where(eq(units.unitLabel, label));
+  return row.id;
+}
+
 /** Build a JSON-RPC POST Request with the Accept header the transport requires. */
 function rpcRequest(
   body: unknown,
@@ -89,8 +93,18 @@ async function callTool(name: string, args: Record<string, unknown> = {}) {
 }
 
 beforeEach(() => {
-  fetchLogsMock.mockReset();
-  fetchLogsMock.mockResolvedValue([]);
+  vi.stubEnv("DATABASE_URL", "");
+});
+
+afterEach(async () => {
+  // The seeded catalogue rows are read, never written; only the logs a test
+  // wrote need clearing.
+  const db = await getDb();
+  await db.delete(maintenanceLogs);
+});
+
+afterAll(() => {
+  resetDbForTests();
 });
 
 // ── GET handler ──────────────────────────────────────────────────────
@@ -223,7 +237,7 @@ describe("tools/call: list_tools", () => {
   it("returns a structured summary of the whole catalog", async () => {
     const { json } = await callTool("list_tools");
     const parsed = JSON.parse(resultText(json));
-    // mock-catalog has 2 tools (Form 4, Trotec Speedy 400).
+    // The demo seed is 2 tools (Form 4, Trotec Speedy 400).
     expect(parsed.count).toBe(2);
     const names = parsed.tools.map((t: { name: string }) => t.name);
     expect(names).toContain("Form 4");
@@ -301,7 +315,7 @@ describe("tools/call: get_tool_details", () => {
 // ── tools/call: get_unit_details ─────────────────────────────────────
 
 describe("tools/call: get_unit_details", () => {
-  it("returns JSON for a real mock unit label", async () => {
+  it("returns JSON for a seeded unit label", async () => {
     const { json } = await callTool("get_unit_details", { unit_label: "Form 4 // A" });
     const text = resultText(json);
     const parsed = JSON.parse(text);
@@ -324,37 +338,44 @@ describe("tools/call: get_unit_details", () => {
 
 describe("tools/call: get_maintenance_history", () => {
   it("returns a JSON list of logs when the unit has maintenance history", async () => {
-    fetchLogsMock.mockResolvedValue([
+    const db = await getDb();
+    const form4A = await unitId("Form 4 // A");
+    await db.insert(maintenanceLogs).values([
+      {
+        title: "Resin tank cloudy",
+        unitId: form4A,
+        type: "repair",
+        priority: "high",
+        status: "open",
+        dateReported: "2024-09-01",
+        description: "The resin tank film is clouded and needs replacement.",
+      },
+      // A log on another unit, to prove the tool reads by unit rather than
+      // returning everything.
       {
-        id: "log-1",
-        createdTime: "2024-09-01T10:00:00.000Z",
-        lastEditedTime: "2024-09-01T10:00:00.000Z",
-        fields: {
-          title: "Resin tank cloudy",
-          type: "Repair",
-          priority: "High",
-          status: "Open",
-          date_reported: "2024-09-01",
-          description: "The resin tank film is clouded and needs replacement.",
-        },
+        title: "Lens dirty",
+        unitId: await unitId("Trotec Speedy 400"),
+        dateReported: "2024-09-02",
       },
-    ] as Awaited<ReturnType<typeof fetchMaintenanceLogsByUnit>>);
+    ]);
 
     const { json } = await callTool("get_maintenance_history", {
       unit_label: "Form 4 // A",
     });
     const text = resultText(json);
     const parsed = JSON.parse(text);
+    expect(parsed.unit_id).toBe(form4A);
     expect(parsed.unit_label).toBe("Form 4 // A");
     expect(parsed.maintenance_logs).toHaveLength(1);
     expect(parsed.maintenance_logs[0].title).toBe("Resin tank cloudy");
+    // Stored `repair` / `high` / `open`, shown in the words the assistant has
+    // always been given.
+    expect(parsed.maintenance_logs[0].type).toBe("Repair");
     expect(parsed.maintenance_logs[0].priority).toBe("High");
-    // Confirm the fetch was driven with the matched unit's id.
-    expect(fetchLogsMock).toHaveBeenCalledWith("unit-form-4-a");
+    expect(parsed.maintenance_logs[0].status).toBe("Open");
   });
 
   it("returns an empty log list when the unit has no logs", async () => {
-    fetchLogsMock.mockResolvedValue([]);
     const { json } = await callTool("get_maintenance_history", {
       unit_label: "Form 4 // A",
     });
diff --git a/v5/src/app/api/projects/route.test.ts b/v5/src/app/api/projects/route.test.ts
index 2f9c367..c9a79a6 100644
--- a/v5/src/app/api/projects/route.test.ts
+++ b/v5/src/app/api/projects/route.test.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 import { http, HttpResponse } from "msw";
 
 import { server } from "../../../../test/msw/server";
@@ -6,11 +7,38 @@ import {
   createSessionPayload,
   signSession,
 } from "@/lib/auth/session-cookie";
+import { nextCacheMock } from "../../../../test/mocks/next-cache";
+
+// The route translates catalogue ids to Notion page ids through Postgres, and
+// that module's neighbours import cacheTag/cacheLife.
+vi.mock("next/cache", () => nextCacheMock());
+
+import { getCatalogTools } from "@/lib/catalog";
+import { resetDbForTests } from "@/lib/db/client";
+import { DEMO_FORM_4_NOTION_PAGE_ID } from "@/lib/db/demo-seed";
 
 const NOTION = "https://api.notion.com/v1";
 const PROJECTS_DB = "db-projects";
 const AUTH_SECRET = "projects-route-test-secret";
 
+// `tools_used` is a Notion relation, but the form now submits catalogue ids —
+// Postgres uuids minted at seed time. The demo seed is the substrate here
+// (`DATABASE_URL` unset): the Form 4 came from Notion and has a page id, the
+// Trotec did not and has none.
+let FORM_4_ID = "";
+let TROTEC_ID = "";
+
+beforeEach(async () => {
+  vi.stubEnv("DATABASE_URL", "");
+  const tools = await getCatalogTools();
+  FORM_4_ID = tools.find((tool) => tool.slug === "form-4")?.id ?? "";
+  TROTEC_ID = tools.find((tool) => tool.slug === "trotec-speedy-400")?.id ?? "";
+});
+
+afterAll(() => {
+  resetDbForTests();
+});
+
 // ── Helpers ─────────────────────────────────────────────────────────
 
 // The in-memory limiter is a per-process singleton keyed by `projects:<ip>` —
@@ -68,7 +96,7 @@ function validPayload(overrides: Record<string, unknown> = {}) {
     title: "Lamp from scrap plywood",
     author: "Ada Lovelace",
     body: "Cut on the laser, glued, sanded.",
-    tools: ["tool-form-4"],
+    tools: [FORM_4_ID],
     materials: ["Plywood"],
     photos: [{ id: "file-upload-1", name: "cover.png" }],
     ...overrides,
@@ -167,7 +195,10 @@ describe("POST /api/projects (drafts by default)", () => {
 
     await post(
       submitRequest(
-        validPayload({ link: "https://example.com/lamp", tools: ["tool-form-4", "tool-2"] })
+        validPayload({
+          link: "https://example.com/lamp",
+          tools: [FORM_4_ID, TROTEC_ID],
+        })
       )
     );
 
@@ -179,8 +210,10 @@ describe("POST /api/projects (drafts by default)", () => {
       rich_text: [{ text: { content: "Ada Lovelace" } }],
     });
     expect(properties.link).toEqual({ url: "https://example.com/lamp" });
+    // Each catalogue id is translated to the tool's Notion page; the Trotec has
+    // no imported page, so it drops out rather than failing the whole write.
     expect(properties.tools_used).toEqual({
-      relation: [{ id: "tool-form-4" }, { id: "tool-2" }],
+      relation: [{ id: DEMO_FORM_4_NOTION_PAGE_ID }],
     });
     expect(properties.materials).toEqual({ multi_select: [{ name: "Plywood" }] });
     // Photos go in as file_upload references from /api/upload-notion.
@@ -439,14 +472,16 @@ describe("POST /api/projects (validation)", () => {
   it("accepts exactly 20 tools", async () => {
     stubProjectsEnv();
     const calls = captureNotionCreate();
-    const tools = Array.from({ length: 20 }, (_, i) => `tool-${i}`);
+    const tools = Array.from({ length: 20 }, () => crypto.randomUUID());
 
     const res = await post(submitRequest(validPayload({ tools })));
 
+    // The cap is what is under test: twenty is not one too many. None of these
+    // ids is a real tool, so nothing survives the Notion-page translation and
+    // the submission is filed without a relation rather than refused.
     expect(res.status).toBe(201);
-    expect(
-      (calls[0].properties?.tools_used as { relation: unknown[] }).relation
-    ).toHaveLength(20);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].properties?.tools_used).toBeUndefined();
   });
 
   it("ignores non-string entries in tools and materials", async () => {
@@ -455,13 +490,13 @@ describe("POST /api/projects (validation)", () => {
 
     const res = await post(
       submitRequest(
-        validPayload({ tools: ["tool-form-4", 7, null], materials: [{}, "Plywood"] })
+        validPayload({ tools: [FORM_4_ID, 7, null], materials: [{}, "Plywood"] })
       )
     );
 
     expect(res.status).toBe(201);
     expect(calls[0].properties?.tools_used).toEqual({
-      relation: [{ id: "tool-form-4" }],
+      relation: [{ id: DEMO_FORM_4_NOTION_PAGE_ID }],
     });
     expect(calls[0].properties?.materials).toEqual({
       multi_select: [{ name: "Plywood" }],
diff --git a/v5/src/app/api/projects/route.ts b/v5/src/app/api/projects/route.ts
index 1222f98..1aefd9a 100644
--- a/v5/src/app/api/projects/route.ts
+++ b/v5/src/app/api/projects/route.ts
@@ -4,6 +4,7 @@ import {
   hasProjectsEnv,
   type ProjectWriteFields,
 } from "../../../lib/notion";
+import { notionPageIdsForTools } from "../../../lib/data/notion-ids";
 import type { ProjectRecord } from "../../../lib/types";
 import { rateLimitAsync } from "../../../lib/rate-limit";
 import { resolveIdentity } from "../../../lib/auth/identity";
@@ -144,6 +145,13 @@ export async function POST(req: NextRequest) {
     );
   }
 
+  // `tools` arrives as catalogue ids, which are Postgres uuids since the read
+  // path moved (spec §3.10), while `tools_used` is a Notion relation. Translate
+  // through `tools.notion_page_id` and drop what does not resolve: Notion
+  // rejects the whole page for one unknown relation id, and losing a student's
+  // whole write-up over a tool link is the wrong way to fail (Article 4).
+  const toolPageIds = await notionPageIdsForTools(tools);
+
   try {
     const record = await submitProject({
       title,
@@ -154,7 +162,7 @@ export async function POST(req: NextRequest) {
       // no session, no email, submission still succeeds.
       author_email: identity.email || undefined,
       link: link || undefined,
-      tools_used: tools,
+      tools_used: toolPageIds,
       materials,
       photo_uploads: photoUploads,
     });
diff --git a/v5/src/app/projects/page.tsx b/v5/src/app/projects/page.tsx
index 4d0b583..ad5ca51 100644
--- a/v5/src/app/projects/page.tsx
+++ b/v5/src/app/projects/page.tsx
@@ -36,7 +36,7 @@ export default async function ProjectsPage() {
           projects.map((project) => (
             <Link
               className="project-card"
-              href={`/projects/${project.id}`}
+              href={`/projects/${project.slug}`}
               key={project.id}
             >
               <span className="project-card-cover" aria-hidden="true">
diff --git a/v5/src/app/tools/[id]/page.tsx b/v5/src/app/tools/[id]/page.tsx
index 953eda3..6d8215d 100644
--- a/v5/src/app/tools/[id]/page.tsx
+++ b/v5/src/app/tools/[id]/page.tsx
@@ -1,30 +1,61 @@
 import { Suspense } from "react";
-import { notFound } from "next/navigation";
+import { notFound, permanentRedirect } from "next/navigation";
 import { QrArrivalNotice } from "./QrArrivalNotice";
 import { DetailShell } from "../../../components/DetailShell";
 import { FlagButton } from "../../../components/FlagButton";
-import { getCatalogTool, getCatalogTools } from "../../../lib/catalog";
+import { getCatalogTool } from "../../../lib/catalog";
+import { findToolByNotionPageId } from "../../../lib/data/catalog";
+import { isLegacyNotionId } from "../../../lib/legacy-id";
 import { getProjectsForTool } from "../../../lib/projects";
 
 interface ToolDetailPageProps {
   params: Promise<{
     id: string;
   }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
 }
 
-export async function generateStaticParams() {
-  const tools = await getCatalogTools();
+// No `generateStaticParams`: enumerating the slugs would make `next build`
+// depend on the database, which the client is explicitly designed not to
+// require — `DATABASE_URL` may be unset, Neon may be asleep, and PGlite cannot
+// run inside the bundled build (spec §3.2). Tool pages render on first request
+// instead and are then served from the cache, which is where they came from
+// anyway: every catalogue read is `"use cache"` + `cacheTag("catalog")`, so a
+// later write invalidates them by tag rather than waiting for the next build
+// (spec §3.9). `/projects/[id]` skips it for the same reason.
 
-  return tools.map((tool) => ({
-    id: tool.slug,
-  }));
+/**
+ * Re-encodes the incoming query string for a redirect target. `?src=qr` is
+ * the case that matters (`QrArrivalNotice` reads it on whatever page it lands
+ * on), but nothing here is specific to that one key — a legacy link keeps
+ * whatever it was carrying.
+ */
+function preserveQueryString(searchParams: Record<string, string | string[] | undefined>): string {
+  const qs = new URLSearchParams();
+  for (const [key, value] of Object.entries(searchParams)) {
+    if (value === undefined) continue;
+    for (const v of Array.isArray(value) ? value : [value]) qs.append(key, v);
+  }
+  const serialized = qs.toString();
+  return serialized ? `?${serialized}` : "";
 }
 
-export default async function ToolDetailPage({ params }: ToolDetailPageProps) {
+export default async function ToolDetailPage({ params, searchParams }: ToolDetailPageProps) {
   const { id } = await params;
   const tool = await getCatalogTool(id);
 
   if (!tool) {
+    // Printed QR labels and old links encode a Notion page id rather than a
+    // slug (spec Goal 2). A match redirects permanently to the tool's current
+    // slug; anything else — a stale id, a typo, a slug that never existed —
+    // 404s exactly as it did before this check existed.
+    if (isLegacyNotionId(id)) {
+      const match = await findToolByNotionPageId(id);
+      if (match) {
+        const query = preserveQueryString(await searchParams);
+        permanentRedirect(`/tools/${match.slug}${query}`);
+      }
+    }
     notFound();
   }
 
diff --git a/v5/src/components/DemoDataBanner.test.tsx b/v5/src/components/DemoDataBanner.test.tsx
index deb079f..b95bd9a 100644
--- a/v5/src/components/DemoDataBanner.test.tsx
+++ b/v5/src/components/DemoDataBanner.test.tsx
@@ -1,7 +1,12 @@
+import { nextCacheMock } from "../../test/mocks/next-cache";
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { DemoDataBanner } from "./DemoDataBanner";
 
+// The banner reaches `isDemoCatalog` through `lib/catalog`, which imports
+// `next/cache` at module load.
+vi.mock("next/cache", () => nextCacheMock());
+
 // The banner asks next-intl for copy on the server; the message content is not
 // what is under test here, only whether the banner appears at all.
 vi.mock("next-intl/server", () => ({
@@ -14,21 +19,6 @@ vi.mock("next-intl/server", () => ({
   },
 }));
 
-const NOTION_ENV = [
-  "NOTION_API_KEY",
-  "NOTION_DB_TOOLS",
-  "NOTION_DB_CATEGORIES",
-  "NOTION_DB_LOCATIONS",
-  "NOTION_DB_UNITS",
-  "NOTION_DB_RESOURCES",
-  "NOTION_DB_MAINTENANCE_LOGS",
-  "NOTION_DB_FLAGS",
-];
-
-function configureNotion() {
-  for (const key of NOTION_ENV) vi.stubEnv(key, "configured");
-}
-
 async function renderBanner() {
   render(await DemoDataBanner());
 }
@@ -37,7 +27,8 @@ describe("DemoDataBanner", () => {
   beforeEach(() => vi.unstubAllEnvs());
   afterEach(() => vi.unstubAllEnvs());
 
-  it("warns when Notion is not configured at all", async () => {
+  it("warns when there is no database and the catalogue is the demo seed", async () => {
+    vi.stubEnv("DATABASE_URL", "");
     await renderBanner();
     const banner = screen.getByRole("status");
     expect(banner).toHaveTextContent("Demo data");
@@ -46,19 +37,18 @@ describe("DemoDataBanner", () => {
     expect(banner.textContent).toMatch(/inventory/);
   });
 
-  it("stays out of the way when the catalogue is real", async () => {
-    configureNotion();
+  it("stays out of the way when a real database is configured", async () => {
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@example.neon.tech/db");
     await renderBanner();
     expect(screen.queryByRole("status")).toBeNull();
   });
 
-  // The failure that actually reaches production is not "Notion is unset" — it is
-  // one variable dropped during a deploy. The catalogue silently falls back to
-  // invented equipment, so the banner has to fire on a partial contract too.
-  it.each(NOTION_ENV)("warns when only %s is missing", async (missing) => {
-    configureNotion();
-    vi.stubEnv(missing, "");
+  // A configured-but-unreachable database is a different failure: the catalogue
+  // throws rather than serving sample data, so the banner must not claim the
+  // page is a demo. It keys on the substrate alone.
+  it("does not fire for a database that is merely unhealthy", async () => {
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@unreachable.invalid/db");
     await renderBanner();
-    expect(screen.getByRole("status")).toBeInTheDocument();
+    expect(screen.queryByRole("status")).toBeNull();
   });
 });
diff --git a/v5/src/components/DemoDataBanner.tsx b/v5/src/components/DemoDataBanner.tsx
index 6916523..a2791a8 100644
--- a/v5/src/components/DemoDataBanner.tsx
+++ b/v5/src/components/DemoDataBanner.tsx
@@ -1,27 +1,26 @@
 import { getTranslations } from "next-intl/server";
-import { hasNotionCatalogEnv } from "../lib/catalog";
+import { isDemoCatalog } from "../lib/catalog";
 import { siteConfig } from "../lib/site-config";
 
 /**
- * Says out loud that the catalogue is built-in demo data rather than the lab's
- * real inventory (operational-hardening spec §6).
+ * Says out loud that the catalogue is the built-in demo seed rather than the
+ * lab's real inventory (operational-hardening spec §6).
  *
- * The fallback itself is deliberate and load-bearing: it is why `npm run dev`
- * and the whole test suite work with no credentials. What was dangerous was
- * that it happened *silently* — a deploy missing one `NOTION_DB_*` variable
- * served invented equipment and looked perfectly healthy, and the only way to
- * find out was to recognise machines the lab does not own.
+ * The seed itself is deliberate and load-bearing: an unset `DATABASE_URL` runs
+ * the app on an in-process Postgres, which is why `npm run dev` and the whole
+ * test suite work with no credentials. What was dangerous was that it happened
+ * *silently* — a deploy missing the variable served equipment the lab does not
+ * own and looked perfectly healthy.
  *
  * `/api/health` reports the same state as a 503 for monitors. This is the half
  * a person standing in front of the page can see.
  *
- * Keyed on the env contract rather than on a fallback that already happened,
- * because a server component renders before any catalogue fetch it does not
- * itself perform — and a missing variable is the case that actually reaches
- * production. A transient fetch failure is caught by the health endpoint.
+ * Keyed on the substrate, not on a failure that already happened: a configured
+ * database that is unreachable is a different case, and one the catalogue
+ * surfaces by failing rather than by quietly showing sample data (Article 4).
  */
 export async function DemoDataBanner() {
-  if (hasNotionCatalogEnv()) return null;
+  if (!isDemoCatalog()) return null;
 
   const t = await getTranslations("demoBanner");
 
diff --git a/v5/src/components/DetailShell.tsx b/v5/src/components/DetailShell.tsx
index 76dd7ce..8b7c2c3 100644
--- a/v5/src/components/DetailShell.tsx
+++ b/v5/src/components/DetailShell.tsx
@@ -320,7 +320,7 @@ export function DetailShell({ tool, projects = [] }: DetailShellProps) {
           </header>
           <div className="td-doc-list">
             {projects.map((project) => (
-              <Link className="td-doc" href={`/projects/${project.id}`} key={project.id}>
+              <Link className="td-doc" href={`/projects/${project.slug}`} key={project.id}>
                 <span className="td-doc-body">
                   <strong>{project.title}</strong>
                   <p>{t("builtWithThisBy", { author: project.author })}</p>
diff --git a/v5/src/components/PrimaryNav.test.tsx b/v5/src/components/PrimaryNav.test.tsx
index ada6b41..9c936d3 100644
--- a/v5/src/components/PrimaryNav.test.tsx
+++ b/v5/src/components/PrimaryNav.test.tsx
@@ -1,6 +1,7 @@
+import { waitForElementToBeRemoved } from "@testing-library/react";
 import { PrimaryNav } from "./PrimaryNav";
 import { render, screen, userEvent } from "../../test/utils/render";
-import type { ClientIdentity } from "../lib/auth/sign-in-client";
+import type { ClientIdentity, SignInStart } from "../lib/auth/sign-in-client";
 
 // PrimaryNav is a client component that reads the active route from
 // `usePathname`. Mock `next/navigation` so each test can control the path
@@ -16,8 +17,8 @@ vi.mock("next/navigation", () => ({
 // real, since the header's job is to render what they derive). Their own
 // behaviour is covered in `lib/auth/sign-in-client.test.ts`.
 const fetchIdentity = vi.fn<() => Promise<ClientIdentity | null>>(async () => null);
-const startGoogleSignIn = vi.fn<(callbackURL: string) => Promise<boolean>>(
-  async () => true
+const startGoogleSignIn = vi.fn<(callbackURL: string) => Promise<SignInStart>>(
+  async () => "started"
 );
 const signOutAndReload = vi.fn(async () => {});
 
@@ -217,7 +218,7 @@ describe("PrimaryNav — sign-in control", () => {
 
   it("re-enables the control when sign-in could not start", async () => {
     const user = userEvent.setup();
-    startGoogleSignIn.mockResolvedValue(false);
+    startGoogleSignIn.mockResolvedValue("failed");
     render(<PrimaryNav />);
 
     const button = await screen.findByRole("button", { name: /Sign in/ });
@@ -225,6 +226,51 @@ describe("PrimaryNav — sign-in control", () => {
 
     expect(button).not.toBeDisabled();
   });
+
+  it("says so, beside the control, when this deployment has no sign-in set up", async () => {
+    const user = userEvent.setup();
+    startGoogleSignIn.mockResolvedValue("unconfigured");
+    render(<PrimaryNav />);
+
+    await user.click(await screen.findByRole("button", { name: /Sign in/ }));
+
+    expect(await screen.findByRole("status")).toHaveTextContent(
+      "Sign-in isn't set up on this deployment yet."
+    );
+  });
+
+  it("says the attempt failed when the request did, and clears the notice on the next try", async () => {
+    const user = userEvent.setup();
+    startGoogleSignIn.mockResolvedValue("failed");
+    render(<PrimaryNav />);
+
+    const button = await screen.findByRole("button", { name: /Sign in/ });
+    await user.click(button);
+    expect(await screen.findByRole("status")).toHaveTextContent("Couldn't start sign-in. Try again.");
+
+    // A retry that leaves for Google renders no notice at all.
+    startGoogleSignIn.mockResolvedValue("started");
+    await user.click(button);
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("shows no notice before anyone has tried", async () => {
+    render(<PrimaryNav />);
+    await screen.findByRole("button", { name: /Sign in/ });
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("lets the notice go after its duration instead of keeping it in the header", async () => {
+    const user = userEvent.setup();
+    startGoogleSignIn.mockResolvedValue("unconfigured");
+    render(<PrimaryNav noticeDurationMs={40} />);
+
+    await user.click(await screen.findByRole("button", { name: /Sign in/ }));
+    const notice = await screen.findByRole("status");
+    expect(notice).toHaveStyle({ animationDuration: "40ms" });
+
+    await waitForElementToBeRemoved(() => screen.queryByRole("status"));
+  });
 });
 
 // The header is where the staff refresh control lives (ops hardening spec §3.2),
diff --git a/v5/src/components/PrimaryNav.tsx b/v5/src/components/PrimaryNav.tsx
index 514b11c..a91a4ba 100644
--- a/v5/src/components/PrimaryNav.tsx
+++ b/v5/src/components/PrimaryNav.tsx
@@ -14,6 +14,7 @@ import {
   signOutAndReload,
   startGoogleSignIn,
   type ClientIdentity,
+  type SignInStart,
 } from "../lib/auth/sign-in-client";
 
 const LINKS = [
@@ -22,7 +23,10 @@ const LINKS = [
   { href: "/about", key: "about", match: (path: string) => path.startsWith("/about") },
 ] as const;
 
-export function PrimaryNav() {
+/** How long a sign-in notice stays before it fades. Long enough to read twice. */
+export const SIGN_IN_NOTICE_MS = 6000;
+
+export function PrimaryNav({ noticeDurationMs = SIGN_IN_NOTICE_MS }: { noticeDurationMs?: number } = {}) {
   const pathname = usePathname() || "/";
   const t = useTranslations("nav");
   const { open } = useChatLauncher();
@@ -34,6 +38,18 @@ export function PrimaryNav() {
   // not a loading failure, and nothing on the page is gated behind signing in.
   const [identity, setIdentity] = useState<ClientIdentity | null>(null);
   const [busy, setBusy] = useState(false);
+  // Why the last sign-in attempt left the visitor here. A click that does
+  // nothing looks broken; this says what happened, in a sentence, beside the
+  // control.
+  const [signInNotice, setSignInNotice] = useState<Exclude<SignInStart, "started"> | null>(null);
+
+  // The notice is transient: it fades and goes after a few seconds rather than
+  // sitting in the header for the rest of the visit.
+  useEffect(() => {
+    if (!signInNotice) return;
+    const timer = setTimeout(() => setSignInNotice(null), noticeDurationMs);
+    return () => clearTimeout(timer);
+  }, [signInNotice, noticeDurationMs]);
 
   useEffect(() => {
     const controller = new AbortController();
@@ -52,11 +68,15 @@ export function PrimaryNav() {
 
   async function handleSignIn() {
     setBusy(true);
+    setSignInNotice(null);
     // Come back to the page the user started on, never to "/" (spec §10).
-    const started = await startGoogleSignIn(pathname);
-    // On success the browser is already leaving for Google; this only matters
-    // when sign-in is unconfigured or the request failed.
-    if (!started) setBusy(false);
+    const result = await startGoogleSignIn(pathname);
+    // On success the browser is already leaving for Google; the rest only
+    // matters when sign-in is unconfigured or the request failed.
+    if (result !== "started") {
+      setBusy(false);
+      setSignInNotice(result);
+    }
   }
 
   async function handleSignOut() {
@@ -75,9 +95,10 @@ export function PrimaryNav() {
           {t(link.key)}
         </Link>
       ))}
+      {/* Same nav-action chrome as Report: an action, not a page. */}
       <button
         type="button"
-        className="primary-nav-add"
+        className="primary-nav-report primary-nav-add"
         onClick={() => open(t("addSeed"))}
         aria-label={t("addAria")}
       >
@@ -121,15 +142,26 @@ export function PrimaryNav() {
           </button>
         </>
       ) : (
-        <button
-          type="button"
-          className="primary-nav-report primary-nav-auth"
-          onClick={handleSignIn}
-          disabled={busy}
-          aria-label={t("signInAria", { institution: siteConfig.institution })}
-        >
-          {t("signIn")}
-        </button>
+        <>
+          <button
+            type="button"
+            className="primary-nav-report primary-nav-auth"
+            onClick={handleSignIn}
+            disabled={busy}
+            aria-label={t("signInAria", { institution: siteConfig.institution })}
+          >
+            {t("signIn")}
+          </button>
+          {signInNotice ? (
+            <span
+              role="status"
+              className="primary-nav-notice"
+              style={{ animationDuration: `${noticeDurationMs}ms` }}
+            >
+              {t(signInNotice === "unconfigured" ? "signInUnconfigured" : "signInFailed")}
+            </span>
+          ) : null}
+        </>
       )}
     </nav>
   );
diff --git a/v5/src/components/ProjectDetail.test.tsx b/v5/src/components/ProjectDetail.test.tsx
index d3d8ff9..e9ffccd 100644
--- a/v5/src/components/ProjectDetail.test.tsx
+++ b/v5/src/components/ProjectDetail.test.tsx
@@ -52,6 +52,7 @@ import { ProjectDetail } from "./ProjectDetail";
 function project(overrides: Partial<MakerLabProject> = {}): MakerLabProject {
   return {
     id: "project-1",
+    slug: "lamp-from-scrap-plywood",
     title: "Lamp from scrap plywood",
     author: "Ada Lovelace",
     body: "## How I made it\n\nCut on the laser, then glued.",
diff --git a/v5/src/components/catalog-types.ts b/v5/src/components/catalog-types.ts
index edadc98..f0f1ced 100644
--- a/v5/src/components/catalog-types.ts
+++ b/v5/src/components/catalog-types.ts
@@ -53,6 +53,8 @@ export interface ProjectToolRef {
 
 export interface MakerLabProject {
   id: string;
+  /** Readable URL key, assigned once from the title; `/projects/<slug>`. */
+  slug: string;
   title: string;
   author: string;
   /** Markdown write-up (rendered with react-markdown + remark-gfm). */
diff --git a/v5/src/i18n/messages.test.ts b/v5/src/i18n/messages.test.ts
new file mode 100644
index 0000000..c082321
--- /dev/null
+++ b/v5/src/i18n/messages.test.ts
@@ -0,0 +1,43 @@
+import en from "../../messages/en.json";
+import { LOCALE_CODES } from "./config";
+import { withEnglishFallback, type Messages } from "./messages";
+
+describe("withEnglishFallback", () => {
+  it("fills a key the locale lacks with the English one, nested namespaces included", () => {
+    const english: Messages = { nav: { signIn: "SIGN IN", signInUnconfigured: "Not set up." } };
+    const french: Messages = { nav: { signIn: "CONNEXION" } };
+
+    expect(withEnglishFallback(english, french)).toEqual({
+      nav: { signIn: "CONNEXION", signInUnconfigured: "Not set up." },
+    });
+  });
+
+  it("keeps a whole namespace the locale defines and English does not", () => {
+    const english: Messages = { nav: { signIn: "SIGN IN" } };
+    const locale: Messages = { nav: { signIn: "X" }, extra: { only: "here" } };
+
+    expect(withEnglishFallback(english, locale).extra).toEqual({ only: "here" });
+  });
+
+  it("does not mutate either input", () => {
+    const english: Messages = { nav: { signIn: "SIGN IN" } };
+    const locale: Messages = { nav: {} };
+    withEnglishFallback(english, locale);
+    expect(english).toEqual({ nav: { signIn: "SIGN IN" } });
+    expect(locale).toEqual({ nav: {} });
+  });
+
+  it("gives every locale file every English key", async () => {
+    for (const code of LOCALE_CODES) {
+      const locale = (await import(`../../messages/${code}.json`)).default as Messages;
+      const merged = withEnglishFallback(en as Messages, locale);
+      expect(flatKeys(merged)).toEqual(expect.arrayContaining(flatKeys(en as Messages)));
+    }
+  });
+});
+
+function flatKeys(messages: Messages, prefix = ""): string[] {
+  return Object.entries(messages).flatMap(([key, value]) =>
+    typeof value === "string" ? [`${prefix}${key}`] : flatKeys(value, `${prefix}${key}.`)
+  );
+}
diff --git a/v5/src/i18n/messages.ts b/v5/src/i18n/messages.ts
new file mode 100644
index 0000000..a1948e9
--- /dev/null
+++ b/v5/src/i18n/messages.ts
@@ -0,0 +1,27 @@
+/**
+ * Locale messages with English underneath (constitution Article 6, as amended
+ * 2026-09-14): a string is added to `messages/en.json` in the PR that needs
+ * it, and the other locale files catch up in a translation pass. Until then a
+ * key missing from a locale file renders in English rather than as a raw key
+ * or a runtime error.
+ */
+
+export type Messages = { [key: string]: string | Messages };
+
+/**
+ * `locale` laid over `english`, namespace by namespace: every English key is
+ * present in the result, and a key the locale file does define wins.
+ */
+export function withEnglishFallback(english: Messages, locale: Messages): Messages {
+  const merged: Messages = { ...english };
+  for (const [key, value] of Object.entries(locale)) {
+    const base = english[key];
+    merged[key] =
+      isNamespace(value) && isNamespace(base) ? withEnglishFallback(base, value) : value;
+  }
+  return merged;
+}
+
+function isNamespace(value: unknown): value is Messages {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/v5/src/i18n/request.ts b/v5/src/i18n/request.ts
index a7caf3e..80a1cbe 100644
--- a/v5/src/i18n/request.ts
+++ b/v5/src/i18n/request.ts
@@ -1,11 +1,14 @@
 import { getRequestConfig } from "next-intl/server";
 import { resolveLocale } from "./locale";
+import { withEnglishFallback, type Messages } from "./messages";
 
 export default getRequestConfig(async () => {
   const locale = await resolveLocale();
+  const english = (await import("../../messages/en.json")).default as Messages;
+  if (locale === "en") return { locale, messages: english };
 
-  return {
-    locale,
-    messages: (await import(`../../messages/${locale}.json`)).default,
-  };
+  // Other locales sit on top of English (Article 6, as amended): a key that
+  // has not been translated yet renders in English, never as a raw key.
+  const messages = (await import(`../../messages/${locale}.json`)).default as Messages;
+  return { locale, messages: withEnglishFallback(english, messages) };
 });
diff --git a/v5/src/lib/auth/sign-in-client.test.ts b/v5/src/lib/auth/sign-in-client.test.ts
index 5e0e43e..307659f 100644
--- a/v5/src/lib/auth/sign-in-client.test.ts
+++ b/v5/src/lib/auth/sign-in-client.test.ts
@@ -129,7 +129,7 @@ describe("startGoogleSignIn", () => {
       json({ url: "https://accounts.google.com/o/oauth2/auth?hd=cornell.edu" })
     );
 
-    await expect(startGoogleSignIn("/tools/form-4")).resolves.toBe(true);
+    await expect(startGoogleSignIn("/tools/form-4")).resolves.toBe("started");
 
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [url, init] = fetchMock.mock.calls[0];
@@ -158,15 +158,21 @@ describe("startGoogleSignIn", () => {
     expect(JSON.parse(String(fetchMock.mock.calls[0][1]?.body)).callbackURL).toBe("/");
   });
 
-  it("reports failure and navigates nowhere when sign-in is unconfigured", async () => {
+  it("says sign-in is unconfigured, and navigates nowhere, on the 503 the auth route answers", async () => {
     stubFetch(async () => json({ error: "Sign-in is not configured." }, 503));
-    await expect(startGoogleSignIn("/")).resolves.toBe(false);
+    await expect(startGoogleSignIn("/")).resolves.toBe("unconfigured");
+    expect(assign).not.toHaveBeenCalled();
+  });
+
+  it("reports failure on any other non-OK answer", async () => {
+    stubFetch(async () => json({ error: "nope" }, 500));
+    await expect(startGoogleSignIn("/")).resolves.toBe("failed");
     expect(assign).not.toHaveBeenCalled();
   });
 
   it("reports failure when the response carries no URL", async () => {
     stubFetch(async () => json({ redirect: true }));
-    await expect(startGoogleSignIn("/")).resolves.toBe(false);
+    await expect(startGoogleSignIn("/")).resolves.toBe("failed");
     expect(assign).not.toHaveBeenCalled();
   });
 
@@ -174,7 +180,7 @@ describe("startGoogleSignIn", () => {
     stubFetch(async () => {
       throw new TypeError("Failed to fetch");
     });
-    await expect(startGoogleSignIn("/")).resolves.toBe(false);
+    await expect(startGoogleSignIn("/")).resolves.toBe("failed");
   });
 });
 
diff --git a/v5/src/lib/auth/sign-in-client.ts b/v5/src/lib/auth/sign-in-client.ts
index c4cb9e9..2bb74bb 100644
--- a/v5/src/lib/auth/sign-in-client.ts
+++ b/v5/src/lib/auth/sign-in-client.ts
@@ -71,28 +71,37 @@ export async function fetchIdentity(
   }
 }
 
+/**
+ * How an attempt to start sign-in ended. `started` means the browser is on
+ * its way to Google; the other two mean it is still here and the caller has
+ * something to tell the visitor: this deployment has no sign-in set up
+ * (`/api/auth` answers 503), or the request itself failed.
+ */
+export type SignInStart = "started" | "unconfigured" | "failed";
+
 /**
  * Start the Google flow and hand the browser to Google.
  *
  * `callbackURL` is where the user comes back to — the page they were on, never
  * `/`, which is on the spec's list of things that would embarrass us (§10).
- * Returns `false` when sign-in is not configured or the request failed, so the
- * caller can stop showing a spinner.
+ * Never throws; the result says why the browser is still here, so a click on
+ * "Sign in" is never silently nothing.
  */
-export async function startGoogleSignIn(callbackURL: string): Promise<boolean> {
+export async function startGoogleSignIn(callbackURL: string): Promise<SignInStart> {
   try {
     const res = await fetch(SIGN_IN_ENDPOINT, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ provider: PROVIDER, callbackURL: callbackURL || "/" }),
     });
-    if (!res.ok) return false;
+    if (res.status === 503) return "unconfigured";
+    if (!res.ok) return "failed";
     const body = (await res.json()) as { url?: string } | null;
-    if (!body?.url) return false;
+    if (!body?.url) return "failed";
     window.location.assign(body.url);
-    return true;
+    return "started";
   } catch {
-    return false;
+    return "failed";
   }
 }
 
diff --git a/v5/src/lib/cache.ts b/v5/src/lib/cache.ts
index f5a7056..ab887e6 100644
--- a/v5/src/lib/cache.ts
+++ b/v5/src/lib/cache.ts
@@ -13,9 +13,9 @@
  */
 
 /**
- * Catalog reads (`fetchFullCatalog`). Long by design — a Notion outage keeps
- * serving cached data rather than falling back to the mock catalog, which is
- * "fail toward stale, not toward wrong". `/api/health` probes Notion directly so
+ * Catalog reads (`getCatalogTools`). Long by design — a database outage keeps
+ * serving cached data rather than falling back to sample data, which is "fail
+ * toward stale, not toward wrong". `/api/health` probes Postgres directly so
  * the outage is still visible.
  */
 export const CATALOG_CACHE = {
diff --git a/v5/src/lib/capabilities/catalog.test.ts b/v5/src/lib/capabilities/catalog.test.ts
new file mode 100644
index 0000000..4f7633e
--- /dev/null
+++ b/v5/src/lib/capabilities/catalog.test.ts
@@ -0,0 +1,163 @@
+// @vitest-environment node
+// `nextCacheMock` is imported first on purpose: `vi.mock` is hoisted above
+// every import, and its factory can only reach a module imported before the one
+// it replaces.
+import { nextCacheMock } from "../../../test/mocks/next-cache";
+import { getCatalogTools } from "../catalog";
+import { resetDbForTests } from "../db/client";
+import { catalog } from "./catalog";
+import type { CapabilityCtx, CapabilityTool } from "./types";
+
+vi.mock("next/cache", () => nextCacheMock());
+
+/**
+ * The `catalog` capability against the demo-seeded PGlite database — the same
+ * two tools (`form-4`, `trotec-speedy-400`) the mock catalogue used to supply,
+ * now real rows. Nothing here writes, so the seed is read as-is.
+ */
+
+const ctx: CapabilityCtx = {};
+
+function tool(name: string): CapabilityTool {
+  const found = catalog.tools.find((t) => t.name === name);
+  if (!found) throw new Error(`No such tool: ${name}`);
+  return found;
+}
+
+beforeEach(() => {
+  vi.stubEnv("DATABASE_URL", "");
+});
+
+afterAll(() => {
+  resetDbForTests();
+});
+
+// ── list_tools ─────────────────────────────────────────────────────
+
+describe("list_tools", () => {
+  it("lists the whole catalogue with a one-line summary each", async () => {
+    const result = (await tool("list_tools").run({}, ctx)) as {
+      count: number;
+      tools: { name: string; slug: string; summary: string }[];
+    };
+
+    expect(result.count).toBe(2);
+    expect(result.tools.map((t) => t.slug)).toEqual(["form-4", "trotec-speedy-400"]);
+    expect(result.tools[0].summary).toContain("Form 4");
+    expect(result.tools[0].summary).toContain("training: Intermediate");
+  });
+
+  it("narrows by category and by location, on a partial match", async () => {
+    const byCategory = (await tool("list_tools").run({ category: "laser" }, ctx)) as {
+      tools: { name: string }[];
+    };
+    expect(byCategory.tools.map((t) => t.name)).toEqual(["Trotec Speedy 400"]);
+
+    const byLocation = (await tool("list_tools").run({ location: "Resin" }, ctx)) as {
+      tools: { name: string }[];
+    };
+    expect(byLocation.tools.map((t) => t.name)).toEqual(["Form 4"]);
+  });
+});
+
+// ── search_tools ───────────────────────────────────────────────────
+
+describe("search_tools", () => {
+  it("matches on materials as well as names and descriptions", async () => {
+    const result = (await tool("search_tools").run({ query: "acrylic" }, ctx)) as {
+      count: number;
+      tools: { name: string; short_description: string }[];
+    };
+
+    expect(result.count).toBe(1);
+    expect(result.tools[0].name).toBe("Trotec Speedy 400");
+    expect(result.tools[0].short_description).toMatch(/laser/i);
+  });
+
+  it("returns an empty result set rather than a guess on a miss", async () => {
+    const result = (await tool("search_tools").run(
+      { query: "nonexistent-widget-xyz" },
+      ctx
+    )) as { query: string; count: number; tools: unknown[] };
+
+    expect(result).toMatchObject({ query: "nonexistent-widget-xyz", count: 0, tools: [] });
+  });
+});
+
+// ── get_tool_details ───────────────────────────────────────────────
+
+describe("get_tool_details", () => {
+  it("resolves a tool by slug and returns its full record", async () => {
+    const result = (await tool("get_tool_details").run(
+      { id_or_name: "form-4" },
+      ctx
+    )) as Record<string, unknown>;
+
+    expect(result).toMatchObject({
+      found: true,
+      slug: "form-4",
+      name: "Form 4",
+      category: "3D Printing",
+      category_sub: "Resin",
+      location: "MakerLab",
+      zone: "Resin Bench",
+      training_level: "Intermediate",
+      status: "In Use",
+      detail_page: "/tools/form-4",
+    });
+    expect(result.links).not.toEqual([]);
+    expect(result.units).toHaveLength(1);
+  });
+
+  it("resolves a tool by the Postgres id it hands back in `list_tools`", async () => {
+    // The round trip that matters: the model reads an id out of one tool result
+    // and passes it to another. Ids are uuids now, not Notion page ids.
+    const [form4] = await getCatalogTools();
+    const result = (await tool("get_tool_details").run(
+      { id_or_name: form4.id },
+      ctx
+    )) as { found: boolean; slug: string };
+
+    expect(result).toMatchObject({ found: true, slug: "form-4" });
+  });
+
+  it("falls back to a partial name when the value is neither id nor slug", async () => {
+    const result = (await tool("get_tool_details").run(
+      { id_or_name: "Trotec" },
+      ctx
+    )) as { found: boolean; slug: string };
+
+    expect(result).toMatchObject({ found: true, slug: "trotec-speedy-400" });
+  });
+
+  it("says so plainly when there is no such tool", async () => {
+    const result = (await tool("get_tool_details").run(
+      { id_or_name: "no-such-tool-id" },
+      ctx
+    )) as { found: boolean; message: string };
+
+    expect(result.found).toBe(false);
+    expect(result.message).toMatch(/Tool not found: no-such-tool-id/);
+  });
+});
+
+// ── Prompt fragment ────────────────────────────────────────────────
+
+describe("promptFragment", () => {
+  it("lists every catalogue tool with the slug the linking rule tells the model to use", async () => {
+    const tools = await getCatalogTools();
+    const fragment = catalog.promptFragment?.({ tools }) ?? "";
+
+    expect(fragment).toContain("## MakerLab catalog (2 tools)");
+    expect(fragment).toContain("**Form 4** — slug: `form-4`");
+    expect(fragment).toContain("units: Form 4 // A [In Use]");
+  });
+
+  it("names the focused tool and tells the model not to link it", async () => {
+    const tools = await getCatalogTools();
+    const fragment = catalog.promptFragment?.({ tools, focusedTool: tools[0] }) ?? "";
+
+    expect(fragment).toContain("Active tool context");
+    expect(fragment).toContain("already on its page");
+  });
+});
diff --git a/v5/src/lib/capabilities/flags.test.ts b/v5/src/lib/capabilities/flags.test.ts
index 0098fd7..5b7d99b 100644
--- a/v5/src/lib/capabilities/flags.test.ts
+++ b/v5/src/lib/capabilities/flags.test.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 import { http, HttpResponse } from "msw";
 import { server } from "../../../test/msw/server";
 import { DB_IDS } from "../../../test/msw/handlers";
@@ -6,6 +7,9 @@ import { nextCacheMock } from "../../../test/mocks/next-cache";
 // `catalog.ts` (pulled in for tool resolution) imports cacheTag/cacheLife.
 vi.mock("next/cache", () => nextCacheMock());
 
+import { getCatalogTools } from "../catalog";
+import { resetDbForTests } from "../db/client";
+import { DEMO_FORM_4_NOTION_PAGE_ID } from "../db/demo-seed";
 import {
   FLAG_FIELDS,
   MAX_FLAG_TEXT,
@@ -19,11 +23,27 @@ import {
 
 const NOTION = "https://api.notion.com/v1";
 
-// The mock catalog is served whenever the Notion catalog env is incomplete; its
-// first tool is the Form 4. Stubbing only the two flag vars keeps reads on the
-// mock path while the write path is fully configured.
-const FORM_4_ID = "tool-form-4";
+// Reads run against the demo-seeded PGlite database (`DATABASE_URL` unset),
+// which holds the same two tools the mock catalogue used to. The Form 4's
+// catalogue id is a Postgres uuid minted at seed time, so it is resolved rather
+// than hard-coded; the Flags relation needs its *Notion page* id instead.
 const FORM_4_NAME = "Form 4";
+let FORM_4_ID = "";
+
+beforeEach(async () => {
+  vi.stubEnv("DATABASE_URL", "");
+  const tools = await getCatalogTools();
+  FORM_4_ID = tools.find((tool) => tool.slug === "form-4")?.id ?? "";
+});
+
+afterAll(() => {
+  resetDbForTests();
+});
+
+/** The Form 4 as `buildFlagFields` receives it, with its Notion page by default. */
+function flaggedTool(notionPageId: string | null = DEMO_FORM_4_NOTION_PAGE_ID) {
+  return { id: FORM_4_ID, name: FORM_4_NAME, notionPageId };
+}
 
 function stubFlagsEnv() {
   vi.stubEnv("NOTION_API_KEY", "secret_test");
@@ -166,27 +186,34 @@ describe("parseCorrectionReport", () => {
 });
 
 describe("buildFlagFields", () => {
-  const tool = { id: FORM_4_ID, name: FORM_4_NAME };
-
   it("generates the title as '<tool> — <field>' and opens the row as New", () => {
-    const fields = buildFlagFields(report({ field_flagged: "safety_info" }), tool);
+    const fields = buildFlagFields(report({ field_flagged: "safety_info" }), flaggedTool());
     expect(fields.title).toBe(`${FORM_4_NAME} — safety_info`);
     expect(fields.status).toBe("New");
-    expect(fields.tool).toEqual([FORM_4_ID]);
+    // The relation addresses the Notion page, never the Postgres id.
+    expect(fields.tool).toEqual([DEMO_FORM_4_NOTION_PAGE_ID]);
+  });
+
+  it("omits the relation for a tool that never came from Notion", () => {
+    // Notion refuses a relation to a page it cannot find, and the correction
+    // itself is worth more than the link (Article 4).
+    const fields = buildFlagFields(report(), flaggedTool(null));
+    expect(fields.tool).toBeUndefined();
+    expect(fields.title).toBe(`${FORM_4_NAME} — materials`);
   });
 
   it("omits the optional fields when they were not supplied", () => {
-    const fields = buildFlagFields(report(), tool);
+    const fields = buildFlagFields(report(), flaggedTool());
     expect(fields.suggested_fix).toBeUndefined();
     expect(fields.reporter).toBeUndefined();
     expect(fields.reporter_email).toBeUndefined();
   });
 
   it("writes reporter_email only for a signed-in reporter", () => {
-    const anonymous = buildFlagFields(report(), tool);
+    const anonymous = buildFlagFields(report(), flaggedTool());
     expect(anonymous.reporter_email).toBeUndefined();
 
-    const signedIn = buildFlagFields(report(), tool, {
+    const signedIn = buildFlagFields(report(), flaggedTool(), {
       name: "Ada",
       email: "ada@example.edu",
     });
@@ -195,7 +222,7 @@ describe("buildFlagFields", () => {
   });
 
   it("prefers a self-declared name over the session name", () => {
-    const fields = buildFlagFields(report({ reporter: "Grace" }), tool, {
+    const fields = buildFlagFields(report({ reporter: "Grace" }), flaggedTool(), {
       name: "Ada",
       email: "ada@example.edu",
     });
@@ -230,18 +257,20 @@ describe("submitCorrection", () => {
     expect(creates[0].properties).toMatchObject({
       status: { select: { name: "New" } },
       field_flagged: { select: { name: "materials" } },
-      tool: { relation: [{ id: FORM_4_ID }] },
+      tool: { relation: [{ id: DEMO_FORM_4_NOTION_PAGE_ID }] },
     });
   });
 
-  it("resolves the tool by slug as well as by page id", async () => {
+  it("resolves the tool by slug as well as by catalogue id", async () => {
     stubFlagsEnv();
     const creates = capturePageCreates();
 
     const result = await submitCorrection(report({ tool_id: "form-4" }));
 
     expect(result.ok).toBe(true);
-    expect(creates[0].properties.tool).toEqual({ relation: [{ id: FORM_4_ID }] });
+    expect(creates[0].properties.tool).toEqual({
+      relation: [{ id: DEMO_FORM_4_NOTION_PAGE_ID }],
+    });
   });
 
   it("returns unknown_tool without writing anything", async () => {
@@ -317,7 +346,9 @@ describe("report_correction capability tool", () => {
     )) as { success: boolean };
 
     expect(result.success).toBe(true);
-    expect(creates[0].properties.tool).toEqual({ relation: [{ id: FORM_4_ID }] });
+    expect(creates[0].properties.tool).toEqual({
+      relation: [{ id: DEMO_FORM_4_NOTION_PAGE_ID }],
+    });
   });
 
   it("rejects an empty description without calling Notion", async () => {
diff --git a/v5/src/lib/capabilities/flags.ts b/v5/src/lib/capabilities/flags.ts
index 1689c17..7ad36f2 100644
--- a/v5/src/lib/capabilities/flags.ts
+++ b/v5/src/lib/capabilities/flags.ts
@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { getCatalogTools } from "../catalog";
+import { notionPageIdForTool } from "../data/notion-ids";
 import type { FlagFields, FlaggedField } from "../types";
 import type { Capability, CapabilityCtx, CapabilityTool } from "./types";
 
@@ -153,17 +154,22 @@ export function parseCorrectionReport(
  */
 export function buildFlagFields(
   report: CorrectionReport,
-  tool: { id: string; name: string },
+  tool: FlaggedTool,
   identity?: ReporterIdentity
 ): FlagWriteFields {
   const fields: FlagWriteFields = {
     title: `${tool.name} — ${report.field_flagged}`,
-    tool: [tool.id],
     field_flagged: report.field_flagged,
     issue_description: report.issue_description,
     status: "New",
   };
 
+  // The `tool` relation addresses a Notion page, and `tool.id` is a Postgres
+  // uuid since the read path moved (spec §3.10). A tool with no imported page
+  // is filed without the relation rather than with an id Notion would reject:
+  // a correction staff have to match up by title beats one that never arrived.
+  if (tool.notionPageId) fields.tool = [tool.notionPageId];
+
   if (report.suggested_fix) fields.suggested_fix = report.suggested_fix;
 
   const reporter = report.reporter || identity?.name;
@@ -247,11 +253,28 @@ async function createFlagPage(fields: FlagWriteFields): Promise<string> {
 
 // ── Submission (shared by both surfaces) ───────────────────────────
 
-/** Resolve by Notion page id or slug — surfaces disagree about which they hold. */
-async function findTool(toolId: string): Promise<{ id: string; name: string } | null> {
+/**
+ * The tool a report is about, with the Notion page behind it.
+ *
+ * `id` is the catalogue id (a Postgres uuid); `notionPageId` is what the Flags
+ * relation needs, and is null for a tool that never came from Notion.
+ */
+export interface FlaggedTool {
+  id: string;
+  name: string;
+  notionPageId?: string | null;
+}
+
+/** Resolve by catalogue id or slug — surfaces disagree about which they hold. */
+async function findTool(toolId: string): Promise<FlaggedTool | null> {
   const tools = await getCatalogTools();
   const match = tools.find((tool) => tool.id === toolId || tool.slug === toolId);
-  return match ? { id: match.id, name: match.name } : null;
+  if (!match) return null;
+  return {
+    id: match.id,
+    name: match.name,
+    notionPageId: await notionPageIdForTool(match.id),
+  };
 }
 
 /**
diff --git a/v5/src/lib/capabilities/helpers.test.ts b/v5/src/lib/capabilities/helpers.test.ts
new file mode 100644
index 0000000..32564a7
--- /dev/null
+++ b/v5/src/lib/capabilities/helpers.test.ts
@@ -0,0 +1,242 @@
+// @vitest-environment node
+import { eq } from "drizzle-orm";
+import { getDb, resetDbForTests } from "../db/client";
+import { maintenanceLogs, units as unitsTable } from "../db/schema/index";
+import type { MakerLabTool } from "../../components/catalog-types";
+import {
+  buildUnitLookup,
+  findTool,
+  findUnit,
+  recentMaintenance,
+  summarizeTool,
+} from "./helpers";
+
+/**
+ * The shared capability helpers: the pure lookups on fixtures, and
+ * `recentMaintenance` against the demo-seeded PGlite database `getDb()` hands
+ * out when `DATABASE_URL` is unset.
+ */
+
+// ── Fixtures ────────────────────────────────────────────────────────
+
+function makeTool(overrides: Partial<MakerLabTool> = {}): MakerLabTool {
+  return {
+    id: "2a6f0d1e-0000-4000-8000-000000000001",
+    slug: "form-4",
+    name: "Form 4",
+    category: "3D Printing",
+    categorySub: "Resin",
+    location: "MakerLab",
+    zone: "Resin Bench",
+    trainingLevel: "Intermediate",
+    trainingLabel: "Resin handling training required.",
+    status: "In Use",
+    shortDescription: "A resin printer.",
+    description: "A production-grade resin printer.",
+    imageSrc: "/tool-images/Form%204.png",
+    ppe: ["Nitrile gloves"],
+    materials: ["Standard resin"],
+    tags: ["Resin"],
+    emergencyStop: null,
+    useRestrictions: null,
+    mapId: null,
+    notes: null,
+    links: [],
+    units: [
+      {
+        id: "3b7f0d1e-0000-4000-8000-000000000001",
+        name: "Form 4 // A",
+        serial: "ML-F4-001",
+        status: "In Use",
+        condition: "Excellent",
+        location: "Resin Bench",
+        dateAcquired: "2024-08-12",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+const trotec = makeTool({
+  id: "2a6f0d1e-0000-4000-8000-000000000002",
+  slug: "trotec-speedy-400",
+  name: "Trotec Speedy 400",
+  category: "Laser",
+  categorySub: "CO2",
+  location: "Laser Room",
+  zone: "Laser Bay",
+  status: "Available",
+  units: [
+    {
+      id: "3b7f0d1e-0000-4000-8000-000000000002",
+      name: "Trotec Speedy 400",
+      serial: "ML-LSR-400",
+      status: "Available",
+      condition: "Good",
+      location: "Laser Bay",
+      dateAcquired: "2022-04-03",
+    },
+  ],
+});
+
+const catalog = [makeTool(), trotec];
+
+// ── Unit lookup ─────────────────────────────────────────────────────
+
+describe("buildUnitLookup", () => {
+  it("flattens every tool's units, carrying the tool they belong to", () => {
+    const lookup = buildUnitLookup(catalog);
+    expect(lookup).toHaveLength(2);
+    expect(lookup[0]).toMatchObject({
+      label: "Form 4 // A",
+      toolName: "Form 4",
+      toolSlug: "form-4",
+      status: "In Use",
+      condition: "Excellent",
+      serial: "ML-F4-001",
+    });
+  });
+
+  it("is empty for a catalogue whose tools have no units", () => {
+    expect(buildUnitLookup([makeTool({ units: [] })])).toEqual([]);
+  });
+});
+
+describe("findUnit", () => {
+  const lookup = buildUnitLookup(catalog);
+
+  it("prefers an exact, case-insensitive label match", () => {
+    expect(findUnit(lookup, "form 4 // a")?.label).toBe("Form 4 // A");
+  });
+
+  it("falls back to the first substring match", () => {
+    expect(findUnit(lookup, "trotec")?.label).toBe("Trotec Speedy 400");
+  });
+
+  it("returns null for an unknown or empty label", () => {
+    expect(findUnit(lookup, "no-such-unit")).toBeNull();
+    expect(findUnit(lookup, "   ")).toBeNull();
+  });
+});
+
+// ── Tool lookup / summaries ─────────────────────────────────────────
+
+describe("findTool", () => {
+  it("resolves by id, by slug, by exact name, then by partial name", () => {
+    expect(findTool(catalog, catalog[0].id)?.slug).toBe("form-4");
+    expect(findTool(catalog, "trotec-speedy-400")?.name).toBe("Trotec Speedy 400");
+    expect(findTool(catalog, "form 4")?.slug).toBe("form-4");
+    expect(findTool(catalog, "speedy")?.slug).toBe("trotec-speedy-400");
+  });
+
+  it("returns null for an unknown or empty needle", () => {
+    expect(findTool(catalog, "no-such-tool")).toBeNull();
+    expect(findTool(catalog, "")).toBeNull();
+  });
+});
+
+describe("summarizeTool", () => {
+  it("packs the fields a list result needs onto one line", () => {
+    expect(summarizeTool(catalog[0])).toBe(
+      `Form 4 | id: ${catalog[0].id} | 3D Printing > Resin | MakerLab / Resin Bench | training: Intermediate | status: In Use`
+    );
+  });
+});
+
+// ── recentMaintenance (Postgres) ────────────────────────────────────
+
+describe("recentMaintenance", () => {
+  beforeEach(() => {
+    vi.stubEnv("DATABASE_URL", "");
+  });
+
+  afterEach(async () => {
+    const db = await getDb();
+    await db.delete(maintenanceLogs);
+  });
+
+  afterAll(() => {
+    resetDbForTests();
+  });
+
+  async function seededUnitId(label: string): Promise<string> {
+    const db = await getDb();
+    const [row] = await db
+      .select({ id: unitsTable.id })
+      .from(unitsTable)
+      .where(eq(unitsTable.unitLabel, label));
+    return row.id;
+  }
+
+  it("flattens logs to the shape both chat and MCP have always returned", async () => {
+    const id = await seededUnitId("Form 4 // A");
+    const db = await getDb();
+    await db.insert(maintenanceLogs).values({
+      title: "Resin tank cloudy",
+      unitId: id,
+      type: "issue_report",
+      priority: "high",
+      status: "open",
+      description: "The tank film is clouded.",
+      resolution: "Not yet.",
+      dateReported: "2024-09-01",
+      reportedByName: "Ada Lovelace",
+      reportedByEmail: "ada@cornell.edu",
+    });
+
+    const [entry] = await recentMaintenance(id);
+
+    // Exactly six keys — the tool descriptions and prompt fragments say the
+    // model gets type, priority, status, date and description, and nothing in
+    // the richer query module leaks past this boundary.
+    expect(entry).toEqual({
+      title: "Resin tank cloudy",
+      type: "Issue Report",
+      priority: "High",
+      status: "Open",
+      date_reported: "2024-09-01",
+      description: "The tank film is clouded.",
+    });
+  });
+
+  it("caps at the 10 most recent", async () => {
+    const id = await seededUnitId("Form 4 // A");
+    const db = await getDb();
+    await db.insert(maintenanceLogs).values(
+      Array.from({ length: 12 }, (_, i) => ({
+        title: `Issue ${i}`,
+        unitId: id,
+        dateReported: `2024-09-${String(i + 1).padStart(2, "0")}`,
+      }))
+    );
+
+    const entries = await recentMaintenance(id);
+    expect(entries).toHaveLength(10);
+    expect(entries[0].title).toBe("Issue 11");
+  });
+
+  it("resolves to [] for a unit with no history", async () => {
+    expect(await recentMaintenance(await seededUnitId("Trotec Speedy 400"))).toEqual([]);
+  });
+
+  it("resolves to [] and logs rather than failing the tool call when the read throws", async () => {
+    // Replace the query module for this test only, so an unreachable database
+    // is simulated without one going near the network (Article 3).
+    vi.resetModules();
+    vi.doMock("../data/maintenance", () => ({
+      listMaintenanceHistoryForUnit: vi.fn(async () => {
+        throw new Error("The database is unavailable.");
+      }),
+    }));
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const { recentMaintenance: withFailingDb } = await import("./helpers");
+    // The tool still answers, and the failure is visible in the logs rather
+    // than swallowed silently (Article 4).
+    expect(await withFailingDb("3b7f0d1e-0000-4000-8000-000000000001")).toEqual([]);
+    expect(warn).toHaveBeenCalled();
+
+    vi.doUnmock("../data/maintenance");
+    vi.resetModules();
+  });
+});
diff --git a/v5/src/lib/capabilities/helpers.ts b/v5/src/lib/capabilities/helpers.ts
index 07d76c6..8f60102 100644
--- a/v5/src/lib/capabilities/helpers.ts
+++ b/v5/src/lib/capabilities/helpers.ts
@@ -1,4 +1,4 @@
-import { fetchMaintenanceLogsByUnit } from "../notion";
+import { listMaintenanceHistoryForUnit } from "../data/maintenance";
 import type {
   MakerLabTool,
   MakerLabUnit,
@@ -10,8 +10,9 @@ import type {
  * (`app/api/chat/route.ts`) and the MCP route (`app/api/mcp/route.ts`); they are
  * collapsed here so both adapters resolve units and summarize tools identically.
  *
- * Pure data transforms plus one thin Notion read wrapper — server-only via the
- * `../notion` import.
+ * Pure data transforms plus one thin Postgres read wrapper (`../data/maintenance`,
+ * spec §3.10 — the maintenance read left Notion in Phase 2; filing a ticket has
+ * not).
  */
 
 // ── Unit lookup ────────────────────────────────────────────────────
@@ -68,7 +69,7 @@ export function findUnit(
 
 // ── Tool lookup / summaries ────────────────────────────────────────
 
-/** Resolve a tool by Notion page id, slug, exact name, or partial name. */
+/** Resolve a tool by id, slug, exact name, or partial name. */
 export function findTool(
   tools: MakerLabTool[],
   idOrName: string
@@ -109,21 +110,34 @@ export interface MaintenanceEntry {
   description: string;
 }
 
+/** The model sees a recap, not an archive — and the read is bounded to match. */
+const MAX_MAINTENANCE_ENTRIES = 10;
+
 /**
  * Fetch the most recent maintenance logs for a unit (cap 10), flattened to the
- * shape both chat and MCP return. Best-effort: resolves to [] on failure.
+ * shape both chat and MCP return — unchanged from when these rows lived in
+ * Notion, so the tool descriptions and prompt fragments still describe what the
+ * model gets. The query module carries more (resolution, resolved date,
+ * reporter name); this is the subset the assistant has always been given.
+ *
+ * Best-effort: resolves to [] on failure, as it always has. A failure here is
+ * odd — resolving the unit already read the same database — so it is logged
+ * rather than swallowed silently (Article 4).
  */
 export function recentMaintenance(unitId: string): Promise<MaintenanceEntry[]> {
-  return fetchMaintenanceLogsByUnit(unitId)
-    .catch(() => [])
+  return listMaintenanceHistoryForUnit(unitId, { limit: MAX_MAINTENANCE_ENTRIES })
+    .catch((err) => {
+      console.warn("[capabilities] maintenance history unavailable", unitId, err);
+      return [];
+    })
     .then((logs) =>
-      logs.slice(0, 10).map((log) => ({
-        title: log.fields.title,
-        type: log.fields.type || "",
-        priority: log.fields.priority || "",
-        status: log.fields.status || "",
-        date_reported: log.fields.date_reported || "",
-        description: log.fields.description || "",
+      logs.map((log) => ({
+        title: log.title,
+        type: log.type,
+        priority: log.priority,
+        status: log.status,
+        date_reported: log.dateReported,
+        description: log.description,
       }))
     );
 }
diff --git a/v5/src/lib/capabilities/intake.test.ts b/v5/src/lib/capabilities/intake.test.ts
index da8e1f7..df4dbce 100644
--- a/v5/src/lib/capabilities/intake.test.ts
+++ b/v5/src/lib/capabilities/intake.test.ts
@@ -13,7 +13,7 @@ vi.mock("next/cache", () => nextCacheMock());
 
 /**
  * Intake ↔ confidence wiring (confidence spec phases 2, 4 and 5). The catalog
- * read runs against the built-in mock catalog (no `NOTION_*` env is stubbed, so
+ * read runs against the PGlite demo seed (no `DATABASE_URL`, so
  * `getCatalogTools()` never touches the network) and every candidate here
  * carries no resources, so no link verification fetch is made either.
  *
@@ -45,7 +45,7 @@ function toolByName(name: string): CapabilityTool<unknown, unknown> {
   return found;
 }
 
-/** A candidate that matches nothing in the mock catalog. */
+/** A candidate that matches nothing in the demo catalogue. */
 function candidate(over: Partial<ToolCandidate> = {}): ToolCandidate {
   return {
     name: "Zorbex Filament Extruder 9000",
diff --git a/v5/src/lib/capabilities/maintenance.test.ts b/v5/src/lib/capabilities/maintenance.test.ts
index 9d97525..2fcecde 100644
--- a/v5/src/lib/capabilities/maintenance.test.ts
+++ b/v5/src/lib/capabilities/maintenance.test.ts
@@ -1,13 +1,17 @@
+// @vitest-environment node
 import { nextCacheMock } from "../../../test/mocks/next-cache";
+import { getCatalogTools } from "../catalog";
+import { resetDbForTests } from "../db/client";
+import { DEMO_FORM_4_UNIT_NOTION_PAGE_ID } from "../db/demo-seed";
 import type { CapabilityCtx } from "./types";
 import type { Identity } from "../auth/identity";
 
 // `catalog.ts` (pulled in to resolve unit labels) imports cacheTag/cacheLife.
 vi.mock("next/cache", () => nextCacheMock());
 
-// Only the write is mocked; everything else in notion.ts stays real. With the
-// NOTION_* env unset the catalog serves the mock catalog, so no test here needs
-// a network call to resolve "Form 4 // A" (Article 3).
+// Only the write is mocked; everything else in notion.ts stays real. Units are
+// resolved against the demo-seeded PGlite database (`DATABASE_URL` unset), so
+// no test here needs a network call to resolve "Form 4 // A" (Article 3).
 const mocks = vi.hoisted(() => ({ createMaintenanceLog: vi.fn() }));
 vi.mock("../notion", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../notion")>();
@@ -66,10 +70,23 @@ function ticket(id = "ticket-1") {
 }
 
 beforeEach(() => {
+  vi.stubEnv("DATABASE_URL", "");
   createMaintenanceLog.mockReset();
   createMaintenanceLog.mockResolvedValue(ticket());
 });
 
+afterAll(() => {
+  resetDbForTests();
+});
+
+/** The seeded unit behind a label, as the capability resolves it. */
+async function seededUnit(toolName: string) {
+  const tools = await getCatalogTools();
+  const tool = tools.find((t) => t.name === toolName);
+  if (!tool?.units[0]) throw new Error(`No seeded unit for ${toolName}`);
+  return tool.units[0];
+}
+
 describe("report_issue — verified authorship", () => {
   it("records the session's name and email when the student is signed in", async () => {
     const ctx: CapabilityCtx = { identity: signedIn() };
@@ -133,17 +150,39 @@ describe("report_issue — verified authorship", () => {
   });
 
   it("still links a resolved unit and reports the ticket id", async () => {
+    const unit = await seededUnit("Form 4");
+
     const result = (await reportIssue.run(
       issue({ unit_label: "Form 4 // A", priority: "High" }),
       { identity: signedIn() }
     )) as { success: boolean; ticket_id?: string; unit_resolved?: unknown };
 
     expect(result.ticket_id).toBe("ticket-1");
+    // The caller is told the catalogue id — a Postgres uuid, the one every
+    // other capability accepts back.
     expect(result.unit_resolved).toEqual({
-      id: "unit-form-4-a",
+      id: unit.id,
       label: "Form 4 // A",
     });
-    expect(writtenFields().unit).toEqual(["unit-form-4-a"]);
+    // The Notion relation is the imported page id, not the uuid: Notion rejects
+    // a relation to a page it cannot find.
+    expect(writtenFields().unit).toEqual([DEMO_FORM_4_UNIT_NOTION_PAGE_ID]);
+  });
+
+  it("files the ticket unlinked when the unit never came from Notion", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const unit = await seededUnit("Trotec Speedy 400");
+
+    const result = (await reportIssue.run(
+      issue({ unit_label: "Trotec Speedy 400" }),
+      {}
+    )) as { success: boolean; ticket_id?: string; unit_resolved?: unknown };
+
+    // The resolution still happened and is reported; only the relation is gone.
+    expect(result.success).toBe(true);
+    expect(result.unit_resolved).toEqual({ id: unit.id, label: "Trotec Speedy 400" });
+    expect(writtenFields().unit).toBeUndefined();
+    expect(warn).toHaveBeenCalled();
   });
 });
 
diff --git a/v5/src/lib/capabilities/maintenance.ts b/v5/src/lib/capabilities/maintenance.ts
index ea27987..bbde95b 100644
--- a/v5/src/lib/capabilities/maintenance.ts
+++ b/v5/src/lib/capabilities/maintenance.ts
@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { getCatalogTools } from "../catalog";
+import { notionPageIdForUnit } from "../data/notion-ids";
 import { createMaintenanceLog } from "../notion";
 import type { MaintenanceLogFields, MaintenanceLogRecord } from "../types";
 import { buildUnitLookup, findUnit } from "./helpers";
@@ -88,6 +89,18 @@ const reportIssue: CapabilityTool<ReportIssueInput, ReportIssueResult> = {
     const tools = await getCatalogTools();
     const unitLookup = buildUnitLookup(tools);
     const match = unit_label ? findUnit(unitLookup, unit_label) : null;
+    // The `unit` relation addresses a Notion page; `match.id` is the Postgres
+    // uuid the catalogue now hands out (spec §3.10). A unit with no imported
+    // page is linked in the description-by-title sense only — the ticket is
+    // filed either way, because Notion rejects a relation to a page it cannot
+    // find and a rejected write loses the student's report (Article 4).
+    const unitPageId = match ? await notionPageIdForUnit(match.id) : null;
+    if (match && !unitPageId) {
+      console.warn(
+        "[maintenance] no Notion page for unit — filing the ticket unlinked",
+        match.label
+      );
+    }
     try {
       const record = await createTicket({
         title,
@@ -102,7 +115,7 @@ const reportIssue: CapabilityTool<ReportIssueInput, ReportIssueResult> = {
         // Server-resolved only. There is no input field for this, and there is
         // deliberately no path that would let one exist.
         reporter_email: ctx.identity?.email || undefined,
-        unit: match ? [match.id] : undefined,
+        unit: unitPageId ? [unitPageId] : undefined,
         date_reported: new Date().toISOString().split("T")[0],
         photo_uploads: photo_uploads?.length ? photo_uploads : undefined,
       });
diff --git a/v5/src/lib/capabilities/types.ts b/v5/src/lib/capabilities/types.ts
index 4774a75..fa9d6fc 100644
--- a/v5/src/lib/capabilities/types.ts
+++ b/v5/src/lib/capabilities/types.ts
@@ -61,7 +61,7 @@ export interface CapabilityCtx {
   attachments?: UploadedImage[];
   /** Response/UI locale, e.g. "en" / "es". */
   locale?: string;
-  /** Notion page id of the tool the user is currently viewing, if any. */
+  /** Catalogue id (a Postgres uuid) of the tool the user is viewing, if any. */
   focusedToolId?: string;
   /**
    * Who is making this request, resolved **server-side** from the session
diff --git a/v5/src/lib/capabilities/units.test.ts b/v5/src/lib/capabilities/units.test.ts
new file mode 100644
index 0000000..b08f289
--- /dev/null
+++ b/v5/src/lib/capabilities/units.test.ts
@@ -0,0 +1,209 @@
+// @vitest-environment node
+// `nextCacheMock` is imported first on purpose: `vi.mock` is hoisted above
+// every import, and its factory can only reach a module imported before the one
+// it replaces.
+import { nextCacheMock } from "../../../test/mocks/next-cache";
+import { eq } from "drizzle-orm";
+import { getDb, resetDbForTests } from "../db/client";
+import { maintenanceLogs, units as unitsTable } from "../db/schema/index";
+import type { CapabilityCtx, CapabilityTool } from "./types";
+import { units } from "./units";
+
+vi.mock("next/cache", () => nextCacheMock());
+
+/**
+ * The `units` capability against the demo-seeded PGlite database `getDb()`
+ * hands out when `DATABASE_URL` is unset — the substrate the whole suite runs
+ * on. The seed's two units are `Form 4 // A` and `Trotec Speedy 400`; the
+ * maintenance logs each test needs are written here, since the seed has none.
+ */
+
+const ctx: CapabilityCtx = {};
+
+function tool(name: string): CapabilityTool {
+  const found = units.tools.find((t) => t.name === name);
+  if (!found) throw new Error(`No such tool: ${name}`);
+  return found;
+}
+
+async function unitId(label: string): Promise<string> {
+  const db = await getDb();
+  const [row] = await db
+    .select({ id: unitsTable.id })
+    .from(unitsTable)
+    .where(eq(unitsTable.unitLabel, label));
+  return row.id;
+}
+
+/** Write a log against a seeded unit. Stored values are snake_case (spec §4.1). */
+async function logIssue(label: string, values: Partial<typeof maintenanceLogs.$inferInsert>) {
+  const db = await getDb();
+  await db.insert(maintenanceLogs).values({
+    title: "Issue",
+    unitId: await unitId(label),
+    ...values,
+  });
+}
+
+beforeEach(() => {
+  vi.stubEnv("DATABASE_URL", "");
+});
+
+afterEach(async () => {
+  // These tests write; the catalogue rows they read are the seed's and are left
+  // alone, so only the logs need clearing between tests.
+  const db = await getDb();
+  await db.delete(maintenanceLogs);
+});
+
+afterAll(() => {
+  resetDbForTests();
+});
+
+// ── get_unit_details ───────────────────────────────────────────────
+
+describe("get_unit_details", () => {
+  it("resolves a seeded unit and derives its status and condition", async () => {
+    const result = (await tool("get_unit_details").run(
+      { unit_label: "Form 4 // A" },
+      ctx
+    )) as Record<string, unknown>;
+
+    expect(result).toMatchObject({
+      found: true,
+      unit_label: "Form 4 // A",
+      tool_name: "Form 4",
+      tool_slug: "form-4",
+      // Stored `in_use` / `excellent`, shown as the display forms the view
+      // models have always carried.
+      status: "In Use",
+      condition: "Excellent",
+      serial: "ML-F4-001",
+      date_acquired: "2024-08-12",
+      detail_page: "/tools/form-4",
+      maintenance_logs: [],
+    });
+    expect(result.unit_id).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it("matches a unit by a case-insensitive substring of its label", async () => {
+    const result = (await tool("get_unit_details").run(
+      { unit_label: "trotec" },
+      ctx
+    )) as Record<string, unknown>;
+    expect(result).toMatchObject({ found: true, unit_label: "Trotec Speedy 400" });
+  });
+
+  it("returns { found:false } with sample labels for an unknown unit", async () => {
+    const result = (await tool("get_unit_details").run(
+      { unit_label: "no-such-unit" },
+      ctx
+    )) as { found: boolean; message: string };
+
+    expect(result.found).toBe(false);
+    expect(result.message).toMatch(/Form 4 \/\/ A|Trotec Speedy 400/);
+  });
+
+  it("surfaces the unit's maintenance history in display form", async () => {
+    await logIssue("Form 4 // A", {
+      title: "Resin tank cloudy",
+      type: "issue_report",
+      priority: "high",
+      status: "in_progress",
+      description: "The tank film is clouded.",
+      dateReported: "2024-09-01",
+    });
+
+    const result = (await tool("get_unit_details").run(
+      { unit_label: "Form 4 // A" },
+      ctx
+    )) as { maintenance_logs: Record<string, string>[] };
+
+    expect(result.maintenance_logs).toEqual([
+      {
+        title: "Resin tank cloudy",
+        type: "Issue Report",
+        priority: "High",
+        status: "In Progress",
+        date_reported: "2024-09-01",
+        description: "The tank film is clouded.",
+      },
+    ]);
+  });
+
+  it("reads another unit's logs as that unit's, not this one's", async () => {
+    await logIssue("Trotec Speedy 400", { title: "Lens dirty" });
+
+    const result = (await tool("get_unit_details").run(
+      { unit_label: "Form 4 // A" },
+      ctx
+    )) as { maintenance_logs: unknown[] };
+    expect(result.maintenance_logs).toEqual([]);
+  });
+});
+
+// ── get_maintenance_history ────────────────────────────────────────
+
+describe("get_maintenance_history", () => {
+  it("returns the unit's logs, newest first and capped at 10", async () => {
+    for (let i = 0; i < 12; i += 1) {
+      await logIssue("Form 4 // A", {
+        title: `Issue ${i}`,
+        dateReported: `2024-09-${String(i + 1).padStart(2, "0")}`,
+      });
+    }
+
+    const result = (await tool("get_maintenance_history").run(
+      { unit_label: "Form 4 // A" },
+      ctx
+    )) as { found: boolean; maintenance_logs: { title: string }[] };
+
+    expect(result.found).toBe(true);
+    expect(result.maintenance_logs).toHaveLength(10);
+    expect(result.maintenance_logs[0].title).toBe("Issue 11");
+  });
+
+  it("never puts the reporter's email in front of the model (spec §8)", async () => {
+    await logIssue("Form 4 // A", {
+      title: "Resin leak",
+      reportedByName: "Ada Lovelace",
+      reportedByEmail: "ada@cornell.edu",
+    });
+
+    const result = await tool("get_maintenance_history").run(
+      { unit_label: "Form 4 // A" },
+      ctx
+    );
+    expect(JSON.stringify(result)).not.toContain("cornell.edu");
+  });
+
+  it("returns an empty history for a unit with no logs", async () => {
+    const result = (await tool("get_maintenance_history").run(
+      { unit_label: "Trotec Speedy 400" },
+      ctx
+    )) as { found: boolean; maintenance_logs: unknown[] };
+
+    expect(result.found).toBe(true);
+    expect(result.maintenance_logs).toEqual([]);
+  });
+
+  it("returns { found:false } for an unknown unit", async () => {
+    const result = (await tool("get_maintenance_history").run(
+      { unit_label: "no-such-unit-999" },
+      ctx
+    )) as { found: boolean; message: string };
+
+    expect(result.found).toBe(false);
+    expect(result.message).toMatch(/No unit found matching "no-such-unit-999"/);
+  });
+});
+
+// ── Prompt fragment ────────────────────────────────────────────────
+
+describe("promptFragment", () => {
+  it("still describes both tools, which is what they do", () => {
+    const fragment = units.promptFragment?.({ tools: [] }) ?? "";
+    expect(fragment).toContain("get_unit_details");
+    expect(fragment).toContain("get_maintenance_history");
+  });
+});
diff --git a/v5/src/lib/catalog.test.ts b/v5/src/lib/catalog.test.ts
index 323e9dc..ebc8ad9 100644
--- a/v5/src/lib/catalog.test.ts
+++ b/v5/src/lib/catalog.test.ts
@@ -1,524 +1,189 @@
-import { http, HttpResponse } from "msw";
-
-import { server } from "../../test/msw/server";
-import { DB_IDS } from "../../test/msw/handlers";
-import {
-  categoriesPage,
-  locationsPage,
-  notionQueryResponse,
-  resourcesPage,
-  toolsPage,
-  unitsPage,
-  selectProp,
-  relationProp,
-  titleProp,
-  richTextProp,
-  checkboxProp,
-  multiSelectProp,
-  filesProp,
-  externalFile,
-  hostedFile,
-  urlProp,
-  STALE_IMAGE_URL,
-  FRESH_IMAGE_URL,
-  type NotionPageFixture,
-} from "../../test/fixtures/notion";
+// @vitest-environment node
+// `nextCacheMock` is imported first on purpose: `vi.mock` is hoisted above
+// every import, and its factory can only reach a module imported before the one
+// it replaces.
 import { nextCacheMock } from "../../test/mocks/next-cache";
+import { cacheLife, cacheTag } from "next/cache";
+import { CATALOG_CACHE } from "./cache";
+import { getCatalogStats, getCatalogTool, getCatalogTools, isDemoCatalog } from "./catalog";
+import { getDb, resetDbForTests } from "./db/client";
+import { tools } from "./db/schema/index";
 
 vi.mock("next/cache", () => nextCacheMock());
 
-// ── Helpers ─────────────────────────────────────────────────────────
-
-function stubNotionEnv() {
-  vi.stubEnv("NOTION_API_KEY", "secret_test");
-  vi.stubEnv("NOTION_DB_TOOLS", DB_IDS.tools);
-  vi.stubEnv("NOTION_DB_CATEGORIES", DB_IDS.categories);
-  vi.stubEnv("NOTION_DB_LOCATIONS", DB_IDS.locations);
-  vi.stubEnv("NOTION_DB_UNITS", DB_IDS.units);
-  vi.stubEnv("NOTION_DB_RESOURCES", DB_IDS.resources);
-  vi.stubEnv("NOTION_DB_MAINTENANCE_LOGS", DB_IDS.maintenance_logs);
-  vi.stubEnv("NOTION_DB_FLAGS", DB_IDS.flags);
-}
-
-function unsetNotionEnv() {
-  vi.stubEnv("NOTION_API_KEY", "");
-  vi.stubEnv("NOTION_DB_TOOLS", "");
-  vi.stubEnv("NOTION_DB_CATEGORIES", "");
-  vi.stubEnv("NOTION_DB_LOCATIONS", "");
-  vi.stubEnv("NOTION_DB_UNITS", "");
-  vi.stubEnv("NOTION_DB_RESOURCES", "");
-  vi.stubEnv("NOTION_DB_MAINTENANCE_LOGS", "");
-  vi.stubEnv("NOTION_DB_FLAGS", "");
-}
-
-// Route the standard catalog DBs to a custom set of pages. tools / categories /
-// locations / units / resources can each be overridden; anything else returns
-// empty. Used to drive status + training-level derivation through the real path.
-function routeCatalog(opts: {
-  tools?: NotionPageFixture[];
-  categories?: NotionPageFixture[];
-  locations?: NotionPageFixture[];
-  units?: NotionPageFixture[];
-  resources?: NotionPageFixture[];
-}) {
-  const byId: Record<string, NotionPageFixture[]> = {
-    [DB_IDS.tools]: opts.tools ?? [toolsPage],
-    [DB_IDS.categories]: opts.categories ?? [categoriesPage],
-    [DB_IDS.locations]: opts.locations ?? [locationsPage],
-    [DB_IDS.units]: opts.units ?? [unitsPage],
-    [DB_IDS.resources]: opts.resources ?? [resourcesPage],
-  };
-  server.use(
-    http.post("https://api.notion.com/v1/databases/:id/query", ({ params }) => {
-      const id = params.id as string;
-      return HttpResponse.json(notionQueryResponse(byId[id] ?? []));
-    })
-  );
-}
-
-// Reset modules + re-import so catalog.ts re-reads process.env at module load.
-async function importCatalog() {
-  vi.resetModules();
-  return import("@/lib/catalog");
-}
-
-// ── hasNotionCatalogEnv ─────────────────────────────────────────────
-
-describe("hasNotionCatalogEnv", () => {
-  it("returns true when all NOTION_* vars are set", async () => {
-    stubNotionEnv();
-    const { hasNotionCatalogEnv } = await importCatalog();
-    expect(hasNotionCatalogEnv()).toBe(true);
-  });
-
-  it("returns false when any NOTION_* var is missing", async () => {
-    stubNotionEnv();
-    vi.stubEnv("NOTION_DB_UNITS", "");
-    const { hasNotionCatalogEnv } = await importCatalog();
-    expect(hasNotionCatalogEnv()).toBe(false);
-  });
+/**
+ * The catalogue against the demo-seeded PGlite database `getDb()` hands out
+ * when `DATABASE_URL` is unset — the same substrate the test suite, E2E and a
+ * fresh clone run on. The seed is two tools, so these assertions are about the
+ * wiring and the derivation, not about the lab's real inventory.
+ */
 
-  it("returns false when NOTION_API_KEY is missing", async () => {
-    stubNotionEnv();
-    vi.stubEnv("NOTION_API_KEY", "");
-    const { hasNotionCatalogEnv } = await importCatalog();
-    expect(hasNotionCatalogEnv()).toBe(false);
-  });
+beforeEach(() => {
+  vi.stubEnv("DATABASE_URL", "");
 });
 
-// ── getCatalogTools — mock fallback ─────────────────────────────────
-
-describe("getCatalogTools (mock fallback)", () => {
-  it("returns the built-in mockTools when Notion env is unset", async () => {
-    unsetNotionEnv();
-    const catalog = await importCatalog();
-    const { mockTools } = await import("@/components/mock-catalog");
-
-    const tools = await catalog.getCatalogTools();
-    expect(tools).toBe(mockTools);
-    expect(tools.map((t) => t.slug)).toEqual(["form-4", "trotec-speedy-400"]);
-  });
+// One in-process database for the file: nothing here writes, so there is
+// nothing to isolate between tests, and a fresh PGlite per test would pay for
+// the migrations every time.
+afterAll(() => {
+  resetDbForTests();
 });
 
-// ── getCatalogTools — real Notion path ──────────────────────────────
-
-describe("getCatalogTools (Notion path)", () => {
-  it("resolves tools from Notion fixtures", async () => {
-    stubNotionEnv();
-    const { getCatalogTools } = await importCatalog();
+// ── getCatalogTools ─────────────────────────────────────────────────
 
-    const tools = await getCatalogTools();
-    expect(tools).toHaveLength(1);
-
-    const [tool] = tools;
-    expect(tool.id).toBe("tool-1");
-    expect(tool.slug).toBe("tool-1");
-    expect(tool.name).toBe("Form 4");
-    // category resolved via relation -> categoriesPage
-    expect(tool.category).toBe("3D Printing");
-    expect(tool.categorySub).toBe("Resin");
-    // location resolved via relation -> locationsPage
-    expect(tool.location).toBe("MakerLab");
-    expect(tool.zone).toBe("Resin Bench");
-    expect(tool.materials).toEqual(["Standard resin", "Tough resin"]);
-    expect(tool.ppe).toEqual(["Nitrile gloves", "Safety glasses"]);
-    // The first image_attachment is the stale airtable host; pickFreshImageUrl
-    // only inspects the *first* attachment's own url candidates and rejects it,
-    // so image_url is null and toMakerLabTool falls back to the local path.
-    expect(tool.imageSrc).toBe("/tool-images/Form%204.png");
-    // mapId from resolved location.id
-    expect(tool.mapId).toBe("ML-RESIN-01");
+describe("getCatalogTools", () => {
+  it("returns the seeded catalogue ordered by name", async () => {
+    const catalog = await getCatalogTools();
+    expect(catalog.map((tool) => tool.slug)).toEqual(["form-4", "trotec-speedy-400"]);
   });
 
-  it("keeps a fresh first-attachment image url and drops a stale one", async () => {
-    stubNotionEnv();
-    const freshFirst: NotionPageFixture = {
-      ...toolsPage,
-      properties: {
-        ...toolsPage.properties,
-        image_attachments: filesProp([externalFile("fresh.png", FRESH_IMAGE_URL)]),
-      },
-    };
-    const staleFirst: NotionPageFixture = {
-      ...toolsPage,
-      properties: {
-        ...toolsPage.properties,
-        image_attachments: filesProp([externalFile("stale.png", STALE_IMAGE_URL)]),
-      },
-    };
-
-    routeCatalog({ tools: [freshFirst] });
-    const fresh = await importCatalog();
-    expect((await fresh.getCatalogTools())[0].imageSrc).toBe(FRESH_IMAGE_URL);
-
-    routeCatalog({ tools: [staleFirst] });
-    const stale = await importCatalog();
-    // stale first-attachment rejected -> local fallback
-    expect((await stale.getCatalogTools())[0].imageSrc).toBe("/tool-images/Form%204.png");
+  it("resolves a tool's category, location and map tag through the joins", async () => {
+    const [form4] = await getCatalogTools();
+    expect(form4).toMatchObject({
+      name: "Form 4",
+      category: "3D Printing",
+      categorySub: "Resin",
+      location: "MakerLab",
+      zone: "Resin Bench",
+      mapId: "ML-RESIN-01",
+    });
+    expect(form4.id).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it("derives status from the units' stored snake_case values", async () => {
+    const [form4, trotec] = await getCatalogTools();
+    // The Form 4's one unit is `in_use`; the Trotec's is `available`, so its
+    // status falls through to the tool's training gate.
+    expect(form4.status).toBe("In Use");
+    expect(form4.units[0]).toMatchObject({
+      name: "Form 4 // A",
+      serial: "ML-F4-001",
+      status: "In Use",
+      condition: "Excellent",
+      location: "Resin Bench",
+      dateAcquired: "2024-08-12",
+    });
+    expect(trotec.status).toBe("Training Required");
+    expect(trotec.units[0]).toMatchObject({ status: "Available", condition: "Good" });
   });
 
-  it("attaches the unit grouped by tool id", async () => {
-    stubNotionEnv();
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.units).toHaveLength(1);
-    expect(tool.units[0].name).toBe("Form 4 #1");
-    expect(tool.units[0].serial).toBe("ML-F4-001");
+  it("derives the training level from the restrictions and tags", async () => {
+    const [form4, trotec] = await getCatalogTools();
+    expect(form4.trainingLevel).toBe("Intermediate");
+    expect(form4.trainingLabel).toBe("Resin handling training required before first print.");
+    // "Authorized" is one of the Trotec's tags.
+    expect(trotec.trainingLevel).toBe("Advanced");
   });
 
-  it("falls back to mockTools and warns when the fetch errors (500)", async () => {
-    stubNotionEnv();
-    server.use(
-      http.post("https://api.notion.com/v1/databases/:id/query", () =>
-        HttpResponse.json({ message: "boom" }, { status: 500 })
-      )
-    );
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const catalog = await importCatalog();
-    const { mockTools } = await import("@/components/mock-catalog");
-
-    const tools = await catalog.getCatalogTools();
-    expect(tools).toBe(mockTools);
-    expect(warn).toHaveBeenCalledWith(
-      "Falling back to mock catalog:",
-      expect.anything()
-    );
+  it("falls back to the bundled photo when no attachment carries one", async () => {
+    const [form4, trotec] = await getCatalogTools();
+    expect(form4.imageSrc).toBe("/tool-images/Form%204.png");
+    // The Trotec's bundled image does not match its name, so the seed gives it
+    // an attachment and the catalogue uses that URL as-is.
+    expect(trotec.imageSrc).toBe("/tool-images/Trotec Speedy 400, 80w.png");
   });
-});
-
-// ── getCatalogTool(id) ──────────────────────────────────────────────
-
-describe("getCatalogTool", () => {
-  it("returns the tool found via the Notion path by id", async () => {
-    stubNotionEnv();
-    const { getCatalogTool } = await importCatalog();
 
-    const tool = await getCatalogTool("tool-1");
-    expect(tool).not.toBeNull();
-    expect(tool?.name).toBe("Form 4");
-    expect(tool?.units).toHaveLength(1);
+  it("attaches each tool's resource links", async () => {
+    const [form4] = await getCatalogTools();
+    expect(form4.links.map((link) => link.label)).toEqual([
+      "Form 4 SOP",
+      "Resin handling safety",
+    ]);
+    expect(form4.links[0].kind).toBe("SOP");
   });
 
-  it("returns null when the id is not found via the Notion path", async () => {
-    stubNotionEnv();
-    const { getCatalogTool } = await importCatalog();
+  it("leaves a draft or archived tool out of the catalogue", async () => {
+    const db = await getDb();
+    await db
+      .insert(tools)
+      .values([
+        { slug: "draft-tool", name: "Draft tool", published: false },
+        { slug: "archived-tool", name: "Archived tool", published: true, archivedAt: new Date() },
+      ])
+      .onConflictDoNothing();
 
-    const tool = await getCatalogTool("does-not-exist");
-    expect(tool).toBeNull();
+    const slugs = (await getCatalogTools()).map((tool) => tool.slug);
+    expect(slugs).not.toContain("draft-tool");
+    expect(slugs).not.toContain("archived-tool");
   });
+});
 
-  it("resolves a tool by slug from the mock catalog when env is unset", async () => {
-    unsetNotionEnv();
-    const { getCatalogTool } = await importCatalog();
+// ── getCatalogTool ──────────────────────────────────────────────────
 
+describe("getCatalogTool", () => {
+  it("resolves a slug", async () => {
     const tool = await getCatalogTool("trotec-speedy-400");
     expect(tool?.name).toBe("Trotec Speedy 400");
   });
 
-  it("returns null for an unknown slug in the mock fallback", async () => {
-    unsetNotionEnv();
-    const { getCatalogTool } = await importCatalog();
+  it("resolves the Postgres uuid capabilities pass back as tool.id", async () => {
+    const [form4] = await getCatalogTools();
+    const tool = await getCatalogTool(form4.id);
+    expect(tool?.slug).toBe("form-4");
+  });
 
+  it("returns null for an unknown slug or uuid", async () => {
     expect(await getCatalogTool("nope")).toBeNull();
+    expect(await getCatalogTool("11111111-2222-3333-4444-555555555555")).toBeNull();
   });
 });
 
 // ── getCatalogStats ─────────────────────────────────────────────────
 
 describe("getCatalogStats", () => {
-  it("counts tools in inventory and reports lab hours (mock path)", async () => {
-    unsetNotionEnv();
-    const { getCatalogStats } = await importCatalog();
-
+  it("counts the published tools and reports lab hours", async () => {
     const stats = await getCatalogStats();
     expect(stats.toolsInInventory).toBe(2);
     expect(stats.labHours).toBe("LAB OPEN 9AM-9PM");
   });
-
-  it("counts tools resolved from the Notion path", async () => {
-    stubNotionEnv();
-    const { getCatalogStats } = await importCatalog();
-
-    const stats = await getCatalogStats();
-    expect(stats.toolsInInventory).toBe(1);
-  });
-});
-
-// ── Status derivation ───────────────────────────────────────────────
-
-describe("status derivation (via Notion path)", () => {
-  const toolNoTraining: NotionPageFixture = {
-    ...toolsPage,
-    properties: { ...toolsPage.properties, training_required: checkboxProp(false) },
-  };
-
-  function unit(id: string, status: string): NotionPageFixture {
-    return {
-      object: "page",
-      id,
-      created_time: "2024-08-12T10:00:00.000Z",
-      last_edited_time: "2024-08-12T10:00:00.000Z",
-      properties: {
-        unit_label: titleProp(`Unit ${id}`),
-        tool: relationProp(["tool-1"]),
-        status: selectProp(status),
-        condition: selectProp("Good"),
-      },
-    };
-  }
-
-  it('derives "In Use" when any unit is In Use', async () => {
-    stubNotionEnv();
-    routeCatalog({ units: [unit("u1", "Available"), unit("u2", "In Use")] });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.status).toBe("In Use");
-  });
-
-  it('derives "Offline" when all units are Offline (Out of Service)', async () => {
-    stubNotionEnv();
-    routeCatalog({ units: [unit("u1", "Out of Service"), unit("u2", "Retired")] });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.status).toBe("Offline");
-  });
-
-  it('derives "Training Required" when training_required and no units gate it', async () => {
-    stubNotionEnv();
-    // toolsPage has training_required: true; give it no units so unit-based
-    // status does not apply.
-    routeCatalog({ tools: [toolsPage], units: [] });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.status).toBe("Training Required");
-  });
-
-  it('derives "Available" when no training required and no gating units', async () => {
-    stubNotionEnv();
-    routeCatalog({ tools: [toolNoTraining], units: [] });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.status).toBe("Available");
-  });
 });
 
-// ── Training level / label derivation ───────────────────────────────
-
-describe("training level + label derivation (via Notion path)", () => {
-  function toolWith(props: Record<string, unknown>): NotionPageFixture {
-    return { ...toolsPage, properties: { ...toolsPage.properties, ...props } };
-  }
-
-  it('derives "Advanced" when restrictions mention "authorized"', async () => {
-    stubNotionEnv();
-    routeCatalog({
-      tools: [toolWith({ use_restrictions: richTextProp("Authorized users only.") })],
-      units: [],
-    });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.trainingLevel).toBe("Advanced");
-    // training_required true + use_restrictions set -> label is the restriction
-    expect(tool.trainingLabel).toBe("Authorized users only.");
-  });
+// ── Caching and the substrate ───────────────────────────────────────
 
-  it('derives "Advanced" when a tag contains "advanced"', async () => {
-    stubNotionEnv();
-    routeCatalog({
-      tools: [
-        toolWith({
-          use_restrictions: richTextProp(""),
-          tags: multiSelectProp(["Advanced", "Laser"]),
-        }),
-      ],
-      units: [],
-    });
-    const { getCatalogTools } = await importCatalog();
+describe("caching", () => {
+  it("tags every read `catalog` and gives it the long catalogue lifetime", async () => {
+    vi.mocked(cacheTag).mockClear();
+    vi.mocked(cacheLife).mockClear();
 
-    const [tool] = await getCatalogTools();
-    expect(tool.trainingLevel).toBe("Advanced");
-  });
+    await getCatalogTools();
+    await getCatalogTool("form-4");
+    await getCatalogStats();
 
-  it('derives "Intermediate" when training_required and no advanced keyword', async () => {
-    stubNotionEnv();
-    // toolsPage: training_required true, restrictions "Resin handling..." (no
-    // advanced/authorized keyword), tags Resin/SLA.
-    routeCatalog({ tools: [toolsPage], units: [] });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.trainingLevel).toBe("Intermediate");
-    expect(tool.trainingLabel).toBe("Resin handling training required.");
-  });
-
-  it('derives "Beginner" when no training required and no keywords', async () => {
-    stubNotionEnv();
-    routeCatalog({
-      tools: [
-        toolWith({
-          training_required: checkboxProp(false),
-          use_restrictions: richTextProp(""),
-          tags: multiSelectProp(["Resin"]),
-        }),
-      ],
-      units: [],
-    });
-    const { getCatalogTools } = await importCatalog();
-
-    const [tool] = await getCatalogTools();
-    expect(tool.trainingLevel).toBe("Beginner");
-    expect(tool.trainingLabel).toBe("Beginner orientation");
+    expect(vi.mocked(cacheTag).mock.calls).toEqual([["catalog"], ["catalog"], ["catalog"]]);
+    expect(vi.mocked(cacheLife)).toHaveBeenCalledWith(CATALOG_CACHE);
   });
 });
 
-// ── resourceLinks ───────────────────────────────────────────────────
-
-describe("resourceLinks (via Notion path)", () => {
-  it("emits a url link plus a link per file attachment", async () => {
-    stubNotionEnv();
-    // Default resourcesPage: url + 2 files (external pdf + hosted png).
-    const { getCatalogTool } = await importCatalog();
-
-    const tool = await getCatalogTool("tool-1");
-    expect(tool).not.toBeNull();
-
-    const links = tool!.links;
-    // 1 url link + 2 file links
-    expect(links).toHaveLength(3);
-
-    const urlLink = links.find((l) => l.href === "https://example.com/form4-sop");
-    expect(urlLink).toMatchObject({ label: "Form 4 SOP", kind: "SOP" });
-
-    const pdfLink = links.find((l) => l.href === "https://example.com/form4-manual.pdf");
-    expect(pdfLink).toBeDefined();
-    const pngLink = links.find((l) => l.href === "https://files.notion.so/safety.png");
-    expect(pngLink).toBeDefined();
-  });
-
-  it("includes a resource even when published === false (gated by its tool's visibility)", async () => {
-    // Resources are created as drafts alongside the tool; tool-level publishing
-    // already gates the catalog, so a tool's links show with it regardless of
-    // the resource's own published flag.
-    stubNotionEnv();
-    const draftResource: NotionPageFixture = {
-      object: "page",
-      id: "res-draft",
-      created_time: "2024-08-12T10:00:00.000Z",
-      last_edited_time: "2024-08-12T10:00:00.000Z",
-      properties: {
-        title: titleProp("Draft SOP"),
-        tool: relationProp(["tool-1"]),
-        type: selectProp("SOP"),
-        url: urlProp("https://example.com/draft-sop"),
-        files: filesProp([]),
-        published: checkboxProp(false),
-      },
-    };
-    routeCatalog({ resources: [draftResource] });
-    const { getCatalogTool } = await importCatalog();
-
-    const tool = await getCatalogTool("tool-1");
-    expect(tool!.links).toHaveLength(1);
-    expect(tool!.links[0].href).toBe("https://example.com/draft-sop");
-  });
-
-  it("emits only file links when a resource has files but no url", async () => {
-    stubNotionEnv();
-    const filesOnly: NotionPageFixture = {
-      object: "page",
-      id: "res-files-only",
-      created_time: "2024-08-12T10:00:00.000Z",
-      last_edited_time: "2024-08-12T10:00:00.000Z",
-      properties: {
-        title: titleProp("Manual"),
-        tool: relationProp(["tool-1"]),
-        type: selectProp("Manual"),
-        url: urlProp(null),
-        files: filesProp([
-          externalFile("a.pdf", "https://example.com/a.pdf"),
-          hostedFile("b.pdf", "https://files.notion.so/b.pdf"),
-        ]),
-        published: checkboxProp(true),
-      },
-    };
-    routeCatalog({ resources: [filesOnly] });
-    const { getCatalogTool } = await importCatalog();
-
-    const tool = await getCatalogTool("tool-1");
-    expect(tool!.links).toHaveLength(2);
-    expect(tool!.links.every((l) => l.href.endsWith(".pdf"))).toBe(true);
+describe("isDemoCatalog", () => {
+  it("is true on the PGlite demo seed and false once a database is configured", () => {
+    expect(isDemoCatalog()).toBe(true);
+    vi.stubEnv("DATABASE_URL", "postgres://user:pass@example.neon.tech/db");
+    expect(isDemoCatalog()).toBe(false);
   });
 });
 
-// ── units / resources grouping ──────────────────────────────────────
-
-describe("units + resources grouping by tool id", () => {
-  it("only attaches units/resources whose relation points at the tool", async () => {
-    stubNotionEnv();
-
-    const otherUnit: NotionPageFixture = {
-      object: "page",
-      id: "unit-other",
-      created_time: "2024-08-12T10:00:00.000Z",
-      last_edited_time: "2024-08-12T10:00:00.000Z",
-      properties: {
-        unit_label: titleProp("Other unit"),
-        tool: relationProp(["tool-2"]),
-        status: selectProp("Available"),
-        condition: selectProp("Good"),
-      },
-    };
-    const otherResource: NotionPageFixture = {
-      object: "page",
-      id: "res-other",
-      created_time: "2024-08-12T10:00:00.000Z",
-      last_edited_time: "2024-08-12T10:00:00.000Z",
-      properties: {
-        title: titleProp("Other SOP"),
-        tool: relationProp(["tool-2"]),
-        type: selectProp("SOP"),
-        url: urlProp("https://example.com/other"),
-        files: filesProp([]),
-        published: checkboxProp(true),
-      },
-    };
-
-    routeCatalog({
-      units: [unitsPage, otherUnit],
-      resources: [resourcesPage, otherResource],
-    });
-    const { getCatalogTool } = await importCatalog();
-
-    const tool = await getCatalogTool("tool-1");
-    // only the unit/resource pointing at tool-1 are attached
-    expect(tool!.units).toHaveLength(1);
-    expect(tool!.units[0].id).toBe("unit-1");
-    expect(tool!.links.some((l) => l.href.includes("/other"))).toBe(false);
+// ── Failing toward stale, never toward invented data ────────────────
+
+describe("a database failure", () => {
+  afterEach(() => {
+    vi.doUnmock("./data/catalog");
+    vi.resetModules();
+  });
+
+  // Article 4: the old code caught a Notion failure and served the mock
+  // catalogue, so a broken deploy looked healthy and showed equipment the lab
+  // does not own. The error has to reach the page instead.
+  it("propagates instead of falling back to sample data", async () => {
+    vi.resetModules();
+    vi.doMock("./data/catalog", () => ({
+      listCatalogTools: () => Promise.reject(new Error("the database is unavailable")),
+      findToolByIdOrSlug: () => Promise.reject(new Error("the database is unavailable")),
+      countPublishedTools: () => Promise.reject(new Error("the database is unavailable")),
+    }));
+    const catalog = await import("./catalog");
+
+    await expect(catalog.getCatalogTools()).rejects.toThrow("the database is unavailable");
+    await expect(catalog.getCatalogTool("form-4")).rejects.toThrow("the database is unavailable");
+    await expect(catalog.getCatalogStats()).rejects.toThrow("the database is unavailable");
   });
 });
diff --git a/v5/src/lib/catalog.ts b/v5/src/lib/catalog.ts
index ce4034d..56de094 100644
--- a/v5/src/lib/catalog.ts
+++ b/v5/src/lib/catalog.ts
@@ -1,246 +1,59 @@
 import { cacheLife, cacheTag } from "next/cache";
 import { CATALOG_CACHE } from "./cache";
 import {
-  fetchAllCategories,
-  fetchAllLocations,
-  fetchAllResources,
-  fetchAllTools,
-  fetchAllUnits,
-  getNotionEnvContract,
-  resolveTools,
-} from "./notion";
-import type {
-  CategoryRecord,
-  LocationRecord,
-  ResourceRecord,
-  ToolRecord,
-  ToolWithMeta,
-  UnitRecord,
-} from "./types";
-import type {
-  CatalogStats,
-  MakerLabTool,
-  MakerLabUnit,
-  ToolStatus,
-} from "../components/catalog-types";
-import { getToolBySlug, mockTools } from "../components/mock-catalog";
-
-interface FullCatalog {
-  tools: ToolRecord[];
-  categories: CategoryRecord[];
-  locations: LocationRecord[];
-  units: UnitRecord[];
-  resources: ResourceRecord[];
-}
-
-export function hasNotionCatalogEnv(): boolean {
-  return getNotionEnvContract().every((key) => Boolean(process.env[key]));
+  countPublishedTools,
+  findToolByIdOrSlug,
+  listCatalogTools,
+} from "./data/catalog";
+import { dataSubstrate } from "./db/client";
+import type { CatalogStats, MakerLabTool } from "../components/catalog-types";
+
+/**
+ * The catalogue the app reads (spec §3.9, §3.10).
+ *
+ * Three cached entry points over `src/lib/data/catalog.ts`, which holds the SQL
+ * and the row→view mapping. Everything is tagged `catalog`, so a write in a
+ * later phase invalidates the whole catalogue with one `revalidateTag` rather
+ * than waiting out a revalidation window (Article 4).
+ *
+ * There is deliberately no fallback. A Postgres failure propagates and the page
+ * renders its error state: cached pages keep serving, and nothing ever invents
+ * equipment the lab does not own. The demo seed is the substrate when
+ * `DATABASE_URL` is unset, never a rescue when a configured database is down.
+ */
+
+/** True when the catalogue is the built-in demo seed rather than a real database. */
+export function isDemoCatalog(): boolean {
+  return dataSubstrate() === "pglite-demo";
 }
 
-async function fetchFullCatalog(): Promise<FullCatalog> {
+export async function getCatalogTools(): Promise<MakerLabTool[]> {
   "use cache";
   cacheTag("catalog");
   cacheLife(CATALOG_CACHE);
 
-  const [tools, categories, locations, units, resources] = await Promise.all([
-    fetchAllTools(),
-    fetchAllCategories(),
-    fetchAllLocations(),
-    fetchAllUnits(),
-    fetchAllResources(),
-  ]);
-  return { tools, categories, locations, units, resources };
-}
-
-function groupUnitsByTool(units: UnitRecord[]): Map<string, UnitRecord[]> {
-  const map = new Map<string, UnitRecord[]>();
-  for (const unit of units) {
-    for (const toolId of unit.fields.tool || []) {
-      const list = map.get(toolId);
-      if (list) list.push(unit);
-      else map.set(toolId, [unit]);
-    }
-  }
-  return map;
-}
-
-function groupResourcesByTool(resources: ResourceRecord[]): Map<string, ResourceRecord[]> {
-  const map = new Map<string, ResourceRecord[]>();
-  for (const resource of resources) {
-    // Resources are gated by their parent tool's visibility, not their own
-    // `published` flag: the catalog only surfaces published tools, so an
-    // unpublished tool already hides its resources. Filtering resources here too
-    // meant intake-created links (created as drafts alongside the tool) stayed
-    // invisible even after staff published the tool — so we show them with it.
-    for (const toolId of resource.fields.tool || []) {
-      const list = map.get(toolId);
-      if (list) list.push(resource);
-      else map.set(toolId, [resource]);
-    }
-  }
-  return map;
-}
-
-export async function getCatalogTools(): Promise<MakerLabTool[]> {
-  if (!hasNotionCatalogEnv()) return mockTools;
-
-  try {
-    const catalog = await fetchFullCatalog();
-    const resolved = resolveTools(catalog.tools, catalog.categories, catalog.locations);
-    const unitsByTool = groupUnitsByTool(catalog.units);
-    const resourcesByTool = groupResourcesByTool(catalog.resources);
-
-    return resolved.map((tool) =>
-      toMakerLabTool(tool, unitsByTool.get(tool.id) || [], resourcesByTool.get(tool.id) || [])
-    );
-  } catch (error) {
-    console.warn("Falling back to mock catalog:", error);
-    return mockTools;
-  }
+  return listCatalogTools();
 }
 
 export async function getCatalogStats(): Promise<CatalogStats> {
-  const tools = await getCatalogTools();
+  "use cache";
+  cacheTag("catalog");
+  cacheLife(CATALOG_CACHE);
 
   return {
-    toolsInInventory: tools.length,
+    toolsInInventory: await countPublishedTools(),
     labHours: "LAB OPEN 9AM-9PM",
   };
 }
 
-export async function getCatalogTool(id: string): Promise<MakerLabTool | null> {
-  if (!hasNotionCatalogEnv()) {
-    return getToolBySlug(id) || null;
-  }
-
-  try {
-    const catalog = await fetchFullCatalog();
-    const raw = catalog.tools.find((tool) => tool.id === id);
-    if (!raw) return null;
-
-    const [resolved] = resolveTools([raw], catalog.categories, catalog.locations);
-    if (!resolved) return null;
-
-    const units = groupUnitsByTool(catalog.units).get(id) || [];
-    const resources = groupResourcesByTool(catalog.resources).get(id) || [];
-    return toMakerLabTool(resolved, units, resources);
-  } catch (error) {
-    console.warn("Falling back to mock tool:", error);
-    return getToolBySlug(id) || null;
-  }
-}
-
-function toMakerLabTool(
-  tool: ToolWithMeta,
-  units: UnitRecord[],
-  resources: ResourceRecord[] = []
-): MakerLabTool {
-  const mappedUnits = units.map((unit) => toMakerLabUnit(unit, tool));
-  const status = deriveStatus(tool, mappedUnits);
-
-  return {
-    id: tool.id,
-    slug: tool.id,
-    name: tool.name,
-    category: tool.category_group,
-    categorySub: tool.category_sub,
-    location: tool.location_room,
-    zone: tool.location_zone,
-    trainingLevel: deriveTrainingLevel(tool),
-    trainingLabel: deriveTrainingLabel(tool),
-    status,
-    shortDescription: tool.description || "Catalog record pending description.",
-    description: tool.description || "This tool record is available in the MakerLab catalog.",
-    imageSrc: tool.image_url || localToolImage(tool.name),
-    ppe: tool.ppe_required.length ? tool.ppe_required : ["Check posted lab guidance"],
-    materials: tool.materials,
-    tags: tool.tags,
-    emergencyStop: tool.emergency_stop,
-    useRestrictions: tool.use_restrictions,
-    mapId: tool.map_tag,
-    notes: tool.notes,
-    links: resourceLinks(resources),
-    units: mappedUnits,
-  };
-}
-
-function resourceLinks(resources: ResourceRecord[]): MakerLabTool["links"] {
-  return resources.flatMap((resource) => {
-    const fields = resource.fields;
-    const base = {
-      kind: fields.type || "Resource",
-      description: fields.notes || undefined,
-    };
-    const urlLinks = fields.url
-      ? [
-          {
-            label: fields.title || fields.type || "Resource",
-            href: fields.url,
-            ...base,
-          },
-        ]
-      : [];
-    const fileLinks =
-      fields.files?.map((file) => ({
-        label: fields.title || file.filename || fields.type || "Resource",
-        href: file.url,
-        ...base,
-      })) || [];
-
-    return [...urlLinks, ...fileLinks];
-  });
-}
-
-function toMakerLabUnit(unit: UnitRecord, tool: ToolWithMeta): MakerLabUnit {
-  return {
-    id: unit.id,
-    name: unit.fields.unit_label || `${tool.name} // Unit`,
-    serial: unit.fields.serial_number || unit.fields.asset_tag || "Unlisted",
-    status: toToolStatus(unit.fields.status, false),
-    condition: toCondition(unit.fields.condition, unit.fields.status),
-    location: tool.location_zone || tool.location_room || "Unknown",
-    dateAcquired: unit.fields.date_acquired || null,
-  };
-}
-
-function deriveStatus(tool: ToolWithMeta, units: MakerLabUnit[]): ToolStatus {
-  if (units.some((unit) => unit.status === "In Use")) return "In Use";
-  if (units.length > 0 && units.every((unit) => unit.status === "Offline")) return "Offline";
-  return toToolStatus(undefined, tool.training_required);
-}
-
-function toToolStatus(status: string | undefined, trainingRequired: boolean): ToolStatus {
-  if (status === "In Use") return "In Use";
-  if (status === "Under Maintenance" || status === "Out of Service" || status === "Retired") {
-    return "Offline";
-  }
-  if (trainingRequired) return "Training Required";
-  return "Available";
-}
-
-function toCondition(
-  condition: string | undefined,
-  status: string | undefined
-): MakerLabUnit["condition"] {
-  if (status === "Out of Service" || status === "Retired") return "Offline";
-  if (condition === "Needs Repair" || status === "Under Maintenance") return "Service Soon";
-  if (condition === "Excellent" || condition === "Good") return condition;
-  return "Good";
-}
-
-function deriveTrainingLevel(tool: ToolWithMeta): MakerLabTool["trainingLevel"] {
-  const restrictionText = `${tool.use_restrictions || ""} ${tool.tags.join(" ")}`.toLowerCase();
-  if (restrictionText.includes("advanced") || restrictionText.includes("authorized")) return "Advanced";
-  if (tool.training_required) return "Intermediate";
-  return "Beginner";
-}
-
-function deriveTrainingLabel(tool: ToolWithMeta): string {
-  if (!tool.training_required) return "Beginner orientation";
-  if (tool.use_restrictions) return tool.use_restrictions;
-  return `${deriveTrainingLevel(tool)} checkout required`;
-}
+/**
+ * One tool by slug, or by the Postgres uuid capabilities pass back as
+ * `tool.id`. Returns null when neither matches.
+ */
+export async function getCatalogTool(idOrSlug: string): Promise<MakerLabTool | null> {
+  "use cache";
+  cacheTag("catalog");
+  cacheLife(CATALOG_CACHE);
 
-function localToolImage(name: string): string {
-  return `/tool-images/${encodeURIComponent(name.replace(/\//g, "_"))}.png`;
+  return findToolByIdOrSlug(idOrSlug);
 }
diff --git a/v5/src/lib/data/catalog.test.ts b/v5/src/lib/data/catalog.test.ts
new file mode 100644
index 0000000..2b8cb8f
--- /dev/null
+++ b/v5/src/lib/data/catalog.test.ts
@@ -0,0 +1,732 @@
+// @vitest-environment node
+import { createPgliteDb } from "../db/pglite";
+import {
+  attachments,
+  categories,
+  locations,
+  resources,
+  tools,
+  units,
+  UNIT_CONDITION,
+  UNIT_STATUS,
+} from "../db/schema/index";
+import type { Db } from "../db/types";
+import {
+  countPublishedTools,
+  deriveTrainingLabel,
+  deriveTrainingLevel,
+  findToolByIdOrSlug,
+  findToolByNotionPageId,
+  findToolBySlug,
+  indexAttachments,
+  listCatalogTools,
+  localToolImage,
+  resourceLinks,
+  toCondition,
+  toMakerLabUnit,
+  toToolStatus,
+  toolImageSrc,
+  type AttachmentRow,
+  type ResourceRow,
+  type ToolRow,
+  type UnitRow,
+} from "./catalog";
+
+/**
+ * The catalogue read path, against a real (in-process) Postgres with rows this
+ * file inserts — and the row→view mapping on its own, where the derivation
+ * rules are easiest to exercise exhaustively.
+ */
+
+let db: Db;
+
+beforeAll(async () => {
+  db = await createPgliteDb();
+});
+
+beforeEach(async () => {
+  // Every test builds the catalogue it needs. Deleting tools cascades to their
+  // units and resources; attachments are polymorphic and have no foreign key.
+  await db.delete(attachments);
+  await db.delete(tools);
+  await db.delete(categories);
+  await db.delete(locations);
+});
+
+// ── Fixtures ────────────────────────────────────────────────────────
+
+type ToolValues = typeof tools.$inferInsert;
+type UnitValues = typeof units.$inferInsert;
+type ResourceValues = typeof resources.$inferInsert;
+
+async function insertCategory(name: string, group: string | null): Promise<string> {
+  const [row] = await db.insert(categories).values({ name, group }).returning({ id: categories.id });
+  return row.id;
+}
+
+async function insertLocation(
+  room: string,
+  zone: string,
+  mapTag: string | null
+): Promise<string> {
+  const [row] = await db
+    .insert(locations)
+    .values({ room, zone, mapTag })
+    .returning({ id: locations.id });
+  return row.id;
+}
+
+async function insertTool(values: ToolValues): Promise<string> {
+  const [row] = await db
+    .insert(tools)
+    .values({ published: true, ...values })
+    .returning({ id: tools.id });
+  return row.id;
+}
+
+async function insertUnit(values: UnitValues): Promise<string> {
+  const [row] = await db.insert(units).values(values).returning({ id: units.id });
+  return row.id;
+}
+
+async function insertResource(values: ResourceValues): Promise<string> {
+  const [row] = await db.insert(resources).values(values).returning({ id: resources.id });
+  return row.id;
+}
+
+async function insertAttachment(values: {
+  ownerType: string;
+  ownerId: string;
+  position?: number;
+  access?: string;
+  publicUrl?: string | null;
+  originalFilename?: string | null;
+}): Promise<void> {
+  await db.insert(attachments).values({
+    ownerType: values.ownerType,
+    ownerId: values.ownerId,
+    position: values.position ?? 0,
+    blobPathname: `blob/${values.ownerId}/${values.position ?? 0}`,
+    access: values.access ?? "public",
+    publicUrl: values.publicUrl === undefined ? "https://blob.example.com/photo.png" : values.publicUrl,
+    originalFilename: values.originalFilename ?? null,
+  });
+}
+
+/** A published tool with a category, a location, one unit and one resource. */
+async function seedForm4(overrides: Partial<ToolValues> = {}): Promise<string> {
+  const categoryId = await insertCategory("Resin", "3D Printing");
+  const locationId = await insertLocation("MakerLab", "Resin Bench", "ML-RESIN-01");
+  const toolId = await insertTool({
+    slug: "form-4",
+    name: "Form 4",
+    description: "A production-grade resin printer.",
+    categoryId,
+    locationId,
+    materials: ["Standard resin"],
+    ppeRequired: ["Nitrile gloves"],
+    tags: ["Resin", "SLA"],
+    trainingRequired: true,
+    useRestrictions: "Resin handling training required.",
+    emergencyStop: "Lift the lid.",
+    notes: "Ventilation must be running.",
+    ...overrides,
+  });
+  await insertUnit({
+    toolId,
+    unitLabel: "Form 4 // A",
+    serialNumber: "ML-F4-001",
+    status: "in_use",
+    condition: "excellent",
+    dateAcquired: "2024-08-12",
+  });
+  await insertResource({ toolId, title: "Form 4 SOP", type: "SOP", url: "https://example.com/sop" });
+  return toolId;
+}
+
+// ── listCatalogTools ────────────────────────────────────────────────
+
+describe("listCatalogTools", () => {
+  it("maps a tool, its category, location, unit and resource into the view model", async () => {
+    await seedForm4();
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool).toMatchObject({
+      slug: "form-4",
+      name: "Form 4",
+      category: "3D Printing",
+      categorySub: "Resin",
+      location: "MakerLab",
+      zone: "Resin Bench",
+      mapId: "ML-RESIN-01",
+      status: "In Use",
+      trainingLevel: "Intermediate",
+      trainingLabel: "Resin handling training required.",
+      shortDescription: "A production-grade resin printer.",
+      materials: ["Standard resin"],
+      ppe: ["Nitrile gloves"],
+      emergencyStop: "Lift the lid.",
+      notes: "Ventilation must be running.",
+    });
+    expect(tool.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(tool.units).toEqual([
+      {
+        id: expect.any(String),
+        name: "Form 4 // A",
+        serial: "ML-F4-001",
+        status: "In Use",
+        condition: "Excellent",
+        location: "Resin Bench",
+        dateAcquired: "2024-08-12",
+      },
+    ]);
+    expect(tool.links).toEqual([
+      {
+        label: "Form 4 SOP",
+        href: "https://example.com/sop",
+        kind: "SOP",
+        description: undefined,
+      },
+    ]);
+  });
+
+  it("shows published tools only, never drafts or archived ones, ordered by name", async () => {
+    await insertTool({ slug: "zeta", name: "Zeta mill" });
+    await insertTool({ slug: "alpha", name: "Alpha saw" });
+    await insertTool({ slug: "draft", name: "Draft router", published: false });
+    await insertTool({ slug: "gone", name: "Archived lathe", archivedAt: new Date() });
+
+    const names = (await listCatalogTools({ db })).map((tool) => tool.name);
+    expect(names).toEqual(["Alpha saw", "Zeta mill"]);
+  });
+
+  it("includes drafts when the caller asks, but never an archived tool", async () => {
+    await insertTool({ slug: "draft", name: "Draft router", published: false });
+    await insertTool({ slug: "gone", name: "Archived lathe", archivedAt: new Date() });
+
+    const names = (await listCatalogTools({ db, includeDrafts: true })).map((tool) => tool.name);
+    expect(names).toEqual(["Draft router"]);
+  });
+
+  it("falls back to honest placeholders when a tool has no category, location or copy", async () => {
+    await insertTool({ slug: "bare", name: "Bare tool" });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool).toMatchObject({
+      category: "Uncategorized",
+      categorySub: "Other",
+      location: "Unknown",
+      zone: "Unknown",
+      mapId: null,
+      status: "Available",
+      trainingLevel: "Beginner",
+      trainingLabel: "Beginner orientation",
+      shortDescription: "Catalog record pending description.",
+      ppe: ["Check posted lab guidance"],
+      imageSrc: "/tool-images/Bare%20tool.png",
+      units: [],
+      links: [],
+    });
+  });
+
+  it("keeps each tool's units and resources to itself", async () => {
+    const form4 = await seedForm4();
+    const other = await insertTool({ slug: "other", name: "Other tool" });
+    await insertUnit({ toolId: other, unitLabel: "Other // A", status: "available" });
+    await insertResource({ toolId: other, title: "Other SOP", url: "https://example.com/other" });
+
+    const bySlug = new Map((await listCatalogTools({ db })).map((tool) => [tool.slug, tool]));
+    expect(bySlug.get("form-4")?.units.map((unit) => unit.name)).toEqual(["Form 4 // A"]);
+    expect(bySlug.get("form-4")?.links.map((link) => link.href)).toEqual([
+      "https://example.com/sop",
+    ]);
+    expect(bySlug.get("other")?.units.map((unit) => unit.name)).toEqual(["Other // A"]);
+    expect(form4).not.toBe(other);
+  });
+});
+
+// ── Images and links from attachments ───────────────────────────────
+
+describe("attachments", () => {
+  it("uses the lowest-position public photo as the tool image", async () => {
+    const toolId = await seedForm4();
+    await insertAttachment({
+      ownerType: "tool",
+      ownerId: toolId,
+      position: 2,
+      publicUrl: "https://blob.example.com/third.png",
+    });
+    await insertAttachment({
+      ownerType: "tool",
+      ownerId: toolId,
+      position: 1,
+      publicUrl: "https://blob.example.com/first.png",
+    });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.imageSrc).toBe("https://blob.example.com/first.png");
+  });
+
+  it("skips a private photo and falls back to the bundled image", async () => {
+    const toolId = await seedForm4();
+    await insertAttachment({
+      ownerType: "tool",
+      ownerId: toolId,
+      access: "private",
+      publicUrl: "https://blob.example.com/private.png",
+    });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.imageSrc).toBe("/tool-images/Form%204.png");
+  });
+
+  it("emits a link per resource file alongside the resource url", async () => {
+    const toolId = await insertTool({ slug: "laser", name: "Laser" });
+    const resourceId = await insertResource({
+      toolId,
+      title: "Manual",
+      type: "Manual",
+      url: "https://example.com/manual",
+      notes: "Read section 4 first.",
+    });
+    await insertAttachment({
+      ownerType: "resource",
+      ownerId: resourceId,
+      position: 0,
+      publicUrl: "https://blob.example.com/manual.pdf",
+      originalFilename: "manual.pdf",
+    });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.links).toEqual([
+      {
+        label: "Manual",
+        href: "https://example.com/manual",
+        kind: "Manual",
+        description: "Read section 4 first.",
+      },
+      {
+        label: "Manual",
+        href: "https://blob.example.com/manual.pdf",
+        kind: "Manual",
+        description: "Read section 4 first.",
+      },
+    ]);
+  });
+
+  it("shows an unpublished resource, because its tool's visibility already gates it", async () => {
+    const toolId = await insertTool({ slug: "laser", name: "Laser" });
+    await insertResource({
+      toolId,
+      title: "Draft SOP",
+      url: "https://example.com/draft",
+      published: false,
+    });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.links.map((link) => link.href)).toEqual(["https://example.com/draft"]);
+  });
+
+  it("ignores attachments owned by another row entirely", async () => {
+    const toolId = await seedForm4();
+    const other = await insertTool({ slug: "other", name: "Other tool" });
+    await insertAttachment({
+      ownerType: "tool",
+      ownerId: other,
+      publicUrl: "https://blob.example.com/other.png",
+    });
+
+    const bySlug = new Map((await listCatalogTools({ db })).map((tool) => [tool.slug, tool]));
+    expect(bySlug.get("form-4")?.imageSrc).toBe("/tool-images/Form%204.png");
+    expect(bySlug.get("other")?.imageSrc).toBe("https://blob.example.com/other.png");
+    expect(toolId).not.toBe(other);
+  });
+});
+
+// ── Status and condition, from the stored vocabulary ────────────────
+
+describe("unit status and condition from stored values", () => {
+  it.each([
+    ["available", "Available"],
+    ["in_use", "In Use"],
+    ["under_maintenance", "Offline"],
+    ["out_of_service", "Offline"],
+    ["retired", "Offline"],
+  ] as const)("reads unit status %s as %s", async (stored, shown) => {
+    const toolId = await insertTool({ slug: "s", name: "Status tool" });
+    await insertUnit({ toolId, unitLabel: "A", status: stored, condition: "good" });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.units[0].status).toBe(shown);
+  });
+
+  it.each([
+    ["excellent", "Excellent"],
+    ["good", "Good"],
+    ["fair", "Good"],
+    ["new", "Good"],
+    ["needs_repair", "Service Soon"],
+    [null, "Good"],
+  ] as const)("reads unit condition %s as %s", async (stored, shown) => {
+    const toolId = await insertTool({ slug: "c", name: "Condition tool" });
+    await insertUnit({ toolId, unitLabel: "A", status: "available", condition: stored });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.units[0].condition).toBe(shown);
+  });
+
+  it("covers every value the schema allows", () => {
+    // A vocabulary that grows without this module growing with it would show
+    // the new value as "Available" / "Good" without anyone noticing.
+    expect([...UNIT_STATUS]).toEqual([
+      "available",
+      "in_use",
+      "under_maintenance",
+      "out_of_service",
+      "retired",
+    ]);
+    expect([...UNIT_CONDITION]).toEqual(["excellent", "good", "fair", "needs_repair", "new"]);
+  });
+
+  it("lets maintenance and retirement override the stored condition", async () => {
+    const toolId = await insertTool({ slug: "m", name: "Maintenance tool" });
+    await insertUnit({
+      toolId,
+      unitLabel: "A",
+      status: "under_maintenance",
+      condition: "excellent",
+    });
+    await insertUnit({ toolId, unitLabel: "B", status: "retired", condition: "good" });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.units.map((unit) => unit.condition)).toEqual(["Service Soon", "Offline"]);
+  });
+
+  it("falls back to the asset tag, then to Unlisted, for a serial", async () => {
+    const toolId = await insertTool({ slug: "sn", name: "Serial tool" });
+    await insertUnit({ toolId, unitLabel: "A", assetTag: "ASSET-9", status: "available" });
+    await insertUnit({ toolId, unitLabel: "B", status: "available" });
+
+    const [tool] = await listCatalogTools({ db });
+    expect(tool.units.map((unit) => unit.serial)).toEqual(["ASSET-9", "Unlisted"]);
+  });
+});
+
+describe("tool status derivation", () => {
+  it("is In Use when any unit is in use, whatever the others say", async () => {
+    const toolId = await insertTool({ slug: "t", name: "Tool" });
+    await insertUnit({ toolId, unitLabel: "A", status: "available" });
+    await insertUnit({ toolId, unitLabel: "B", status: "in_use" });
+
+    expect((await listCatalogTools({ db }))[0].status).toBe("In Use");
+  });
+
+  it("is Offline when every unit is offline", async () => {
+    const toolId = await insertTool({ slug: "t", name: "Tool" });
+    await insertUnit({ toolId, unitLabel: "A", status: "out_of_service" });
+    await insertUnit({ toolId, unitLabel: "B", status: "retired" });
+
+    expect((await listCatalogTools({ db }))[0].status).toBe("Offline");
+  });
+
+  it("is Training Required when training is required and no unit gates it", async () => {
+    await insertTool({ slug: "t", name: "Tool", trainingRequired: true });
+
+    expect((await listCatalogTools({ db }))[0].status).toBe("Training Required");
+  });
+
+  it("is Available when nothing gates it", async () => {
+    const toolId = await insertTool({ slug: "t", name: "Tool" });
+    await insertUnit({ toolId, unitLabel: "A", status: "available" });
+
+    expect((await listCatalogTools({ db }))[0].status).toBe("Available");
+  });
+});
+
+// ── Lookups ─────────────────────────────────────────────────────────
+
+describe("findToolBySlug", () => {
+  it("resolves a published tool and returns null for an unknown slug", async () => {
+    await seedForm4();
+
+    expect((await findToolBySlug("form-4", { db }))?.name).toBe("Form 4");
+    expect(await findToolBySlug("nope", { db })).toBeNull();
+  });
+
+  it("hides a draft unless the caller passes includeDrafts", async () => {
+    await insertTool({ slug: "draft", name: "Draft router", published: false });
+
+    expect(await findToolBySlug("draft", { db })).toBeNull();
+    expect((await findToolBySlug("draft", { db, includeDrafts: true }))?.name).toBe("Draft router");
+  });
+
+  it("hides an archived tool even with includeDrafts", async () => {
+    await insertTool({ slug: "gone", name: "Archived lathe", archivedAt: new Date() });
+
+    expect(await findToolBySlug("gone", { db, includeDrafts: true })).toBeNull();
+  });
+});
+
+describe("findToolByIdOrSlug", () => {
+  it("resolves the Postgres uuid capabilities pass back as tool.id", async () => {
+    const toolId = await seedForm4();
+
+    expect((await findToolByIdOrSlug(toolId, { db }))?.slug).toBe("form-4");
+  });
+
+  it("resolves a slug", async () => {
+    await seedForm4();
+
+    expect((await findToolByIdOrSlug("form-4", { db }))?.name).toBe("Form 4");
+  });
+
+  it("returns null for an unknown uuid and for free text, without a bad-cast error", async () => {
+    await seedForm4();
+
+    expect(await findToolByIdOrSlug("11111111-2222-3333-4444-555555555555", { db })).toBeNull();
+    expect(await findToolByIdOrSlug("not a tool at all", { db })).toBeNull();
+  });
+});
+
+describe("findToolByNotionPageId", () => {
+  const dashed = "0f5e2c1a-4b6d-4e8f-9a0b-1c2d3e4f5a6b";
+  const compact = "0f5e2c1a4b6d4e8f9a0b1c2d3e4f5a6b";
+
+  it("matches the stored id whether the link carries dashes or not", async () => {
+    await insertTool({ slug: "form-4", name: "Form 4", notionPageId: dashed });
+
+    expect(await findToolByNotionPageId(dashed, { db })).toEqual({ slug: "form-4" });
+    expect(await findToolByNotionPageId(compact, { db })).toEqual({ slug: "form-4" });
+    expect(await findToolByNotionPageId(compact.toUpperCase(), { db })).toEqual({ slug: "form-4" });
+  });
+
+  it("matches an undashed stored id too, since the import is not the only writer", async () => {
+    await insertTool({ slug: "form-4", name: "Form 4", notionPageId: compact });
+
+    expect(await findToolByNotionPageId(dashed, { db })).toEqual({ slug: "form-4" });
+  });
+
+  it("returns null for an unknown id and for a slug", async () => {
+    await seedForm4();
+
+    expect(await findToolByNotionPageId(dashed, { db })).toBeNull();
+    expect(await findToolByNotionPageId("form-4", { db })).toBeNull();
+  });
+});
+
+describe("countPublishedTools", () => {
+  it("counts published, non-archived tools only", async () => {
+    await insertTool({ slug: "a", name: "A" });
+    await insertTool({ slug: "b", name: "B" });
+    await insertTool({ slug: "c", name: "C", published: false });
+    await insertTool({ slug: "d", name: "D", archivedAt: new Date() });
+
+    expect(await countPublishedTools({ db })).toBe(2);
+  });
+
+  it("is 0 on an empty catalogue", async () => {
+    expect(await countPublishedTools({ db })).toBe(0);
+  });
+});
+
+// ── The mapping functions on their own ──────────────────────────────
+
+const toolRow: ToolRow = {
+  id: "tool-id",
+  slug: "form-4",
+  name: "Form 4",
+  description: null,
+  materials: [],
+  ppeRequired: [],
+  tags: [],
+  trainingRequired: false,
+  useRestrictions: null,
+  emergencyStop: null,
+  notes: null,
+  categoryName: null,
+  categoryGroup: null,
+  room: "MakerLab",
+  zone: "Resin Bench",
+  mapTag: null,
+};
+
+const unitRow: UnitRow = {
+  id: "unit-id",
+  toolId: "tool-id",
+  unitLabel: "Form 4 // A",
+  serialNumber: null,
+  assetTag: null,
+  status: "available",
+  condition: null,
+  dateAcquired: null,
+};
+
+function file(overrides: Partial<AttachmentRow> = {}): AttachmentRow {
+  return {
+    ownerType: "tool",
+    ownerId: "tool-id",
+    position: 0,
+    access: "public",
+    publicUrl: "https://blob.example.com/a.png",
+    originalFilename: null,
+    ...overrides,
+  };
+}
+
+describe("toToolStatus", () => {
+  it("maps stored statuses, then falls through to the training gate", () => {
+    expect(toToolStatus("in_use", false)).toBe("In Use");
+    expect(toToolStatus("under_maintenance", false)).toBe("Offline");
+    expect(toToolStatus("out_of_service", false)).toBe("Offline");
+    expect(toToolStatus("retired", false)).toBe("Offline");
+    expect(toToolStatus("available", true)).toBe("Training Required");
+    expect(toToolStatus("available", false)).toBe("Available");
+    expect(toToolStatus(undefined, true)).toBe("Training Required");
+    expect(toToolStatus(null, false)).toBe("Available");
+  });
+
+  it("does not accept the Title-case values Notion used to store", () => {
+    expect(toToolStatus("In Use", false)).toBe("Available");
+    expect(toToolStatus("Out of Service", false)).toBe("Available");
+  });
+});
+
+describe("toCondition", () => {
+  it("lets the status override the condition", () => {
+    expect(toCondition("excellent", "out_of_service")).toBe("Offline");
+    expect(toCondition("excellent", "retired")).toBe("Offline");
+    expect(toCondition("excellent", "under_maintenance")).toBe("Service Soon");
+  });
+
+  it("maps every stored condition", () => {
+    expect(toCondition("excellent", "available")).toBe("Excellent");
+    expect(toCondition("good", "available")).toBe("Good");
+    expect(toCondition("fair", "available")).toBe("Good");
+    expect(toCondition("new", "available")).toBe("Good");
+    expect(toCondition("needs_repair", "available")).toBe("Service Soon");
+    expect(toCondition(null, "available")).toBe("Good");
+  });
+});
+
+describe("toMakerLabUnit", () => {
+  it("names an unlabelled unit after its tool and locates it by zone", () => {
+    const unit = toMakerLabUnit({ ...unitRow, unitLabel: "" }, toolRow);
+    expect(unit.name).toBe("Form 4 // Unit");
+    expect(unit.location).toBe("Resin Bench");
+  });
+
+  it("falls back to the room, then to Unknown, when there is no zone", () => {
+    expect(toMakerLabUnit(unitRow, { ...toolRow, zone: null }).location).toBe("MakerLab");
+    expect(toMakerLabUnit(unitRow, { ...toolRow, zone: null, room: null }).location).toBe("Unknown");
+  });
+});
+
+describe("deriveTrainingLevel / deriveTrainingLabel", () => {
+  it("reads Advanced out of the restrictions or the tags", () => {
+    expect(
+      deriveTrainingLevel({ ...toolRow, useRestrictions: "Authorized users only." })
+    ).toBe("Advanced");
+    expect(deriveTrainingLevel({ ...toolRow, tags: ["Advanced", "Laser"] })).toBe("Advanced");
+  });
+
+  it("is Intermediate when training is required and nothing says advanced", () => {
+    expect(deriveTrainingLevel({ ...toolRow, trainingRequired: true })).toBe("Intermediate");
+  });
+
+  it("is Beginner otherwise", () => {
+    expect(deriveTrainingLevel(toolRow)).toBe("Beginner");
+    expect(deriveTrainingLabel(toolRow)).toBe("Beginner orientation");
+  });
+
+  it("prefers the restriction text as the label, then names the level", () => {
+    expect(
+      deriveTrainingLabel({
+        ...toolRow,
+        trainingRequired: true,
+        useRestrictions: "Resin handling training required.",
+      })
+    ).toBe("Resin handling training required.");
+    expect(deriveTrainingLabel({ ...toolRow, trainingRequired: true })).toBe(
+      "Intermediate checkout required"
+    );
+  });
+});
+
+describe("indexAttachments / toolImageSrc", () => {
+  it("groups by owner and sorts by position, whatever order the rows arrive in", () => {
+    const index = indexAttachments([
+      file({ position: 2, publicUrl: "c.png" }),
+      file({ position: 0, publicUrl: "a.png" }),
+      file({ ownerType: "resource", ownerId: "res-id", publicUrl: "r.png" }),
+      file({ position: 1, publicUrl: "b.png" }),
+    ]);
+
+    expect(index.get("tool:tool-id")?.map((row) => row.publicUrl)).toEqual([
+      "a.png",
+      "b.png",
+      "c.png",
+    ]);
+    expect(index.get("resource:res-id")?.map((row) => row.publicUrl)).toEqual(["r.png"]);
+  });
+
+  it("drops an attachment that is not owned by anything yet", () => {
+    expect(indexAttachments([file({ ownerType: null, ownerId: null })]).size).toBe(0);
+  });
+
+  it("falls back to the bundled photo when there is no public file", () => {
+    expect(toolImageSrc(toolRow, [])).toBe("/tool-images/Form%204.png");
+    expect(toolImageSrc(toolRow, [file({ access: "private" })])).toBe("/tool-images/Form%204.png");
+    expect(toolImageSrc(toolRow, [file({ publicUrl: null })])).toBe("/tool-images/Form%204.png");
+  });
+});
+
+describe("resourceLinks", () => {
+  const resourceRow: ResourceRow = {
+    id: "res-id",
+    toolId: "tool-id",
+    title: "Form 4 SOP",
+    type: "SOP",
+    url: null,
+    notes: null,
+  };
+
+  it("emits nothing for a resource with neither a url nor a file", () => {
+    expect(resourceLinks([resourceRow])).toEqual([]);
+  });
+
+  it("labels a file link with the resource title, then the filename, then the type", () => {
+    const files = indexAttachments([
+      file({ ownerType: "resource", ownerId: "res-id", originalFilename: "sop.pdf" }),
+    ]);
+
+    expect(resourceLinks([resourceRow], files)[0].label).toBe("Form 4 SOP");
+    expect(resourceLinks([{ ...resourceRow, title: "" }], files)[0].label).toBe("sop.pdf");
+    expect(
+      resourceLinks(
+        [{ ...resourceRow, title: "" }],
+        indexAttachments([file({ ownerType: "resource", ownerId: "res-id" })])
+      )[0].label
+    ).toBe("SOP");
+  });
+
+  it("never links a private file", () => {
+    const files = indexAttachments([
+      file({ ownerType: "resource", ownerId: "res-id", access: "private" }),
+    ]);
+    expect(resourceLinks([resourceRow], files)).toEqual([]);
+  });
+
+  it("calls an untyped resource a Resource", () => {
+    const links = resourceLinks([
+      { ...resourceRow, title: "", type: null, url: "https://example.com/x" },
+    ]);
+    expect(links[0]).toMatchObject({ label: "Resource", kind: "Resource" });
+  });
+});
+
+describe("localToolImage", () => {
+  it("encodes the name and keeps a slash out of the path", () => {
+    expect(localToolImage("Form 4")).toBe("/tool-images/Form%204.png");
+    expect(localToolImage("Bantam/Othermill")).toBe("/tool-images/Bantam_Othermill.png");
+  });
+});
diff --git a/v5/src/lib/data/catalog.ts b/v5/src/lib/data/catalog.ts
new file mode 100644
index 0000000..757a0ab
--- /dev/null
+++ b/v5/src/lib/data/catalog.ts
@@ -0,0 +1,476 @@
+import { and, asc, count, eq, inArray, isNotNull, isNull, or, sql, type SQL } from "drizzle-orm";
+import { getDb } from "../db/client.ts";
+import {
+  attachments,
+  categories,
+  locations,
+  resources,
+  tools,
+  units,
+} from "../db/schema/index.ts";
+import type { Db } from "../db/types.ts";
+import { compactNotionId } from "../legacy-id.ts";
+import { isUuid } from "./uuid.ts";
+import type { MakerLabTool, MakerLabUnit, ToolStatus } from "../../components/catalog-types.ts";
+
+/**
+ * The catalogue read path on Postgres (spec §3.10, §4.13).
+ *
+ * `src/lib/catalog.ts` is the cached wrapper the app calls; this module is the
+ * SQL underneath it and the row→view mapping, exported so the derivation rules
+ * can be tested without a database. The view models are unchanged — every
+ * display string (`"In Use"`, `"Service Soon"`, `"Uncategorized"`) is derived
+ * from the stored snake_case vocabulary exactly as `catalog.ts` derived it from
+ * Notion's Title-case select options.
+ *
+ * A catalogue read is four statements whatever the size of the catalogue —
+ * tools with their category and location, then units, resources and
+ * attachments in bulk — never one per tool.
+ *
+ * Relative imports with `.ts` extensions and no `@/` alias, and no
+ * `"server-only"`: `scripts/` loads this module under plain Node.
+ */
+
+/** A `tools` row joined to its category and location. */
+export interface ToolRow {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  materials: string[];
+  ppeRequired: string[];
+  tags: string[];
+  trainingRequired: boolean;
+  useRestrictions: string | null;
+  emergencyStop: string | null;
+  notes: string | null;
+  categoryName: string | null;
+  categoryGroup: string | null;
+  room: string | null;
+  zone: string | null;
+  mapTag: string | null;
+}
+
+/** A `units` row belonging to one tool. */
+export interface UnitRow {
+  id: string;
+  toolId: string | null;
+  unitLabel: string;
+  serialNumber: string | null;
+  assetTag: string | null;
+  status: string;
+  condition: string | null;
+  dateAcquired: string | null;
+}
+
+/** A `resources` row belonging to one tool. */
+export interface ResourceRow {
+  id: string;
+  toolId: string | null;
+  title: string;
+  type: string | null;
+  url: string | null;
+  notes: string | null;
+}
+
+/** An `attachments` row: a file in Blob and the row it hangs off. */
+export interface AttachmentRow {
+  ownerType: string | null;
+  ownerId: string | null;
+  position: number;
+  access: string;
+  publicUrl: string | null;
+  originalFilename: string | null;
+}
+
+/** Attachments grouped by `<owner type>:<owner id>`, each list in position order. */
+export type AttachmentIndex = Map<string, AttachmentRow[]>;
+
+export interface CatalogQueryOptions {
+  /** A handle to use instead of {@link getDb} — tests pass an isolated one. */
+  db?: Db;
+  /** Include unpublished tools. Off by default: the catalogue is published-only. */
+  includeDrafts?: boolean;
+}
+
+// ── Queries ─────────────────────────────────────────────────────────
+
+/** Every published, non-archived tool, ordered by name. */
+export async function listCatalogTools(
+  options: CatalogQueryOptions = {}
+): Promise<MakerLabTool[]> {
+  const db = await resolveDb(options);
+  return loadTools(db, and(...visibility(options)));
+}
+
+/** One tool by slug, or null. Published only unless `includeDrafts` is passed. */
+export async function findToolBySlug(
+  slug: string,
+  options: CatalogQueryOptions = {}
+): Promise<MakerLabTool | null> {
+  const db = await resolveDb(options);
+  const [tool] = await loadTools(db, and(eq(tools.slug, slug), ...visibility(options)));
+  return tool ?? null;
+}
+
+/**
+ * One tool by slug or by Postgres uuid, or null. Capabilities hand `tool.id`
+ * straight back (`get_tool_details`), and the tool route passes a slug, so both
+ * resolve here in a single statement. A value that is neither a uuid nor a
+ * known slug returns null rather than reaching Postgres as a bad uuid cast.
+ */
+export async function findToolByIdOrSlug(
+  idOrSlug: string,
+  options: CatalogQueryOptions = {}
+): Promise<MakerLabTool | null> {
+  const db = await resolveDb(options);
+  const match = isUuid(idOrSlug)
+    ? or(eq(tools.slug, idOrSlug), eq(tools.id, idOrSlug))
+    : eq(tools.slug, idOrSlug);
+  const [tool] = await loadTools(db, and(match, ...visibility(options)));
+  return tool ?? null;
+}
+
+/**
+ * The slug behind a legacy `/tools/<notion-page-id>` link, or null (spec
+ * Goal 2). Dashes and case are normalised on both sides, because the id in a
+ * printed QR label is undashed and the stored one is not.
+ *
+ * Unfiltered by `published` and `archived_at` on purpose: an old link should
+ * land on the tool's current page and let that page decide what to show,
+ * rather than silently 404 at the redirect.
+ */
+export async function findToolByNotionPageId(
+  id: string,
+  options: CatalogQueryOptions = {}
+): Promise<{ slug: string } | null> {
+  const compact = compactNotionId(id);
+  if (!compact) return null;
+
+  const db = await resolveDb(options);
+  const [row] = await db
+    .select({ slug: tools.slug })
+    .from(tools)
+    .where(sql`lower(replace(${tools.notionPageId}, '-', '')) = ${compact}`)
+    .limit(1);
+  return row ?? null;
+}
+
+/** How many tools the catalogue shows — `getCatalogStats().toolsInInventory`. */
+export async function countPublishedTools(options: CatalogQueryOptions = {}): Promise<number> {
+  const db = await resolveDb(options);
+  const [row] = await db
+    .select({ value: count() })
+    .from(tools)
+    .where(and(...visibility(options)));
+  return row?.value ?? 0;
+}
+
+async function resolveDb(options: CatalogQueryOptions): Promise<Db> {
+  return options.db ?? (await getDb());
+}
+
+/** Archived tools are never shown; drafts only when the caller asks. */
+function visibility(options: CatalogQueryOptions): SQL[] {
+  const clauses = [isNull(tools.archivedAt)];
+  if (!options.includeDrafts) clauses.push(eq(tools.published, true));
+  return clauses;
+}
+
+/**
+ * Tools matching `where`, with everything they display. Four statements: the
+ * tools themselves, their units, their resources, and the attachments owned by
+ * either — so the cost of a catalogue page does not grow with the tool count.
+ */
+async function loadTools(db: Db, where: SQL | undefined): Promise<MakerLabTool[]> {
+  const toolRows: ToolRow[] = await db
+    .select({
+      id: tools.id,
+      slug: tools.slug,
+      name: tools.name,
+      description: tools.description,
+      materials: tools.materials,
+      ppeRequired: tools.ppeRequired,
+      tags: tools.tags,
+      trainingRequired: tools.trainingRequired,
+      useRestrictions: tools.useRestrictions,
+      emergencyStop: tools.emergencyStop,
+      notes: tools.notes,
+      categoryName: categories.name,
+      categoryGroup: categories.group,
+      room: locations.room,
+      zone: locations.zone,
+      mapTag: locations.mapTag,
+    })
+    .from(tools)
+    .leftJoin(categories, eq(tools.categoryId, categories.id))
+    .leftJoin(locations, eq(tools.locationId, locations.id))
+    .where(where)
+    .orderBy(asc(tools.name));
+
+  if (toolRows.length === 0) return [];
+  const toolIds = toolRows.map((tool) => tool.id);
+
+  const unitRows: UnitRow[] = await db
+    .select({
+      id: units.id,
+      toolId: units.toolId,
+      unitLabel: units.unitLabel,
+      serialNumber: units.serialNumber,
+      assetTag: units.assetTag,
+      status: units.status,
+      condition: units.condition,
+      dateAcquired: units.dateAcquired,
+    })
+    .from(units)
+    .where(inArray(units.toolId, toolIds))
+    .orderBy(asc(units.unitLabel), asc(units.id));
+
+  // Deliberately not filtered by `resources.published`: resources are created
+  // as drafts alongside their tool, and tool-level publishing already gates the
+  // catalogue. Filtering here too kept intake-created links invisible after
+  // staff published the tool.
+  const resourceRows: ResourceRow[] = await db
+    .select({
+      id: resources.id,
+      toolId: resources.toolId,
+      title: resources.title,
+      type: resources.type,
+      url: resources.url,
+      notes: resources.notes,
+    })
+    .from(resources)
+    .where(inArray(resources.toolId, toolIds))
+    .orderBy(asc(resources.createdAt), asc(resources.title), asc(resources.id));
+
+  const files = indexAttachments(
+    await selectAttachments(
+      db,
+      toolIds,
+      resourceRows.map((resource) => resource.id)
+    )
+  );
+  const unitsByTool = groupByTool(unitRows);
+  const resourcesByTool = groupByTool(resourceRows);
+
+  return toolRows.map((tool) =>
+    toMakerLabTool(tool, unitsByTool.get(tool.id) ?? [], resourcesByTool.get(tool.id) ?? [], files)
+  );
+}
+
+/** Every attachment owned by one of these tools or resources, in position order. */
+async function selectAttachments(
+  db: Db,
+  toolIds: string[],
+  resourceIds: string[]
+): Promise<AttachmentRow[]> {
+  const ownedByTool = toolIds.length
+    ? and(eq(attachments.ownerType, "tool"), inArray(attachments.ownerId, toolIds))
+    : undefined;
+  const ownedByResource = resourceIds.length
+    ? and(eq(attachments.ownerType, "resource"), inArray(attachments.ownerId, resourceIds))
+    : undefined;
+  if (!ownedByTool && !ownedByResource) return [];
+
+  return db
+    .select({
+      ownerType: attachments.ownerType,
+      ownerId: attachments.ownerId,
+      position: attachments.position,
+      access: attachments.access,
+      publicUrl: attachments.publicUrl,
+      originalFilename: attachments.originalFilename,
+    })
+    .from(attachments)
+    .where(and(or(ownedByTool, ownedByResource), isNotNull(attachments.publicUrl)))
+    .orderBy(asc(attachments.position), asc(attachments.id));
+}
+
+function groupByTool<T extends { toolId: string | null }>(rows: T[]): Map<string, T[]> {
+  const map = new Map<string, T[]>();
+  for (const row of rows) {
+    if (!row.toolId) continue;
+    const list = map.get(row.toolId);
+    if (list) list.push(row);
+    else map.set(row.toolId, [row]);
+  }
+  return map;
+}
+
+// ── Row → view model ────────────────────────────────────────────────
+
+export function indexAttachments(rows: AttachmentRow[]): AttachmentIndex {
+  const index: AttachmentIndex = new Map();
+  for (const row of rows) {
+    if (!row.ownerType || !row.ownerId) continue;
+    const key = attachmentKey(row.ownerType, row.ownerId);
+    const list = index.get(key);
+    if (list) list.push(row);
+    else index.set(key, [row]);
+  }
+  // Sorted here rather than trusted from the query, so the first attachment is
+  // the lowest-position one however the rows arrived.
+  for (const list of index.values()) list.sort((a, b) => a.position - b.position);
+  return index;
+}
+
+export function attachmentsFor(
+  index: AttachmentIndex,
+  ownerType: string,
+  ownerId: string
+): AttachmentRow[] {
+  return index.get(attachmentKey(ownerType, ownerId)) ?? [];
+}
+
+function attachmentKey(ownerType: string, ownerId: string): string {
+  return `${ownerType}:${ownerId}`;
+}
+
+export function toMakerLabTool(
+  tool: ToolRow,
+  unitRows: UnitRow[],
+  resourceRows: ResourceRow[] = [],
+  files: AttachmentIndex = new Map()
+): MakerLabTool {
+  const mappedUnits = unitRows.map((unit) => toMakerLabUnit(unit, tool));
+  const status = deriveStatus(tool, mappedUnits);
+
+  return {
+    id: tool.id,
+    slug: tool.slug,
+    name: tool.name,
+    category: tool.categoryGroup || "Uncategorized",
+    categorySub: tool.categoryName || "Other",
+    location: tool.room || "Unknown",
+    zone: tool.zone || "Unknown",
+    trainingLevel: deriveTrainingLevel(tool),
+    trainingLabel: deriveTrainingLabel(tool),
+    status,
+    shortDescription: tool.description || "Catalog record pending description.",
+    description: tool.description || "This tool record is available in the MakerLab catalog.",
+    imageSrc: toolImageSrc(tool, attachmentsFor(files, "tool", tool.id)),
+    ppe: tool.ppeRequired.length ? tool.ppeRequired : ["Check posted lab guidance"],
+    materials: tool.materials,
+    tags: tool.tags,
+    emergencyStop: tool.emergencyStop,
+    useRestrictions: tool.useRestrictions,
+    mapId: tool.mapTag,
+    notes: tool.notes,
+    links: resourceLinks(resourceRows, files),
+    units: mappedUnits,
+  };
+}
+
+/** The tool's first public photo in Blob, or the bundled photo named after it. */
+export function toolImageSrc(tool: Pick<ToolRow, "name">, files: AttachmentRow[]): string {
+  const image = files.find((file) => file.access === "public" && file.publicUrl);
+  return image?.publicUrl || localToolImage(tool.name);
+}
+
+/** A link per resource url, plus one per file the resource owns. */
+export function resourceLinks(
+  resourceRows: ResourceRow[],
+  files: AttachmentIndex = new Map()
+): MakerLabTool["links"] {
+  return resourceRows.flatMap((resource) => {
+    const base = {
+      kind: resource.type || "Resource",
+      description: resource.notes || undefined,
+    };
+    const urlLinks = resource.url
+      ? [
+          {
+            label: resource.title || resource.type || "Resource",
+            href: resource.url,
+            ...base,
+          },
+        ]
+      : [];
+    // A private file has no public URL to link to, and would not be one a
+    // visitor is allowed to open even if it did.
+    const fileLinks = attachmentsFor(files, "resource", resource.id).flatMap((file) =>
+      file.access === "public" && file.publicUrl
+        ? [
+            {
+              label: resource.title || file.originalFilename || resource.type || "Resource",
+              href: file.publicUrl,
+              ...base,
+            },
+          ]
+        : []
+    );
+
+    return [...urlLinks, ...fileLinks];
+  });
+}
+
+export function toMakerLabUnit(
+  unit: UnitRow,
+  tool: Pick<ToolRow, "name" | "room" | "zone">
+): MakerLabUnit {
+  return {
+    id: unit.id,
+    name: unit.unitLabel || `${tool.name} // Unit`,
+    serial: unit.serialNumber || unit.assetTag || "Unlisted",
+    status: toToolStatus(unit.status, false),
+    condition: toCondition(unit.condition, unit.status),
+    location: tool.zone || tool.room || "Unknown",
+    dateAcquired: unit.dateAcquired || null,
+  };
+}
+
+export function deriveStatus(
+  tool: Pick<ToolRow, "trainingRequired">,
+  units: MakerLabUnit[]
+): ToolStatus {
+  if (units.some((unit) => unit.status === "In Use")) return "In Use";
+  if (units.length > 0 && units.every((unit) => unit.status === "Offline")) return "Offline";
+  return toToolStatus(undefined, tool.trainingRequired);
+}
+
+export function toToolStatus(
+  status: string | null | undefined,
+  trainingRequired: boolean
+): ToolStatus {
+  if (status === "in_use") return "In Use";
+  if (status === "under_maintenance" || status === "out_of_service" || status === "retired") {
+    return "Offline";
+  }
+  if (trainingRequired) return "Training Required";
+  return "Available";
+}
+
+export function toCondition(
+  condition: string | null | undefined,
+  status: string | null | undefined
+): MakerLabUnit["condition"] {
+  if (status === "out_of_service" || status === "retired") return "Offline";
+  if (condition === "needs_repair" || status === "under_maintenance") return "Service Soon";
+  if (condition === "excellent") return "Excellent";
+  // `fair`, `new` and an unknown condition all read as Good, as they did when
+  // the same four display values came from Notion's select options.
+  return "Good";
+}
+
+export function deriveTrainingLevel(
+  tool: Pick<ToolRow, "useRestrictions" | "tags" | "trainingRequired">
+): MakerLabTool["trainingLevel"] {
+  const restrictionText = `${tool.useRestrictions || ""} ${tool.tags.join(" ")}`.toLowerCase();
+  if (restrictionText.includes("advanced") || restrictionText.includes("authorized")) {
+    return "Advanced";
+  }
+  if (tool.trainingRequired) return "Intermediate";
+  return "Beginner";
+}
+
+export function deriveTrainingLabel(
+  tool: Pick<ToolRow, "useRestrictions" | "tags" | "trainingRequired">
+): string {
+  if (!tool.trainingRequired) return "Beginner orientation";
+  if (tool.useRestrictions) return tool.useRestrictions;
+  return `${deriveTrainingLevel(tool)} checkout required`;
+}
+
+export function localToolImage(name: string): string {
+  return `/tool-images/${encodeURIComponent(name.replace(/\//g, "_"))}.png`;
+}
diff --git a/v5/src/lib/data/maintenance.test.ts b/v5/src/lib/data/maintenance.test.ts
new file mode 100644
index 0000000..e998cf4
--- /dev/null
+++ b/v5/src/lib/data/maintenance.test.ts
@@ -0,0 +1,193 @@
+// @vitest-environment node
+import { createPgliteDb } from "../db/pglite";
+import { maintenanceLogs, tools, units } from "../db/schema/index";
+import type { Db } from "../db/types";
+import {
+  listMaintenanceHistoryForUnit,
+  toDisplayLabel,
+  toMaintenanceHistoryEntry,
+} from "./maintenance";
+
+/**
+ * Maintenance history against a real (in-process) Postgres, plus the
+ * stored-value → display-string translation on its own.
+ */
+
+let db: Db;
+let unitId: string;
+let otherUnitId: string;
+
+beforeAll(async () => {
+  db = await createPgliteDb();
+});
+
+beforeEach(async () => {
+  await db.delete(maintenanceLogs);
+  // Deleting the tools cascades to their units.
+  await db.delete(tools);
+
+  const [form4] = await db
+    .insert(tools)
+    .values({ slug: "form-4", name: "Form 4", published: true })
+    .returning({ id: tools.id });
+  const [unitA, unitB] = await db
+    .insert(units)
+    .values([
+      { toolId: form4.id, unitLabel: "Form 4 // A" },
+      { toolId: form4.id, unitLabel: "Form 4 // B" },
+    ])
+    .returning({ id: units.id });
+  unitId = unitA.id;
+  otherUnitId = unitB.id;
+});
+
+type LogValues = typeof maintenanceLogs.$inferInsert;
+
+async function insertLog(values: Partial<LogValues> = {}): Promise<void> {
+  await db.insert(maintenanceLogs).values({
+    title: "Resin tank cloudy",
+    unitId,
+    ...values,
+  });
+}
+
+// ── listMaintenanceHistoryForUnit ───────────────────────────────────
+
+describe("listMaintenanceHistoryForUnit", () => {
+  it("returns the unit's logs with the display strings the assistant has always seen", async () => {
+    await insertLog({
+      title: "Resin tank cloudy",
+      type: "issue_report",
+      priority: "high",
+      status: "in_progress",
+      description: "The resin tank film is clouded.",
+      resolution: "Tank swapped.",
+      dateReported: "2024-09-01",
+      dateResolved: "2024-09-03",
+      reportedByName: "Ada Lovelace",
+    });
+
+    const [entry] = await listMaintenanceHistoryForUnit(unitId, { db });
+
+    expect(entry).toMatchObject({
+      title: "Resin tank cloudy",
+      type: "Issue Report",
+      priority: "High",
+      status: "In Progress",
+      description: "The resin tank film is clouded.",
+      resolution: "Tank swapped.",
+      dateReported: "2024-09-01",
+      dateResolved: "2024-09-03",
+      reportedByName: "Ada Lovelace",
+    });
+  });
+
+  it("never returns the reporter's email (spec §8)", async () => {
+    await insertLog({
+      reportedByName: "Ada Lovelace",
+      reportedByEmail: "ada@cornell.edu",
+    });
+
+    const [entry] = await listMaintenanceHistoryForUnit(unitId, { db });
+
+    expect(entry.reportedByName).toBe("Ada Lovelace");
+    // Not "undefined" — the address must not be a key at all, so no caller can
+    // spread it into a prompt or a mirror payload.
+    expect(Object.keys(entry)).not.toContain("reportedByEmail");
+    expect(JSON.stringify(entry)).not.toContain("cornell.edu");
+  });
+
+  it("orders newest first and sorts an undated log last", async () => {
+    await insertLog({ title: "Oldest", dateReported: "2024-01-01" });
+    await insertLog({ title: "Undated", dateReported: null });
+    await insertLog({ title: "Newest", dateReported: "2024-09-01" });
+
+    const titles = (await listMaintenanceHistoryForUnit(unitId, { db })).map(
+      (log) => log.title
+    );
+    expect(titles).toEqual(["Newest", "Oldest", "Undated"]);
+  });
+
+  it("reads only the requested unit's logs", async () => {
+    await insertLog({ title: "Mine" });
+    await insertLog({ title: "Theirs", unitId: otherUnitId });
+
+    const titles = (await listMaintenanceHistoryForUnit(unitId, { db })).map(
+      (log) => log.title
+    );
+    expect(titles).toEqual(["Mine"]);
+  });
+
+  it("bounds the read with `limit`, keeping the most recent", async () => {
+    for (let i = 0; i < 12; i += 1) {
+      await insertLog({ title: `Issue ${i}`, dateReported: `2024-09-${String(i + 1).padStart(2, "0")}` });
+    }
+
+    const logs = await listMaintenanceHistoryForUnit(unitId, { db, limit: 10 });
+    expect(logs).toHaveLength(10);
+    expect(logs[0].title).toBe("Issue 11");
+  });
+
+  it("is empty for a unit with no history", async () => {
+    expect(await listMaintenanceHistoryForUnit(unitId, { db })).toEqual([]);
+  });
+
+  it("is empty for anything that is not a uuid, without querying", async () => {
+    // A unit label that failed to resolve must not reach Postgres as a cast.
+    expect(await listMaintenanceHistoryForUnit("Form 4 // A", { db })).toEqual([]);
+    expect(await listMaintenanceHistoryForUnit("", { db })).toEqual([]);
+  });
+});
+
+// ── Row → entry ─────────────────────────────────────────────────────
+
+describe("toMaintenanceHistoryEntry", () => {
+  it("turns every absent value into an empty string", () => {
+    expect(
+      toMaintenanceHistoryEntry({
+        id: "log-1",
+        title: "Untriaged",
+        type: null,
+        priority: null,
+        status: null,
+        description: null,
+        resolution: null,
+        dateReported: null,
+        dateResolved: null,
+        reportedByName: null,
+      })
+    ).toEqual({
+      id: "log-1",
+      title: "Untriaged",
+      type: "",
+      priority: "",
+      status: "",
+      description: "",
+      resolution: "",
+      dateReported: "",
+      dateResolved: "",
+      reportedByName: "",
+    });
+  });
+});
+
+describe("toDisplayLabel", () => {
+  it("maps every stored maintenance value back to the words Notion showed", () => {
+    expect(toDisplayLabel("issue_report")).toBe("Issue Report");
+    expect(toDisplayLabel("preventive_maintenance")).toBe("Preventive Maintenance");
+    expect(toDisplayLabel("repair")).toBe("Repair");
+    expect(toDisplayLabel("inspection")).toBe("Inspection");
+    expect(toDisplayLabel("calibration")).toBe("Calibration");
+    expect(toDisplayLabel("critical")).toBe("Critical");
+    expect(toDisplayLabel("open")).toBe("Open");
+    expect(toDisplayLabel("in_progress")).toBe("In Progress");
+    expect(toDisplayLabel("resolved")).toBe("Resolved");
+    expect(toDisplayLabel("closed")).toBe("Closed");
+  });
+
+  it("returns an empty string for a missing value", () => {
+    expect(toDisplayLabel(null)).toBe("");
+    expect(toDisplayLabel(undefined)).toBe("");
+    expect(toDisplayLabel("")).toBe("");
+  });
+});
diff --git a/v5/src/lib/data/maintenance.ts b/v5/src/lib/data/maintenance.ts
new file mode 100644
index 0000000..d2b0d46
--- /dev/null
+++ b/v5/src/lib/data/maintenance.ts
@@ -0,0 +1,149 @@
+import { desc, eq, sql } from "drizzle-orm";
+import { getDb } from "../db/client.ts";
+import { maintenanceLogs } from "../db/schema/index.ts";
+import type { Db } from "../db/types.ts";
+import { isUuid } from "./uuid.ts";
+
+/**
+ * Maintenance history reads on Postgres (spec §3.10, §4.8).
+ *
+ * This replaces `fetchMaintenanceLogsByUnit` from `src/lib/notion.ts` behind
+ * the `units` capability. Tickets are still *written* to Notion until Phase 3;
+ * only the read moved.
+ *
+ * Two rules shape what comes back:
+ *
+ * - **Display strings, not stored values.** The column holds `issue_report`;
+ *   the assistant has always seen `"Issue Report"`, and the tool descriptions
+ *   and prompt fragments say so. {@link toDisplayLabel} is the exact inverse of
+ *   the import's `toStoredValue`, so a value that survived the import round
+ *   trips back to the words Notion showed.
+ * - **Never the reporter's email.** `reported_by_email` is set only from a
+ *   resolved session and must not enter a model prompt (spec §8, PII). It is
+ *   not selected here at all, so no caller can leak it by accident.
+ *
+ * Relative imports with `.ts` extensions and no `@/` alias, and no
+ * `"server-only"`: `scripts/` loads these modules under plain Node.
+ */
+
+/** One maintenance log, flattened and translated into display text. */
+export interface MaintenanceHistoryEntry {
+  id: string;
+  title: string;
+  /** `"Issue Report"`, `"Repair"`, … — empty when the log has none. */
+  type: string;
+  /** `"Critical"`, `"High"`, … — empty when the log has none. */
+  priority: string;
+  /** `"Open"`, `"In Progress"`, … — empty when the log has none. */
+  status: string;
+  description: string;
+  resolution: string;
+  dateReported: string;
+  dateResolved: string;
+  /** The reporter's name. Deliberately never their email (spec §8). */
+  reportedByName: string;
+}
+
+export interface MaintenanceQueryOptions {
+  /** A handle to use instead of {@link getDb} — tests pass an isolated one. */
+  db?: Db;
+  /** How many of the most recent logs to read. */
+  limit?: number;
+}
+
+/**
+ * A history is for a person (or a model) to read, not an archive to page
+ * through, so a read is always bounded (Article 4). Callers that show fewer
+ * pass their own, smaller limit.
+ */
+const DEFAULT_LIMIT = 50;
+
+/**
+ * The most recent maintenance logs filed against one unit, newest first.
+ *
+ * Empty for a unit with no history, and for anything that is not a uuid — a
+ * unit label that failed to resolve returns nothing rather than reaching
+ * Postgres as a bad uuid cast.
+ */
+export async function listMaintenanceHistoryForUnit(
+  unitId: string,
+  options: MaintenanceQueryOptions = {}
+): Promise<MaintenanceHistoryEntry[]> {
+  if (!isUuid(unitId)) return [];
+
+  const db = options.db ?? (await getDb());
+  const rows = await db
+    .select({
+      id: maintenanceLogs.id,
+      title: maintenanceLogs.title,
+      type: maintenanceLogs.type,
+      priority: maintenanceLogs.priority,
+      status: maintenanceLogs.status,
+      description: maintenanceLogs.description,
+      resolution: maintenanceLogs.resolution,
+      dateReported: maintenanceLogs.dateReported,
+      dateResolved: maintenanceLogs.dateResolved,
+      reportedByName: maintenanceLogs.reportedByName,
+    })
+    .from(maintenanceLogs)
+    .where(eq(maintenanceLogs.unitId, unitId))
+    // `date_reported` is nullable and most imported logs have one; a log with
+    // no date sorts last rather than ahead of everything, which is where a
+    // descending sort would otherwise put it.
+    .orderBy(
+      sql`${maintenanceLogs.dateReported} desc nulls last`,
+      desc(maintenanceLogs.createdAt)
+    )
+    .limit(options.limit ?? DEFAULT_LIMIT);
+
+  return rows.map(toMaintenanceHistoryEntry);
+}
+
+/** The columns {@link listMaintenanceHistoryForUnit} selects, before translation. */
+export interface MaintenanceLogRow {
+  id: string;
+  title: string;
+  type: string | null;
+  priority: string | null;
+  status: string | null;
+  description: string | null;
+  resolution: string | null;
+  dateReported: string | null;
+  dateResolved: string | null;
+  reportedByName: string | null;
+}
+
+/**
+ * Row → entry. Every absent value becomes `""` rather than null: these strings
+ * are read by a model, and an empty string reads as "not recorded" where a
+ * `null` reads as a value.
+ */
+export function toMaintenanceHistoryEntry(row: MaintenanceLogRow): MaintenanceHistoryEntry {
+  return {
+    id: row.id,
+    title: row.title,
+    type: toDisplayLabel(row.type),
+    priority: toDisplayLabel(row.priority),
+    status: toDisplayLabel(row.status),
+    description: row.description || "",
+    resolution: row.resolution || "",
+    dateReported: row.dateReported || "",
+    dateResolved: row.dateResolved || "",
+    reportedByName: row.reportedByName || "",
+  };
+}
+
+/**
+ * `in_progress` → `"In Progress"`. The inverse of the import's `toStoredValue`,
+ * which lower-cased Notion's option names and turned spaces into underscores,
+ * so every vocabulary value that came through the import maps back to the words
+ * the workspace used.
+ */
+export function toDisplayLabel(value: string | null | undefined): string {
+  if (!value) return "";
+  return value
+    .split("_")
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
diff --git a/v5/src/lib/data/notion-ids.test.ts b/v5/src/lib/data/notion-ids.test.ts
new file mode 100644
index 0000000..43a2b78
--- /dev/null
+++ b/v5/src/lib/data/notion-ids.test.ts
@@ -0,0 +1,140 @@
+// @vitest-environment node
+import { createPgliteDb } from "../db/pglite";
+import { tools, units } from "../db/schema/index";
+import type { Db } from "../db/types";
+import {
+  notionPageIdForTool,
+  notionPageIdForUnit,
+  notionPageIdsForTools,
+} from "./notion-ids";
+import { isUuid } from "./uuid";
+
+/**
+ * The Postgres → Notion page id translation the three remaining Notion writes
+ * depend on, against a real (in-process) Postgres with rows this file inserts.
+ */
+
+let db: Db;
+
+beforeAll(async () => {
+  db = await createPgliteDb();
+});
+
+beforeEach(async () => {
+  await db.delete(tools);
+});
+
+/** One tool, with or without the page id the import would have recorded. */
+async function insertTool(slug: string, notionPageId: string | null): Promise<string> {
+  const [row] = await db
+    .insert(tools)
+    .values({ slug, name: slug, notionPageId })
+    .returning({ id: tools.id });
+  return row.id;
+}
+
+async function insertUnit(toolId: string, notionPageId: string | null): Promise<string> {
+  const [row] = await db
+    .insert(units)
+    .values({ toolId, unitLabel: `${toolId} // A`, status: "available", notionPageId })
+    .returning({ id: units.id });
+  return row.id;
+}
+
+// ── isUuid ──────────────────────────────────────────────────────────
+
+describe("isUuid", () => {
+  it("accepts a uuid in either case and rejects everything else", () => {
+    expect(isUuid("1f2e3d4c-5b6a-4789-8abc-def012345678")).toBe(true);
+    expect(isUuid("1F2E3D4C-5B6A-4789-8ABC-DEF012345678")).toBe(true);
+    expect(isUuid("form-4")).toBe(false);
+    expect(isUuid("Form 4 // A")).toBe(false);
+    expect(isUuid("1f2e3d4c5b6a47898abcdef012345678")).toBe(false);
+    expect(isUuid("")).toBe(false);
+  });
+});
+
+// ── Tools ───────────────────────────────────────────────────────────
+
+describe("notionPageIdForTool", () => {
+  it("returns the page the tool was imported from", async () => {
+    const id = await insertTool("form-4", "notion-tool-1");
+    await expect(notionPageIdForTool(id, { db })).resolves.toBe("notion-tool-1");
+  });
+
+  it("is null for a tool that never came from Notion", async () => {
+    const id = await insertTool("locally-made", null);
+    await expect(notionPageIdForTool(id, { db })).resolves.toBeNull();
+  });
+
+  it("is null for an unknown uuid", async () => {
+    await expect(notionPageIdForTool(crypto.randomUUID(), { db })).resolves.toBeNull();
+  });
+
+  it("is null for a slug or free text, without a bad-cast error", async () => {
+    // A surface may hand this a slug; reaching a uuid column with one throws.
+    await expect(notionPageIdForTool("form-4", { db })).resolves.toBeNull();
+    await expect(notionPageIdForTool("", { db })).resolves.toBeNull();
+  });
+});
+
+// ── Units ───────────────────────────────────────────────────────────
+
+describe("notionPageIdForUnit", () => {
+  it("returns the page the unit was imported from", async () => {
+    const toolId = await insertTool("form-4", "notion-tool-1");
+    const unitId = await insertUnit(toolId, "notion-unit-1");
+
+    await expect(notionPageIdForUnit(unitId, { db })).resolves.toBe("notion-unit-1");
+  });
+
+  it("is null for a unit with no page, so the ticket is filed unlinked", async () => {
+    const toolId = await insertTool("form-4", "notion-tool-1");
+    const unitId = await insertUnit(toolId, null);
+
+    await expect(notionPageIdForUnit(unitId, { db })).resolves.toBeNull();
+  });
+
+  it("is null for a unit label that failed to resolve", async () => {
+    await expect(notionPageIdForUnit("Form 4 // A", { db })).resolves.toBeNull();
+  });
+});
+
+// ── Many tools ──────────────────────────────────────────────────────
+
+describe("notionPageIdsForTools", () => {
+  it("translates each id, in the order it was given", async () => {
+    const first = await insertTool("form-4", "notion-tool-1");
+    const second = await insertTool("trotec", "notion-tool-2");
+
+    await expect(notionPageIdsForTools([second, first], { db })).resolves.toEqual([
+      "notion-tool-2",
+      "notion-tool-1",
+    ]);
+  });
+
+  it("drops ids that do not resolve rather than passing them through", async () => {
+    // One unresolvable relation id fails the whole Notion page, which would
+    // lose the student's submission (Article 4).
+    const known = await insertTool("form-4", "notion-tool-1");
+    const local = await insertTool("locally-made", null);
+
+    await expect(
+      notionPageIdsForTools([known, local, crypto.randomUUID(), "form-4"], { db })
+    ).resolves.toEqual(["notion-tool-1"]);
+  });
+
+  it("is empty for an empty list and for a list with no uuids, without querying", async () => {
+    await expect(notionPageIdsForTools([], { db })).resolves.toEqual([]);
+    await expect(notionPageIdsForTools(["form-4", "trotec"], { db })).resolves.toEqual([]);
+  });
+
+  it("keeps a repeated id as often as it was given", async () => {
+    const id = await insertTool("form-4", "notion-tool-1");
+
+    await expect(notionPageIdsForTools([id, id], { db })).resolves.toEqual([
+      "notion-tool-1",
+      "notion-tool-1",
+    ]);
+  });
+});
diff --git a/v5/src/lib/data/notion-ids.ts b/v5/src/lib/data/notion-ids.ts
new file mode 100644
index 0000000..5cfd6b1
--- /dev/null
+++ b/v5/src/lib/data/notion-ids.ts
@@ -0,0 +1,92 @@
+import { and, eq, inArray, isNotNull } from "drizzle-orm";
+import { getDb } from "../db/client.ts";
+import { tools, units } from "../db/schema/index.ts";
+import type { Db } from "../db/types.ts";
+import { isUuid } from "./uuid.ts";
+
+/**
+ * Postgres row → Notion page id (spec §3.10, §9 Phase 2).
+ *
+ * Reads moved to Postgres in Phase 2; three writes have not yet (a correction,
+ * a maintenance ticket, a project submission). Those still create Notion pages
+ * whose `relation` properties address Notion **page** ids, while every id the
+ * app now hands around — `tool.id`, `unit.id` — is a Postgres uuid. Notion
+ * rejects a relation to a page it cannot find, so without this translation the
+ * whole write fails and the student's report is lost.
+ *
+ * `tools.notion_page_id` and `units.notion_page_id` carry the mapping the
+ * import recorded (spec §4), and this module is the only place that reads it.
+ * A row with no page id — created after the import, or a demo-seed row —
+ * resolves to null, and the caller files the page *without* the relation: a
+ * ticket missing its unit link is recoverable by a human, a ticket Notion
+ * refused is not (Article 4, fail toward stale rather than toward nothing).
+ *
+ * This module moves out with the writes in Phase 3.
+ */
+
+export interface NotionIdOptions {
+  /** A handle to use instead of {@link getDb} — tests pass an isolated one. */
+  db?: Db;
+}
+
+/** The Notion page the tool was imported from, or null. */
+export async function notionPageIdForTool(
+  toolId: string,
+  options: NotionIdOptions = {}
+): Promise<string | null> {
+  if (!isUuid(toolId)) return null;
+
+  const db = await resolveDb(options);
+  const [row] = await db
+    .select({ notionPageId: tools.notionPageId })
+    .from(tools)
+    .where(eq(tools.id, toolId))
+    .limit(1);
+  return row?.notionPageId ?? null;
+}
+
+/** The Notion page the unit was imported from, or null. */
+export async function notionPageIdForUnit(
+  unitId: string,
+  options: NotionIdOptions = {}
+): Promise<string | null> {
+  if (!isUuid(unitId)) return null;
+
+  const db = await resolveDb(options);
+  const [row] = await db
+    .select({ notionPageId: units.notionPageId })
+    .from(units)
+    .where(eq(units.id, unitId))
+    .limit(1);
+  return row?.notionPageId ?? null;
+}
+
+/**
+ * The Notion pages behind a list of tool ids, in the order they were given.
+ * Ids that are not uuids, are unknown, or name a tool that never came from
+ * Notion are dropped rather than passed through — an unresolvable id would
+ * fail the entire write.
+ */
+export async function notionPageIdsForTools(
+  toolIds: string[],
+  options: NotionIdOptions = {}
+): Promise<string[]> {
+  const candidates = toolIds.filter(isUuid);
+  if (candidates.length === 0) return [];
+
+  const db = await resolveDb(options);
+  const rows = await db
+    .select({ id: tools.id, notionPageId: tools.notionPageId })
+    .from(tools)
+    .where(and(inArray(tools.id, candidates), isNotNull(tools.notionPageId)));
+
+  const byId = new Map(rows.map((row) => [row.id, row.notionPageId]));
+  return toolIds.flatMap((id) => {
+    const pageId = byId.get(id);
+    return pageId ? [pageId] : [];
+  });
+}
+
+async function resolveDb(options: NotionIdOptions): Promise<Db> {
+  return options.db ?? (await getDb());
+}
diff --git a/v5/src/lib/data/projects.test.ts b/v5/src/lib/data/projects.test.ts
new file mode 100644
index 0000000..78daaaa
--- /dev/null
+++ b/v5/src/lib/data/projects.test.ts
@@ -0,0 +1,197 @@
+// @vitest-environment node
+import { createPgliteDb } from "../db/pglite";
+import { attachments, projectTools, projects, tools } from "../db/schema/index";
+import type { Db } from "../db/types";
+
+/**
+ * `src/lib/data/projects.ts` calls `getDb()` internally, like every other
+ * query module (spec §3.2 — one entry point, no `Proxy`, no db parameter to
+ * plumb through pages). Tests therefore need `getDb()` itself to resolve to
+ * an isolated, per-test PGlite instance rather than the memoised demo
+ * database — done by mocking `../db/client.ts`, the exact specifier the
+ * module under test imports, and pointing it at a fresh `createPgliteDb()`
+ * before each test.
+ */
+const dbHolder = vi.hoisted(() => ({ current: undefined as Db | undefined }));
+
+vi.mock("../db/client.ts", () => ({
+  getDb: () => Promise.resolve(dbHolder.current),
+}));
+
+import { findPublishedProject, listPublishedProjects, listPublishedProjectsForTool } from "./projects";
+
+async function insertProject(
+  db: Db,
+  overrides: Partial<typeof projects.$inferInsert> = {}
+): Promise<string> {
+  const [row] = await db
+    .insert(projects)
+    .values({
+      slug: `project-${crypto.randomUUID()}`,
+      title: "Untitled project",
+      body: "Body",
+      published: true,
+      ...overrides,
+    })
+    .returning({ id: projects.id });
+  return row.id;
+}
+
+async function insertTool(db: Db, overrides: Partial<typeof tools.$inferInsert> = {}): Promise<string> {
+  const [row] = await db
+    .insert(tools)
+    .values({
+      slug: `tool-${crypto.randomUUID()}`,
+      name: "A tool",
+      published: true,
+      ...overrides,
+    })
+    .returning({ id: tools.id });
+  return row.id;
+}
+
+async function linkTool(db: Db, projectId: string, toolId: string): Promise<void> {
+  await db.insert(projectTools).values({ projectId, toolId });
+}
+
+async function addPhoto(
+  db: Db,
+  projectId: string,
+  overrides: Partial<typeof attachments.$inferInsert> = {}
+): Promise<void> {
+  await db.insert(attachments).values({
+    ownerType: "project",
+    ownerId: projectId,
+    blobPathname: `projects/${projectId}/${crypto.randomUUID()}.png`,
+    access: "public",
+    publicUrl: `https://blob.test/${crypto.randomUUID()}.png`,
+    position: 0,
+    ...overrides,
+  });
+}
+
+describe("src/lib/data/projects.ts", () => {
+  let db: Db;
+
+  beforeEach(async () => {
+    db = await createPgliteDb();
+    dbHolder.current = db;
+  });
+
+  describe("listPublishedProjects", () => {
+    it("returns only published projects, newest first", async () => {
+      await insertProject(db, {
+        title: "Older",
+        createdAt: new Date("2026-01-01T00:00:00.000Z"),
+      });
+      await insertProject(db, { title: "Draft", published: false });
+      await insertProject(db, {
+        title: "Newer",
+        createdAt: new Date("2026-02-01T00:00:00.000Z"),
+      });
+
+      const result = await listPublishedProjects();
+      expect(result.map((project) => project.title)).toEqual(["Newer", "Older"]);
+    });
+
+    it("falls back to Anonymous when author_name is null, and reports the created_at ISO string", async () => {
+      const createdAt = new Date("2026-03-04T12:30:00.000Z");
+      await insertProject(db, { title: "No byline", authorName: null, createdAt });
+
+      const [project] = await listPublishedProjects();
+      expect(project.author).toBe("Anonymous");
+      expect(project.date).toBe(createdAt.toISOString());
+    });
+
+    it("uses the author_name when present", async () => {
+      await insertProject(db, { title: "With byline", authorName: "Ada Lovelace" });
+
+      const [project] = await listPublishedProjects();
+      expect(project.author).toBe("Ada Lovelace");
+    });
+
+    it("orders photos by position, and includes only public attachments owned by the project", async () => {
+      const projectId = await insertProject(db, { title: "Gallery" });
+      await addPhoto(db, projectId, { position: 1, publicUrl: "https://blob.test/second.png" });
+      await addPhoto(db, projectId, { position: 0, publicUrl: "https://blob.test/first.png" });
+      // A private photo (e.g. a re-owned maintenance shot) must never surface.
+      await addPhoto(db, projectId, { position: 2, publicUrl: null, access: "private" });
+      // A public attachment with no URL yet (upload recorded before the blob
+      // finished) is skipped rather than rendered as a broken image.
+      await addPhoto(db, projectId, { position: 3, publicUrl: null, access: "public" });
+
+      const [project] = await listPublishedProjects();
+      expect(project.photos).toEqual(["https://blob.test/first.png", "https://blob.test/second.png"]);
+    });
+
+    it("resolves tool refs to {id,name,slug}, and drops refs to unpublished tools without dropping the project", async () => {
+      const projectId = await insertProject(db, { title: "Built with two" });
+      const published = await insertTool(db, { name: "Form 4", slug: "form-4", published: true });
+      const draft = await insertTool(db, { name: "Secret prototype", slug: "secret-prototype", published: false });
+      await linkTool(db, projectId, published);
+      await linkTool(db, projectId, draft);
+
+      const [project] = await listPublishedProjects();
+      expect(project.tools).toEqual([{ id: published, name: "Form 4", slug: "form-4" }]);
+    });
+  });
+
+  describe("findPublishedProject", () => {
+    it("finds a published project by its uuid id", async () => {
+      const id = await insertProject(db, { title: "By id" });
+
+      const project = await findPublishedProject(id);
+      expect(project?.id).toBe(id);
+      expect(project?.title).toBe("By id");
+    });
+
+    it("finds a published project by its slug", async () => {
+      await insertProject(db, { title: "By slug", slug: "by-slug" });
+
+      const project = await findPublishedProject("by-slug");
+      expect(project?.title).toBe("By slug");
+    });
+
+    it("returns null for an unpublished project, whether looked up by id or by slug", async () => {
+      const id = await insertProject(db, { title: "Draft", slug: "draft-project", published: false });
+
+      expect(await findPublishedProject(id)).toBeNull();
+      expect(await findPublishedProject("draft-project")).toBeNull();
+    });
+
+    it("returns null for an id that does not exist", async () => {
+      expect(await findPublishedProject(crypto.randomUUID())).toBeNull();
+    });
+
+    it("returns null for a slug that does not exist", async () => {
+      expect(await findPublishedProject("no-such-project")).toBeNull();
+    });
+  });
+
+  describe("listPublishedProjectsForTool", () => {
+    it("returns only published projects that reference the given tool", async () => {
+      const toolId = await insertTool(db, { name: "Trotec Speedy 400" });
+      const otherToolId = await insertTool(db, { name: "Form 4" });
+      const built = await insertProject(db, { title: "Laser box" });
+      const other = await insertProject(db, { title: "Printed part" });
+      const draft = await insertProject(db, { title: "Draft laser project", published: false });
+      await linkTool(db, built, toolId);
+      await linkTool(db, other, otherToolId);
+      await linkTool(db, draft, toolId);
+
+      const result = await listPublishedProjectsForTool(toolId);
+      expect(result.map((project) => project.title)).toEqual(["Laser box"]);
+    });
+
+    it("returns an empty array for a tool nothing was built with", async () => {
+      const toolId = await insertTool(db);
+      await insertProject(db, { title: "Unrelated" });
+
+      expect(await listPublishedProjectsForTool(toolId)).toEqual([]);
+    });
+
+    it("returns an empty array instead of throwing when the id is not uuid-shaped", async () => {
+      await expect(listPublishedProjectsForTool("not-a-uuid")).resolves.toEqual([]);
+    });
+  });
+});
diff --git a/v5/src/lib/data/projects.ts b/v5/src/lib/data/projects.ts
new file mode 100644
index 0000000..76dbaa6
--- /dev/null
+++ b/v5/src/lib/data/projects.ts
@@ -0,0 +1,133 @@
+import { and, desc, eq, inArray } from "drizzle-orm";
+import { getDb } from "../db/client.ts";
+import { attachments, projectTools, projects, tools } from "../db/schema/index.ts";
+import type { Db } from "../db/types.ts";
+import { isUuid } from "./uuid.ts";
+import type { MakerLabProject, ProjectToolRef } from "../../components/catalog-types.ts";
+
+/**
+ * Postgres reads for published projects (data platform design spec 2026-09-14
+ * §3.10, §4.10, §4.13). This is the query module `src/lib/projects.ts` wraps
+ * in `"use cache"`; nothing here is cached itself, so every export is a plain
+ * round trip and safe to call as often as the caller needs a fresh answer.
+ *
+ * Imports are relative with `.ts` extensions and skip the `@/` alias, like
+ * everything under `src/lib/db/` and `src/lib/import/`: scripts load these
+ * modules under plain Node type-stripping, which cannot resolve either.
+ *
+ * A project's photos and tool refs are joined in eagerly rather than resolved
+ * lazily per view, because both list views (the gallery, "Built with this")
+ * need the whole set at once and Article 4 prefers one round trip of joins
+ * over N+1 queries.
+ */
+
+type ProjectRow = typeof projects.$inferSelect;
+
+/** Every published project, newest first (spec §4.10). */
+export async function listPublishedProjects(): Promise<MakerLabProject[]> {
+  const db = await getDb();
+  const rows = await db
+    .select()
+    .from(projects)
+    .where(eq(projects.published, true))
+    .orderBy(desc(projects.createdAt));
+  return hydrateProjects(db, rows);
+}
+
+/**
+ * A published project by its uuid id or its slug. Null for an unknown id, a
+ * slug that matches nothing, or a real row that is not published — a draft is
+ * never reachable by guessing its id.
+ */
+export async function findPublishedProject(idOrSlug: string): Promise<MakerLabProject | null> {
+  const db = await getDb();
+  const match = isUuid(idOrSlug) ? eq(projects.id, idOrSlug) : eq(projects.slug, idOrSlug);
+  const rows = await db
+    .select()
+    .from(projects)
+    .where(and(match, eq(projects.published, true)))
+    .limit(1);
+  const [hydrated] = await hydrateProjects(db, rows);
+  return hydrated ?? null;
+}
+
+/** Published projects built with a given tool — the tool page's "Built with this" section. */
+export async function listPublishedProjectsForTool(toolId: string): Promise<MakerLabProject[]> {
+  if (!isUuid(toolId)) return [];
+
+  const db = await getDb();
+  const rows = await db
+    .select({ project: projects })
+    .from(projects)
+    .innerJoin(projectTools, eq(projectTools.projectId, projects.id))
+    .where(and(eq(projectTools.toolId, toolId), eq(projects.published, true)))
+    .orderBy(desc(projects.createdAt));
+  return hydrateProjects(
+    db,
+    rows.map((row) => row.project)
+  );
+}
+
+/** Attaches each row's photos and tool refs, then maps onto the view model. */
+async function hydrateProjects(db: Db, rows: ProjectRow[]): Promise<MakerLabProject[]> {
+  if (rows.length === 0) return [];
+
+  const ids = rows.map((row) => row.id);
+  const [photosByProject, toolsByProject] = await Promise.all([loadPhotos(db, ids), loadToolRefs(db, ids)]);
+
+  return rows.map((row) => toMakerLabProject(row, photosByProject.get(row.id) ?? [], toolsByProject.get(row.id) ?? []));
+}
+
+/** Public attachment URLs owned by these projects, grouped by project id and ordered by `position`. */
+async function loadPhotos(db: Db, projectIds: string[]): Promise<Map<string, string[]>> {
+  const rows = await db
+    .select({ ownerId: attachments.ownerId, publicUrl: attachments.publicUrl })
+    .from(attachments)
+    .where(
+      and(eq(attachments.ownerType, "project"), inArray(attachments.ownerId, projectIds), eq(attachments.access, "public"))
+    )
+    .orderBy(attachments.position);
+
+  const map = new Map<string, string[]>();
+  for (const row of rows) {
+    if (!row.ownerId || !row.publicUrl) continue;
+    const list = map.get(row.ownerId);
+    if (list) list.push(row.publicUrl);
+    else map.set(row.ownerId, [row.publicUrl]);
+  }
+  return map;
+}
+
+/** `{id,name,slug}` for each project's *published* tools, grouped by project id. An archived/draft tool drops the ref, not the project. */
+async function loadToolRefs(db: Db, projectIds: string[]): Promise<Map<string, ProjectToolRef[]>> {
+  const rows = await db
+    .select({ projectId: projectTools.projectId, id: tools.id, name: tools.name, slug: tools.slug })
+    .from(projectTools)
+    .innerJoin(tools, eq(projectTools.toolId, tools.id))
+    .where(and(inArray(projectTools.projectId, projectIds), eq(tools.published, true)))
+    .orderBy(tools.name);
+
+  const map = new Map<string, ProjectToolRef[]>();
+  for (const row of rows) {
+    const ref: ProjectToolRef = { id: row.id, name: row.name, slug: row.slug };
+    const list = map.get(row.projectId);
+    if (list) list.push(ref);
+    else map.set(row.projectId, [ref]);
+  }
+  return map;
+}
+
+function toMakerLabProject(row: ProjectRow, photos: string[], toolRefs: ProjectToolRef[]): MakerLabProject {
+  return {
+    id: row.id,
+    slug: row.slug,
+    title: row.title,
+    author: row.authorName ?? "Anonymous",
+    body: row.body,
+    photos,
+    tools: toolRefs,
+    link: row.link,
+    materials: row.materials,
+    date: row.createdAt.toISOString(),
+  };
+}
diff --git a/v5/src/lib/data/resources.test.ts b/v5/src/lib/data/resources.test.ts
new file mode 100644
index 0000000..0b48efa
--- /dev/null
+++ b/v5/src/lib/data/resources.test.ts
@@ -0,0 +1,141 @@
+// @vitest-environment node
+import { createPgliteDb } from "../db/pglite";
+import { attachments, resources, tools } from "../db/schema/index";
+import type { Db } from "../db/types";
+import { listResources, listResourcesForTool } from "./resources";
+
+/**
+ * Resource reads against a real (in-process) Postgres — what the chat route
+ * needs to decide which of a tool's files are manuals worth attaching.
+ */
+
+let db: Db;
+let form4: string;
+let trotec: string;
+
+beforeAll(async () => {
+  db = await createPgliteDb();
+});
+
+beforeEach(async () => {
+  await db.delete(attachments);
+  // Deleting the tools cascades to their resources.
+  await db.delete(tools);
+
+  const [a, b] = await db
+    .insert(tools)
+    .values([
+      { slug: "form-4", name: "Form 4", published: true },
+      { slug: "trotec-speedy-400", name: "Trotec Speedy 400", published: true },
+    ])
+    .returning({ id: tools.id });
+  form4 = a.id;
+  trotec = b.id;
+});
+
+type ResourceValues = typeof resources.$inferInsert;
+type AttachmentValues = typeof attachments.$inferInsert;
+
+async function insertResource(values: Partial<ResourceValues> = {}): Promise<string> {
+  const [row] = await db
+    .insert(resources)
+    .values({ toolId: form4, title: "Form 4 manual", ...values })
+    .returning({ id: resources.id });
+  return row.id;
+}
+
+async function attachFile(resourceId: string, values: Partial<AttachmentValues> = {}) {
+  await db.insert(attachments).values({
+    ownerType: "resource",
+    ownerId: resourceId,
+    blobPathname: "resources/manual.pdf",
+    access: "public",
+    publicUrl: "https://blob.test/manual.pdf",
+    ...values,
+  });
+}
+
+// ── listResourcesForTool ────────────────────────────────────────────
+
+describe("listResourcesForTool", () => {
+  it("returns the tool's resources with their link and notes", async () => {
+    await insertResource({
+      title: "Form 4 SOP",
+      type: "SOP",
+      url: "https://x.test/sop.pdf",
+      notes: "Read before the first print.",
+    });
+
+    expect(await listResourcesForTool(form4, { db })).toEqual([
+      {
+        id: expect.any(String),
+        toolId: form4,
+        title: "Form 4 SOP",
+        type: "SOP",
+        url: "https://x.test/sop.pdf",
+        notes: "Read before the first print.",
+        fileUrls: [],
+      },
+    ]);
+  });
+
+  it("carries a resource's public files, cover first", async () => {
+    const id = await insertResource({ title: "Manual", url: null });
+    await attachFile(id, { position: 1, publicUrl: "https://blob.test/second.pdf" });
+    await attachFile(id, { position: 0, publicUrl: "https://blob.test/first.pdf" });
+
+    const [resource] = await listResourcesForTool(form4, { db });
+    expect(resource.fileUrls).toEqual([
+      "https://blob.test/first.pdf",
+      "https://blob.test/second.pdf",
+    ]);
+  });
+
+  it("leaves out private files, which no visitor could open either", async () => {
+    const id = await insertResource({ title: "Incident photos", url: null });
+    await attachFile(id, { access: "private", publicUrl: null });
+
+    const [resource] = await listResourcesForTool(form4, { db });
+    expect(resource.fileUrls).toEqual([]);
+  });
+
+  it("leaves out unpublished resources — the assistant must not read what staff hid", async () => {
+    await insertResource({ title: "Draft SOP", published: false });
+    await insertResource({ title: "Live SOP", published: true });
+
+    const titles = (await listResourcesForTool(form4, { db })).map((r) => r.title);
+    expect(titles).toEqual(["Live SOP"]);
+  });
+
+  it("returns only the named tool's resources, ordered by title", async () => {
+    await insertResource({ title: "Zebra chart" });
+    await insertResource({ title: "Alpha guide" });
+    await insertResource({ title: "Trotec SOP", toolId: trotec });
+
+    const titles = (await listResourcesForTool(form4, { db })).map((r) => r.title);
+    expect(titles).toEqual(["Alpha guide", "Zebra chart"]);
+  });
+
+  it("is empty for a tool with no resources, and for anything that is not a uuid", async () => {
+    expect(await listResourcesForTool(trotec, { db })).toEqual([]);
+    expect(await listResourcesForTool("form-4", { db })).toEqual([]);
+  });
+});
+
+// ── listResources ───────────────────────────────────────────────────
+
+describe("listResources", () => {
+  it("returns every published resource in the lab, by title", async () => {
+    await insertResource({ title: "Trotec SOP", toolId: trotec });
+    await insertResource({ title: "Form 4 SOP" });
+    await insertResource({ title: "Hidden", published: false });
+
+    const rows = await listResources({ db });
+    expect(rows.map((r) => r.title)).toEqual(["Form 4 SOP", "Trotec SOP"]);
+    expect(rows.map((r) => r.toolId)).toEqual([form4, trotec]);
+  });
+
+  it("is empty when the lab has no resources", async () => {
+    expect(await listResources({ db })).toEqual([]);
+  });
+});
diff --git a/v5/src/lib/data/resources.ts b/v5/src/lib/data/resources.ts
new file mode 100644
index 0000000..1d8e4a6
--- /dev/null
+++ b/v5/src/lib/data/resources.ts
@@ -0,0 +1,123 @@
+import { and, asc, eq, inArray, isNotNull, type SQL } from "drizzle-orm";
+import { getDb } from "../db/client.ts";
+import { attachments, resources } from "../db/schema/index.ts";
+import type { Db } from "../db/types.ts";
+import { isUuid } from "./uuid.ts";
+
+/**
+ * Resource reads on Postgres (spec §3.10, §4.6, §4.7).
+ *
+ * This replaces `fetchAllResources` from `src/lib/notion.ts` behind the chat
+ * route's manual attachment: the route picks the focused tool's PDFs and hands
+ * their bytes to the model, so it needs each resource's link *and* the files
+ * hanging off it.
+ *
+ * **Unpublished resources are left out.** A resource staff unpublished is one
+ * they hid, and the assistant must not read its manual into a conversation.
+ * That is the rule the chat route has always applied; note it is deliberately
+ * *not* the rule in `./catalog.ts`, where a tool's links are gated by the
+ * tool's own visibility so intake-created drafts appear the moment staff
+ * publish the tool.
+ *
+ * Relative imports with `.ts` extensions and no `@/` alias, and no
+ * `"server-only"`: `scripts/` loads these modules under plain Node.
+ */
+
+/** A resource and the public files attached to it. */
+export interface ToolResource {
+  id: string;
+  toolId: string | null;
+  title: string;
+  type: string | null;
+  url: string | null;
+  notes: string | null;
+  /** Public URLs of the resource's attachments, cover first. */
+  fileUrls: string[];
+}
+
+export interface ResourceQueryOptions {
+  /** A handle to use instead of {@link getDb} — tests pass an isolated one. */
+  db?: Db;
+}
+
+/** Every published resource in the lab, by title — the order Notion sorted them in. */
+export async function listResources(
+  options: ResourceQueryOptions = {}
+): Promise<ToolResource[]> {
+  const db = options.db ?? (await getDb());
+  return loadResources(db, eq(resources.published, true));
+}
+
+/**
+ * One tool's published resources, by title. Empty for a tool with none, and
+ * for anything that is not a uuid.
+ */
+export async function listResourcesForTool(
+  toolId: string,
+  options: ResourceQueryOptions = {}
+): Promise<ToolResource[]> {
+  if (!isUuid(toolId)) return [];
+
+  const db = options.db ?? (await getDb());
+  return loadResources(
+    db,
+    and(eq(resources.toolId, toolId), eq(resources.published, true))
+  );
+}
+
+/**
+ * Two statements whatever the number of resources: the rows, then every
+ * attachment they own, keyed by resource id.
+ */
+async function loadResources(db: Db, where: SQL | undefined): Promise<ToolResource[]> {
+  const rows = await db
+    .select({
+      id: resources.id,
+      toolId: resources.toolId,
+      title: resources.title,
+      type: resources.type,
+      url: resources.url,
+      notes: resources.notes,
+    })
+    .from(resources)
+    .where(where)
+    .orderBy(asc(resources.title), asc(resources.id));
+
+  if (rows.length === 0) return [];
+
+  const filesByResource = await loadFileUrls(
+    db,
+    rows.map((row) => row.id)
+  );
+
+  return rows.map((row) => ({ ...row, fileUrls: filesByResource.get(row.id) ?? [] }));
+}
+
+/**
+ * Public attachment URLs owned by these resources, grouped by resource id and
+ * ordered by `position`. A private file has no URL a visitor could open, and
+ * the model is given nothing a visitor could not read.
+ */
+async function loadFileUrls(db: Db, resourceIds: string[]): Promise<Map<string, string[]>> {
+  const rows = await db
+    .select({ ownerId: attachments.ownerId, publicUrl: attachments.publicUrl })
+    .from(attachments)
+    .where(
+      and(
+        eq(attachments.ownerType, "resource"),
+        inArray(attachments.ownerId, resourceIds),
+        eq(attachments.access, "public"),
+        isNotNull(attachments.publicUrl)
+      )
+    )
+    .orderBy(asc(attachments.position), asc(attachments.id));
+
+  const map = new Map<string, string[]>();
+  for (const row of rows) {
+    if (!row.ownerId || !row.publicUrl) continue;
+    const list = map.get(row.ownerId);
+    if (list) list.push(row.publicUrl);
+    else map.set(row.ownerId, [row.publicUrl]);
+  }
+  return map;
+}
diff --git a/v5/src/lib/data/uuid.ts b/v5/src/lib/data/uuid.ts
new file mode 100644
index 0000000..02f4d93
--- /dev/null
+++ b/v5/src/lib/data/uuid.ts
@@ -0,0 +1,18 @@
+/**
+ * The uuid shape guard every query module needs (spec §4).
+ *
+ * Postgres `uuid` columns reject anything that is not uuid-shaped with a cast
+ * error rather than an empty result, so a slug, a unit label or free text from
+ * a model must never reach one. Each lookup that takes an untrusted id checks
+ * here first and returns its own "not found" instead.
+ *
+ * Relative imports with `.ts` extensions and no `@/` alias: `scripts/` loads
+ * these modules under plain Node.
+ */
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** True when `value` could address a uuid primary key. */
+export function isUuid(value: string): boolean {
+  return UUID.test(value);
+}
diff --git a/v5/src/lib/db/demo-seed.test.ts b/v5/src/lib/db/demo-seed.test.ts
index b859ea3..c36f3ac 100644
--- a/v5/src/lib/db/demo-seed.test.ts
+++ b/v5/src/lib/db/demo-seed.test.ts
@@ -1,8 +1,13 @@
 // @vitest-environment node
-import { eq } from "drizzle-orm";
-import { seedDemo } from "./demo-seed";
+import { and, eq } from "drizzle-orm";
+import {
+  DEMO_FORM_4_NOTION_PAGE_ID,
+  DEMO_FORM_4_UNIT_NOTION_PAGE_ID,
+  DEMO_PROJECT_SLUG,
+  seedDemo,
+} from "./demo-seed";
 import { createPgliteDb } from "./pglite";
-import { resources, tools, units } from "./schema/index";
+import { attachments, projectTools, projects, resources, tools, units } from "./schema/index";
 
 describe("seedDemo", () => {
   it("inserts the two demo tools with their units and resources", async () => {
@@ -13,14 +18,68 @@ describe("seedDemo", () => {
     expect(toolRows.every((row) => row.published)).toBe(true);
 
     const form4 = toolRows[0];
+    // Legacy-QR redirect fixture (spec Goal 2): Form 4 carries a Notion page
+    // id so an old `/tools/<id>` link can be tested end to end.
+    expect(form4.notionPageId).toBe(DEMO_FORM_4_NOTION_PAGE_ID);
+    expect(toolRows[1].notionPageId).toBeNull();
+
     const form4Units = await db.select().from(units).where(eq(units.toolId, form4.id));
     expect(form4Units).toHaveLength(1);
     expect(form4Units[0]).toMatchObject({ unitLabel: "Form 4 // A", status: "in_use", condition: "excellent" });
+    // The unit carries a page id too: the writes still on Notion relate rows by
+    // page id, and the Trotec's unit deliberately has none so both branches of
+    // that translation are reachable from the seed.
+    expect(form4Units[0].notionPageId).toBe(DEMO_FORM_4_UNIT_NOTION_PAGE_ID);
+
+    const trotecUnits = await db
+      .select()
+      .from(units)
+      .where(eq(units.toolId, toolRows[1].id));
+    expect(trotecUnits[0].notionPageId).toBeNull();
 
     const form4Resources = await db.select().from(resources).where(eq(resources.toolId, form4.id));
     expect(form4Resources.map((row) => row.title)).toEqual(["Form 4 SOP", "Resin handling safety"]);
   });
 
+  it("gives the Trotec a photo attachment, since its bundled image does not match its name", async () => {
+    const db = await createPgliteDb({ seed: seedDemo });
+    const [trotec] = await db.select().from(tools).where(eq(tools.slug, "trotec-speedy-400"));
+    const photos = await db
+      .select()
+      .from(attachments)
+      .where(and(eq(attachments.ownerType, "tool"), eq(attachments.ownerId, trotec.id)));
+    expect(photos).toHaveLength(1);
+    expect(photos[0]).toMatchObject({ access: "public", publicUrl: "/tool-images/Trotec Speedy 400, 80w.png" });
+  });
+
+  it("publishes one sample project with photos, materials, a link, and both tools", async () => {
+    const db = await createPgliteDb({ seed: seedDemo });
+
+    const [lamp] = await db.select().from(projects).where(eq(projects.slug, DEMO_PROJECT_SLUG));
+    expect(lamp).toMatchObject({
+      title: "Laser-cut plywood lamp",
+      published: true,
+      link: "https://en.wikipedia.org/wiki/Laser_cutting",
+      authorName: "MakerLab demo",
+    });
+    expect(lamp.materials.length).toBeGreaterThanOrEqual(3);
+    expect(lamp.body).toContain("## How it went");
+
+    const links = await db.select().from(projectTools).where(eq(projectTools.projectId, lamp.id));
+    expect(links).toHaveLength(2);
+
+    const photos = await db
+      .select()
+      .from(attachments)
+      .where(and(eq(attachments.ownerType, "project"), eq(attachments.ownerId, lamp.id)))
+      .orderBy(attachments.position);
+    expect(photos.map((p) => p.publicUrl)).toEqual([
+      "/sample-projects/laser-cut-lamp-lit.png",
+      "/sample-projects/laser-cut-lamp-parts.png",
+    ]);
+    expect(photos.every((p) => p.access === "public")).toBe(true);
+  });
+
   it("is idempotent", async () => {
     const db = await createPgliteDb({ seed: seedDemo });
     await seedDemo(db);
diff --git a/v5/src/lib/db/demo-seed.ts b/v5/src/lib/db/demo-seed.ts
index 669f378..3938ffa 100644
--- a/v5/src/lib/db/demo-seed.ts
+++ b/v5/src/lib/db/demo-seed.ts
@@ -1,12 +1,41 @@
-import { categories, locations, resources, tools, units } from "./schema/index.ts";
+import {
+  attachments,
+  categories,
+  locations,
+  projectTools,
+  projects,
+  resources,
+  tools,
+  units,
+} from "./schema/index.ts";
 import type { Db } from "./types.ts";
 
 /**
  * Sample data for a database with no `DATABASE_URL` (spec §3.10): the two
  * tools the mock catalogue has always shown, now as real rows so the same
- * query modules serve tests, E2E and a fresh clone. Idempotent — a database
- * that already has tools is left alone.
+ * query modules serve tests, E2E and a fresh clone, plus one published
+ * sample project built with them so the gallery, the project page and a
+ * tool's "built with this" section all have something to show. Idempotent —
+ * a database that already has tools is left alone.
+ *
+ * Images are `attachments` rows whose `public_url` points at files under
+ * `public/` (allowed by `images.localPatterns` in next.config.ts), the same
+ * shape an imported Blob attachment has, so no code path is demo-specific.
+ *
+ * Form 4 carries a `notionPageId`, exercising the legacy `/tools/<notion-id>`
+ * redirect (spec Goal 2) end to end without a real database. Its unit carries
+ * one too: the writes still on Notion until Phase 3 relate rows by page id, so
+ * an imported row and a purely local one (the Trotec, which has neither) are
+ * both worth having in the seed.
  */
+export const DEMO_FORM_4_NOTION_PAGE_ID = "1f2e3d4c-5b6a-4789-8abc-def012345678";
+
+/** The Notion page behind the Form 4's one unit — the `unit` relation target. */
+export const DEMO_FORM_4_UNIT_NOTION_PAGE_ID = "2a3b4c5d-6e7f-4890-9abc-def012345678";
+
+/** The sample project's slug, for tests and E2E. */
+export const DEMO_PROJECT_SLUG = "laser-cut-plywood-lamp";
+
 export async function seedDemo(db: Db): Promise<void> {
   const existing = await db.select({ id: tools.id }).from(tools).limit(1);
   if (existing.length > 0) return;
@@ -46,6 +75,7 @@ export async function seedDemo(db: Db): Promise<void> {
           emergencyStop: "Lift the lid to immediately halt the print and pause the build.",
           notes: "Always wear nitrile gloves when handling uncured resin. Ventilation must be running.",
           published: true,
+          notionPageId: DEMO_FORM_4_NOTION_PAGE_ID,
         },
         {
           slug: "trotec-speedy-400",
@@ -74,6 +104,7 @@ export async function seedDemo(db: Db): Promise<void> {
         status: "in_use",
         condition: "excellent",
         dateAcquired: "2024-08-12",
+        notionPageId: DEMO_FORM_4_UNIT_NOTION_PAGE_ID,
       },
       {
         toolId: trotec.id,
@@ -91,5 +122,72 @@ export async function seedDemo(db: Db): Promise<void> {
       { toolId: trotec.id, title: "Trotec Speedy 400 SOP", type: "SOP", url: "#" },
       { toolId: trotec.id, title: "Approved material list", type: "Safety", url: "#" },
     ]);
+
+    // Tool photos. The Form 4's bundled image matches its name, so the
+    // catalogue's fallback finds it; the Trotec's does not ("…, 80w.png"), so
+    // it gets an explicit attachment like an imported tool would.
+    await tx.insert(attachments).values({
+      ownerType: "tool",
+      ownerId: trotec.id,
+      position: 0,
+      blobPathname: "demo/tools/trotec-speedy-400.png",
+      access: "public",
+      publicUrl: "/tool-images/Trotec Speedy 400, 80w.png",
+      contentType: "image/png",
+      originalFilename: "Trotec Speedy 400, 80w.png",
+    });
+
+    const [lamp] = await tx
+      .insert(projects)
+      .values({
+        slug: DEMO_PROJECT_SLUG,
+        title: "Laser-cut plywood lamp",
+        body: [
+          "A bedside lamp cut from a single sheet of 3 mm birch plywood on the Trotec, with a resin diffuser printed on the Form 4.",
+          "",
+          "## How it went",
+          "",
+          "The slats are a living hinge pattern, so the shade bends round a hexagonal base without any steam. Two passes at 60 % power cut cleanly; the first attempt at 80 % scorched the edges.",
+          "",
+          "The diffuser is a 1 mm resin shell that slots over an LED strip. Sanding the cut edges before glue-up made the joints close up properly.",
+          "",
+          "Read more about the process on [Wikipedia](https://en.wikipedia.org/wiki/Laser_cutting).",
+        ].join("\n"),
+        link: "https://en.wikipedia.org/wiki/Laser_cutting",
+        materials: ["3 mm birch plywood", "Wood glue", "LED strip", "Standard resin", "Sandpaper"],
+        authorName: "MakerLab demo",
+        published: true,
+        publishedAt: new Date("2026-03-02T15:00:00.000Z"),
+        createdAt: new Date("2026-03-01T15:00:00.000Z"),
+      })
+      .returning({ id: projects.id });
+
+    await tx.insert(projectTools).values([
+      { projectId: lamp.id, toolId: trotec.id },
+      { projectId: lamp.id, toolId: form4.id },
+    ]);
+
+    await tx.insert(attachments).values([
+      {
+        ownerType: "project",
+        ownerId: lamp.id,
+        position: 0,
+        blobPathname: "demo/projects/laser-cut-lamp-lit.png",
+        access: "public",
+        publicUrl: "/sample-projects/laser-cut-lamp-lit.png",
+        contentType: "image/png",
+        originalFilename: "laser-cut-lamp-lit.png",
+      },
+      {
+        ownerType: "project",
+        ownerId: lamp.id,
+        position: 1,
+        blobPathname: "demo/projects/laser-cut-lamp-parts.png",
+        access: "public",
+        publicUrl: "/sample-projects/laser-cut-lamp-parts.png",
+        contentType: "image/png",
+        originalFilename: "laser-cut-lamp-parts.png",
+      },
+    ]);
   });
 }
diff --git a/v5/src/lib/legacy-id.test.ts b/v5/src/lib/legacy-id.test.ts
new file mode 100644
index 0000000..9934e44
--- /dev/null
+++ b/v5/src/lib/legacy-id.test.ts
@@ -0,0 +1,53 @@
+import { compactNotionId, isLegacyNotionId, normaliseNotionId } from "./legacy-id";
+
+const DASHED = "0f5e2c1a-4b6d-4e8f-9a0b-1c2d3e4f5a6b";
+const COMPACT = "0f5e2c1a4b6d4e8f9a0b1c2d3e4f5a6b";
+
+describe("isLegacyNotionId", () => {
+  it("accepts a Notion page id with and without dashes, in either case", () => {
+    expect(isLegacyNotionId(DASHED)).toBe(true);
+    expect(isLegacyNotionId(COMPACT)).toBe(true);
+    expect(isLegacyNotionId(DASHED.toUpperCase())).toBe(true);
+    expect(isLegacyNotionId(COMPACT.toUpperCase())).toBe(true);
+    expect(isLegacyNotionId(` ${DASHED} `)).toBe(true);
+  });
+
+  it("rejects slugs, which is the whole point of the check", () => {
+    for (const slug of [
+      "form-4",
+      "trotec-speedy-400",
+      "bantam-tools-desktop-cnc-milling-machine",
+      "0f5e2c1a", // a truncated id
+      `${COMPACT}0`, // 33 characters
+      "0f5e2c1a-4b6d-4e8f-9a0b-1c2d3e4f5a6z", // not hex
+      "0f5e2c1a4b6d-4e8f9a0b1c2d3e4f5a6b", // dashes in the wrong places
+      "",
+    ]) {
+      expect(isLegacyNotionId(slug)).toBe(false);
+    }
+  });
+});
+
+describe("compactNotionId", () => {
+  it("reduces both spellings to the same comparison key", () => {
+    expect(compactNotionId(DASHED)).toBe(COMPACT);
+    expect(compactNotionId(COMPACT)).toBe(COMPACT);
+    expect(compactNotionId(DASHED.toUpperCase())).toBe(COMPACT);
+  });
+
+  it("returns null for a slug", () => {
+    expect(compactNotionId("form-4")).toBeNull();
+  });
+});
+
+describe("normaliseNotionId", () => {
+  it("returns the dashed lower-case form Notion's API uses", () => {
+    expect(normaliseNotionId(COMPACT)).toBe(DASHED);
+    expect(normaliseNotionId(DASHED)).toBe(DASHED);
+    expect(normaliseNotionId(COMPACT.toUpperCase())).toBe(DASHED);
+  });
+
+  it("returns null for a slug", () => {
+    expect(normaliseNotionId("trotec-speedy-400")).toBeNull();
+  });
+});
diff --git a/v5/src/lib/legacy-id.ts b/v5/src/lib/legacy-id.ts
new file mode 100644
index 0000000..949b94e
--- /dev/null
+++ b/v5/src/lib/legacy-id.ts
@@ -0,0 +1,56 @@
+/**
+ * Legacy Notion page ids in `/tools/<id>` URLs (spec Goal 2).
+ *
+ * Before the Postgres move a tool's URL key was its Notion page id, and those
+ * ids are printed on the QR labels stuck to the machines. `tools.notion_page_id`
+ * keeps the key so the tool route can redirect an old link to `/tools/<slug>`,
+ * and these helpers are the whole test for "is this path segment a legacy id or
+ * a slug?".
+ *
+ * Notion writes the same id two ways: dashed in API responses, undashed in the
+ * URLs people copy out of the app. Both are accepted, in either case; anything
+ * else — `form-4`, a partial id, a uuid with dashes in the wrong places — is a
+ * slug as far as this module is concerned.
+ *
+ * No `@/` alias and no `server-only`: `src/lib/data/catalog.ts` imports this,
+ * and the scripts load that module under plain Node type-stripping.
+ */
+
+/** 32 hex characters, no dashes — the form Notion puts in a page URL. */
+const COMPACT = /^[0-9a-f]{32}$/i;
+
+/** The canonical 8-4-4-4-12 form Notion's API returns. */
+const DASHED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** True for a Notion page id, dashed or not. False for a slug like `form-4`. */
+export function isLegacyNotionId(value: string): boolean {
+  return compactNotionId(value) !== null;
+}
+
+/**
+ * The id's 32 hex characters, lower-case and undashed, or null when `value` is
+ * not a Notion page id. This is the comparison key: a stored id is normalised
+ * the same way before it is matched, so dashes and case never decide a lookup.
+ */
+export function compactNotionId(value: string): string | null {
+  const trimmed = value.trim();
+  if (COMPACT.test(trimmed)) return trimmed.toLowerCase();
+  if (DASHED.test(trimmed)) return trimmed.replace(/-/g, "").toLowerCase();
+  return null;
+}
+
+/**
+ * The dashed lower-case form Notion's API returns (`8-4-4-4-12`), or null when
+ * `value` is not a Notion page id.
+ */
+export function normaliseNotionId(value: string): string | null {
+  const compact = compactNotionId(value);
+  if (!compact) return null;
+  return [
+    compact.slice(0, 8),
+    compact.slice(8, 12),
+    compact.slice(12, 16),
+    compact.slice(16, 20),
+    compact.slice(20),
+  ].join("-");
+}
diff --git a/v5/src/lib/projects.test.ts b/v5/src/lib/projects.test.ts
index 4d81b41..ad14238 100644
--- a/v5/src/lib/projects.test.ts
+++ b/v5/src/lib/projects.test.ts
@@ -1,368 +1,114 @@
-import { http, HttpResponse } from "msw";
-
-import { server } from "../../test/msw/server";
-import {
-  checkboxProp,
-  externalFile,
-  filesProp,
-  multiSelectProp,
-  notionQueryResponse,
-  relationProp,
-  richTextProp,
-  titleProp,
-  urlProp,
-  type NotionPageFixture,
-} from "../../test/fixtures/notion";
 import { nextCacheMock } from "../../test/mocks/next-cache";
 
 vi.mock("next/cache", () => nextCacheMock());
 
-// ── Helpers ─────────────────────────────────────────────────────────
-
-const PROJECTS_DB = "db-projects";
-
-// The Projects DB is independent of the catalog env contract: it needs only
-// NOTION_API_KEY + NOTION_DB_PROJECTS. The catalog DB ids are deliberately left
-// blank so `getCatalogTools()` resolves tool relations against the built-in
-// mock catalog (tool-form-4 / tool-trotec-speedy-400) with no network call.
-function stubProjectsEnv() {
-  vi.stubEnv("NOTION_API_KEY", "secret_test");
-  vi.stubEnv("NOTION_DB_PROJECTS", PROJECTS_DB);
-  vi.stubEnv("NOTION_DB_TOOLS", "");
-  vi.stubEnv("NOTION_DB_CATEGORIES", "");
-  vi.stubEnv("NOTION_DB_LOCATIONS", "");
-  vi.stubEnv("NOTION_DB_UNITS", "");
-  vi.stubEnv("NOTION_DB_RESOURCES", "");
-  vi.stubEnv("NOTION_DB_MAINTENANCE_LOGS", "");
-  vi.stubEnv("NOTION_DB_FLAGS", "");
-}
-
-const TS = "2024-08-12T10:00:00.000Z";
-
-// A raw Projects page. Any property can be overridden — or omitted entirely, to
-// exercise the "property absent from the database" path.
-function projectPage(
-  id: string,
-  properties: Record<string, unknown>,
-  createdTime = TS
-): NotionPageFixture {
+// `src/lib/projects.ts` is now a thin `"use cache"` wrapper over
+// `src/lib/data/projects.ts` (spec §3.10); the mapping and filtering it used
+// to do live there and are covered by `src/lib/data/projects.test.ts`
+// instead. This file only has to prove the wrapper: it delegates with the
+// right arguments, tags every read `projects`, and — Article 4 — never turns
+// a database failure into an invented empty result.
+const dataProjects = vi.hoisted(() => ({
+  listPublishedProjects: vi.fn(),
+  findPublishedProject: vi.fn(),
+  listPublishedProjectsForTool: vi.fn(),
+}));
+
+vi.mock("./data/projects", () => dataProjects);
+
+import { cacheTag } from "next/cache";
+import type { MakerLabProject } from "../components/catalog-types";
+import { getProject, getProjectsForTool, getPublishedProjects } from "./projects";
+
+function project(overrides: Partial<MakerLabProject> = {}): MakerLabProject {
   return {
-    object: "page",
-    id,
-    created_time: createdTime,
-    last_edited_time: createdTime,
-    properties,
+    id: "11111111-1111-1111-1111-111111111111",
+    slug: "lamp-from-scrap-plywood",
+    title: "Lamp from scrap plywood",
+    author: "Ada Lovelace",
+    body: "## How I made it",
+    photos: ["https://blob.test/cover.png"],
+    tools: [{ id: "tool-1", name: "Form 4", slug: "form-4" }],
+    link: null,
+    materials: ["Plywood"],
+    date: "2026-01-01T00:00:00.000Z",
+    ...overrides,
   };
 }
 
-const fullProject = projectPage("project-1", {
-  title: titleProp("Lamp from scrap plywood"),
-  author: richTextProp("Ada Lovelace"),
-  body: richTextProp("## How I made it\nCut on the laser, glued, sanded."),
-  photos: filesProp([
-    externalFile("cover.png", "https://files.notion.so/cover.png"),
-    externalFile("detail.png", "https://files.notion.so/detail.png"),
-  ]),
-  // tool-form-4 exists in the mock catalog; tool-deleted does not.
-  tools_used: relationProp(["tool-form-4", "tool-deleted"]),
-  link: urlProp("https://example.com/lamp"),
-  materials: multiSelectProp(["Plywood", "PLA"]),
-  published: checkboxProp(true),
-});
-
-// Route every Notion DB query to the supplied project pages. `projects.ts` only
-// ever queries the Projects DB (the catalog comes from the mock fallback), so a
-// single override is enough.
-function routeProjects(pages: NotionPageFixture[]) {
-  server.use(
-    http.post("https://api.notion.com/v1/databases/:id/query", ({ params }) =>
-      HttpResponse.json(
-        notionQueryResponse(params.id === PROJECTS_DB ? pages : [])
-      )
-    )
-  );
-}
-
-// projects.ts reads process.env through function calls (`hasProjectsEnv`), but
-// re-importing per test also gives each test a fresh `"use cache"` boundary.
-async function importProjects() {
-  vi.resetModules();
-  return import("@/lib/projects");
-}
-
-// ── toMakerLabProject mapping ───────────────────────────────────────
-
-describe("getPublishedProjects (mapping)", () => {
-  it("maps a Notion project record onto MakerLabProject", async () => {
-    stubProjectsEnv();
-    routeProjects([fullProject]);
-    const { getPublishedProjects } = await importProjects();
-
-    const [project] = await getPublishedProjects();
-
-    expect(project.id).toBe("project-1");
-    expect(project.title).toBe("Lamp from scrap plywood");
-    expect(project.author).toBe("Ada Lovelace");
-    expect(project.body).toContain("How I made it");
-    expect(project.photos).toEqual([
-      "https://files.notion.so/cover.png",
-      "https://files.notion.so/detail.png",
-    ]);
-    expect(project.link).toBe("https://example.com/lamp");
-    expect(project.materials).toEqual(["Plywood", "PLA"]);
-    expect(project.date).toBe(TS);
-  });
-
-  it("falls back to Anonymous when the author is empty", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      projectPage("project-anon", {
-        title: titleProp("Anonymous build"),
-        author: richTextProp(""),
-        body: richTextProp("No name on this one."),
-        published: checkboxProp(true),
-      }),
-    ]);
-    const { getPublishedProjects } = await importProjects();
-
-    const [project] = await getPublishedProjects();
-    expect(project.author).toBe("Anonymous");
-  });
-
-  it("falls back to Anonymous when the author property is absent entirely", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      projectPage("project-no-author", {
-        title: titleProp("Untitled author"),
-        body: richTextProp("Body only."),
-        published: checkboxProp(true),
-      }),
-    ]);
-    const { getPublishedProjects } = await importProjects();
-
-    const [project] = await getPublishedProjects();
-    expect(project.author).toBe("Anonymous");
-  });
-
-  it("returns empty photos/tools/materials when those properties are absent", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      projectPage("project-bare", {
-        title: titleProp("Bare project"),
-        author: richTextProp("Grace Hopper"),
-        body: richTextProp("Just words."),
-        published: checkboxProp(true),
-      }),
-    ]);
-    const { getPublishedProjects } = await importProjects();
-
-    const [project] = await getPublishedProjects();
-    expect(project.photos).toEqual([]);
-    expect(project.tools).toEqual([]);
-    expect(project.materials).toEqual([]);
-    expect(project.link).toBeNull();
-    // No `date` property — falls back to the page's created_time.
-    expect(project.date).toBe(TS);
-  });
-
-  it("drops tool ids that no longer resolve instead of rendering them broken", async () => {
-    stubProjectsEnv();
-    routeProjects([fullProject]);
-    const { getPublishedProjects } = await importProjects();
-
-    const [project] = await getPublishedProjects();
-
-    // tool-deleted is gone from the catalog; only the resolvable ref survives.
-    expect(project.tools).toEqual([
-      { id: "tool-form-4", name: "Form 4", slug: "form-4" },
-    ]);
-  });
-
-  it("resolves tool refs with the slug the tool page is routed by", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      projectPage("project-two-tools", {
-        title: titleProp("Two machines"),
-        author: richTextProp("Ada"),
-        body: richTextProp("Body"),
-        tools_used: relationProp(["tool-trotec-speedy-400", "tool-form-4"]),
-        published: checkboxProp(true),
-      }),
-    ]);
-    const { getPublishedProjects } = await importProjects();
-
-    const [project] = await getPublishedProjects();
-    expect(project.tools.map((tool) => tool.slug)).toEqual([
-      "trotec-speedy-400",
-      "form-4",
-    ]);
-  });
+beforeEach(() => {
+  dataProjects.listPublishedProjects.mockReset();
+  dataProjects.findPublishedProject.mockReset();
+  dataProjects.listPublishedProjectsForTool.mockReset();
 });
 
-// ── published filtering ─────────────────────────────────────────────
+describe("getPublishedProjects", () => {
+  it("returns what the data layer resolves", async () => {
+    dataProjects.listPublishedProjects.mockResolvedValue([project()]);
 
-describe("getPublishedProjects (publish gate)", () => {
-  it("excludes records whose published checkbox is unticked", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      fullProject,
-      projectPage("project-draft", {
-        title: titleProp("Draft build"),
-        author: richTextProp("Someone"),
-        body: richTextProp("Not reviewed yet."),
-        published: checkboxProp(false),
-      }),
-    ]);
-    const { getPublishedProjects } = await importProjects();
-
-    const projects = await getPublishedProjects();
-    expect(projects.map((project) => project.id)).toEqual(["project-1"]);
+    expect(await getPublishedProjects()).toEqual([project()]);
+    expect(dataProjects.listPublishedProjects).toHaveBeenCalledTimes(1);
   });
 
-  it("excludes records with no published property at all", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      projectPage("project-unset", {
-        title: titleProp("No checkbox"),
-        author: richTextProp("Someone"),
-        body: richTextProp("Body"),
-      }),
-    ]);
-    const { getPublishedProjects } = await importProjects();
+  it("tags the read `projects`, so publishing or unpublishing one can invalidate it", async () => {
+    dataProjects.listPublishedProjects.mockResolvedValue([]);
 
-    expect(await getPublishedProjects()).toEqual([]);
+    await getPublishedProjects();
+    expect(vi.mocked(cacheTag)).toHaveBeenCalledWith("projects");
   });
-});
-
-// ── no env / failure paths ──────────────────────────────────────────
 
-describe("getPublishedProjects (no Projects DB)", () => {
-  it("returns an empty array without throwing or calling Notion", async () => {
-    vi.stubEnv("NOTION_API_KEY", "");
-    vi.stubEnv("NOTION_DB_PROJECTS", "");
-    const { getPublishedProjects } = await importProjects();
+  it("lets a database failure propagate instead of returning an invented empty gallery", async () => {
+    dataProjects.listPublishedProjects.mockRejectedValue(new Error("db unavailable"));
 
-    // MSW's onUnhandledRequest:"error" would fail this test on any outbound
-    // call, so reaching the assertion proves nothing was fetched.
-    await expect(getPublishedProjects()).resolves.toEqual([]);
-  });
-
-  it("returns an empty array when NOTION_DB_PROJECTS alone is missing", async () => {
-    vi.stubEnv("NOTION_API_KEY", "secret_test");
-    vi.stubEnv("NOTION_DB_PROJECTS", "");
-    const { getPublishedProjects } = await importProjects();
-
-    await expect(getPublishedProjects()).resolves.toEqual([]);
-  });
-
-  it("fails toward empty (not toward a thrown page) when Notion errors", async () => {
-    stubProjectsEnv();
-    server.use(
-      http.post("https://api.notion.com/v1/databases/:id/query", () =>
-        HttpResponse.json(
-          { object: "error", status: 500, message: "internal" },
-          { status: 500 }
-        )
-      )
-    );
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const { getPublishedProjects } = await importProjects();
-
-    await expect(getPublishedProjects()).resolves.toEqual([]);
-    // The failure has to be visible in the logs (Article 4).
-    expect(warn).toHaveBeenCalled();
+    await expect(getPublishedProjects()).rejects.toThrow("db unavailable");
   });
 });
 
-// ── getProject ──────────────────────────────────────────────────────
-
 describe("getProject", () => {
-  it("returns the published project for a known id", async () => {
-    stubProjectsEnv();
-    routeProjects([fullProject]);
-    const { getProject } = await importProjects();
+  it("delegates to findPublishedProject with the id or slug it was given", async () => {
+    dataProjects.findPublishedProject.mockResolvedValue(project());
 
-    const project = await getProject("project-1");
-    expect(project?.title).toBe("Lamp from scrap plywood");
+    expect(await getProject("lamp-from-scrap-plywood")).toEqual(project());
+    expect(dataProjects.findPublishedProject).toHaveBeenCalledWith("lamp-from-scrap-plywood");
   });
 
-  it("returns null for an unknown id", async () => {
-    stubProjectsEnv();
-    routeProjects([fullProject]);
-    const { getProject } = await importProjects();
+  it("returns null when the data layer finds nothing published under that id or slug", async () => {
+    dataProjects.findPublishedProject.mockResolvedValue(null);
 
     expect(await getProject("no-such-project")).toBeNull();
   });
 
-  it("returns null for an unpublished project reachable by direct id", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      fullProject,
-      projectPage("project-draft", {
-        title: titleProp("Draft build"),
-        author: richTextProp("Someone"),
-        body: richTextProp("Not reviewed yet."),
-        published: checkboxProp(false),
-      }),
-    ]);
-    const { getProject } = await importProjects();
+  it("tags the read `projects`", async () => {
+    dataProjects.findPublishedProject.mockResolvedValue(null);
 
-    // Guessing the id of an unpublished submission must not surface it.
-    expect(await getProject("project-draft")).toBeNull();
+    await getProject("project-1");
+    expect(vi.mocked(cacheTag)).toHaveBeenCalledWith("projects");
   });
 
-  it("returns null when no Projects DB is configured", async () => {
-    vi.stubEnv("NOTION_API_KEY", "");
-    vi.stubEnv("NOTION_DB_PROJECTS", "");
-    const { getProject } = await importProjects();
+  it("lets a database failure propagate", async () => {
+    dataProjects.findPublishedProject.mockRejectedValue(new Error("db unavailable"));
 
-    expect(await getProject("project-1")).toBeNull();
+    await expect(getProject("project-1")).rejects.toThrow("db unavailable");
   });
 });
 
-// ── getProjectsForTool (the "Built with this" join) ──────────────────
-
 describe("getProjectsForTool", () => {
-  it("returns only the projects that reference the tool", async () => {
-    stubProjectsEnv();
-    routeProjects([
-      fullProject,
-      projectPage("project-laser", {
-        title: titleProp("Laser box"),
-        author: richTextProp("Someone"),
-        body: richTextProp("Body"),
-        tools_used: relationProp(["tool-trotec-speedy-400"]),
-        published: checkboxProp(true),
-      }),
-    ]);
-    const { getProjectsForTool } = await importProjects();
-
-    const forPrinter = await getProjectsForTool("tool-form-4");
-    expect(forPrinter.map((project) => project.id)).toEqual(["project-1"]);
-  });
-
-  it("returns an empty array for a tool nothing was built with", async () => {
-    stubProjectsEnv();
-    routeProjects([fullProject]);
-    const { getProjectsForTool } = await importProjects();
+  it("delegates to listPublishedProjectsForTool with the given tool id", async () => {
+    dataProjects.listPublishedProjectsForTool.mockResolvedValue([project()]);
 
-    expect(await getProjectsForTool("tool-trotec-speedy-400")).toEqual([]);
+    expect(await getProjectsForTool("tool-1")).toEqual([project()]);
+    expect(dataProjects.listPublishedProjectsForTool).toHaveBeenCalledWith("tool-1");
   });
 
-  it("returns an empty array — never throws — for a deleted tool id", async () => {
-    stubProjectsEnv();
-    routeProjects([fullProject]);
-    const { getProjectsForTool } = await importProjects();
+  it("returns an empty array when nothing was built with the tool", async () => {
+    dataProjects.listPublishedProjectsForTool.mockResolvedValue([]);
 
-    // A project referencing a deleted tool must not 500 the tool page.
-    expect(await getProjectsForTool("tool-deleted")).toEqual([]);
+    expect(await getProjectsForTool("tool-1")).toEqual([]);
   });
 
-  it("returns an empty array when no Projects DB is configured", async () => {
-    vi.stubEnv("NOTION_API_KEY", "");
-    vi.stubEnv("NOTION_DB_PROJECTS", "");
-    const { getProjectsForTool } = await importProjects();
+  it("lets a database failure propagate", async () => {
+    dataProjects.listPublishedProjectsForTool.mockRejectedValue(new Error("db unavailable"));
 
-    expect(await getProjectsForTool("tool-form-4")).toEqual([]);
+    await expect(getProjectsForTool("tool-1")).rejects.toThrow("db unavailable");
   });
 });
diff --git a/v5/src/lib/projects.ts b/v5/src/lib/projects.ts
index 4361568..f71b16d 100644
--- a/v5/src/lib/projects.ts
+++ b/v5/src/lib/projects.ts
@@ -1,84 +1,50 @@
 import { cacheLife, cacheTag } from "next/cache";
-import { fetchAllProjects, hasProjectsEnv } from "./notion";
-import type { ProjectRecord } from "./types";
-import type { MakerLabProject, ProjectToolRef } from "../components/catalog-types";
-import { getCatalogTools } from "./catalog";
+import { findPublishedProject, listPublishedProjects, listPublishedProjectsForTool } from "./data/projects";
+import type { MakerLabProject } from "../components/catalog-types";
 
-// Cached, published-only view of every project. Behind `"use cache"` with the
-// `projects` tag so the admin revalidate endpoint can bust it on publish.
-async function fetchPublishedProjects(): Promise<ProjectRecord[]> {
+// Cached, published-only reads over `src/lib/data/projects.ts`. Every export
+// below shares the `projects` cache tag (spec §3.9), so publishing,
+// unpublishing or editing a project in `/admin/projects` busts every one of
+// these with a single `revalidateTag("projects")` / `updateTag("projects")`
+// call. A thrown database read is not caught here: it surfaces as a stale
+// cached page (Article 4, fail toward stale), never an invented empty result.
+
+async function fetchPublishedProjects(): Promise<MakerLabProject[]> {
   "use cache";
   cacheTag("projects");
   cacheLife("minutes");
 
-  return fetchAllProjects({ publishedOnly: true });
+  return listPublishedProjects();
 }
 
-async function toMakerLabProjects(
-  records: ProjectRecord[]
-): Promise<MakerLabProject[]> {
-  // Resolve tool relation ids → {id,name,slug} via the catalog (slug === id).
-  const tools = await getCatalogTools();
-  const toolMap = new Map<string, ProjectToolRef>(
-    tools.map((tool) => [tool.id, { id: tool.id, name: tool.name, slug: tool.slug }])
-  );
+async function fetchProject(idOrSlug: string): Promise<MakerLabProject | null> {
+  "use cache";
+  cacheTag("projects");
+  cacheLife("minutes");
 
-  return records.map((record) => toMakerLabProject(record, toolMap));
+  return findPublishedProject(idOrSlug);
 }
 
-function toMakerLabProject(
-  record: ProjectRecord,
-  toolMap: Map<string, ProjectToolRef>
-): MakerLabProject {
-  const fields = record.fields;
-  return {
-    id: record.id,
-    title: fields.title,
-    author: fields.author || "Anonymous",
-    body: fields.body || "",
-    // Notion file URLs are signed and expire; surfaced as-is for the short
-    // cacheLife window (mirrors the catalog image approach).
-    photos: (fields.photos || []).map((photo) => photo.url).filter(Boolean),
-    tools: (fields.tools_used || [])
-      .map((id) => toolMap.get(id))
-      .filter((ref): ref is ProjectToolRef => Boolean(ref)),
-    link: fields.link || null,
-    materials: fields.materials || [],
-    date: fields.date || record.createdTime || null,
-  };
+async function fetchProjectsForTool(toolId: string): Promise<MakerLabProject[]> {
+  "use cache";
+  cacheTag("projects");
+  cacheLife("minutes");
+
+  return listPublishedProjectsForTool(toolId);
 }
 
 export async function getPublishedProjects(): Promise<MakerLabProject[]> {
-  if (!hasProjectsEnv()) return [];
-
-  try {
-    const records = await fetchPublishedProjects();
-    return toMakerLabProjects(records);
-  } catch (error) {
-    console.warn("Failed to load projects:", error);
-    return [];
-  }
+  return fetchPublishedProjects();
 }
 
-export async function getProject(id: string): Promise<MakerLabProject | null> {
-  if (!hasProjectsEnv()) return null;
-
-  // Resolve from the cached published set so unpublished projects never surface
-  // via the detail route either.
-  const projects = await getPublishedProjects();
-  return projects.find((project) => project.id === id) || null;
+export async function getProject(idOrSlug: string): Promise<MakerLabProject | null> {
+  return fetchProject(idOrSlug);
 }
 
 /**
  * Published projects that reference a given tool id (the "Built with this"
- * section on the tool detail). Derived by scanning each project's
- * `tools_used`. Returns [] when no projects DB is configured.
+ * section on the tool detail).
  */
-export async function getProjectsForTool(
-  toolId: string
-): Promise<MakerLabProject[]> {
-  const projects = await getPublishedProjects();
-  return projects.filter((project) =>
-    project.tools.some((tool) => tool.id === toolId)
-  );
+export async function getProjectsForTool(toolId: string): Promise<MakerLabProject[]> {
+  return fetchProjectsForTool(toolId);
 }
diff --git a/v5/src/styles/globals.css b/v5/src/styles/globals.css
index b4edb82..5581a81 100644
--- a/v5/src/styles/globals.css
+++ b/v5/src/styles/globals.css
@@ -163,6 +163,7 @@ img {
 }
 
 .primary-nav {
+  position: relative; /* anchors .primary-nav-notice */
   display: flex;
   gap: 32px;
   color: var(--on-surface-muted);
@@ -200,6 +201,40 @@ img {
   outline: none;
 }
 
+/* Why the last "Sign in" click went nowhere. Anchored under the nav's right
+   edge and taken out of the flow, so it never pushes the links or the rows
+   beneath the header when it appears. */
+.primary-nav-notice {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 20;
+  max-width: 32ch;
+  padding: 6px 10px;
+  border: 1px solid var(--outline);
+  background: var(--background);
+  color: var(--on-surface-muted);
+  font-size: 11px;
+  line-height: 1.3;
+  text-transform: none;
+  white-space: normal;
+  /* Holds, then fades over the last fifth of its life; the component removes
+     it when the duration (set inline) is up. */
+  animation-name: primary-nav-notice-fade;
+  animation-timing-function: ease-in;
+  animation-fill-mode: forwards;
+}
+
+@keyframes primary-nav-notice-fade {
+  0%,
+  80% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+  }
+}
+
 .nav-actions {
   display: flex;
   align-items: center;
diff --git a/v5/test/README.md b/v5/test/README.md
index e77ffa8..afa1a07 100644
--- a/v5/test/README.md
+++ b/v5/test/README.md
@@ -17,7 +17,7 @@ your `*.test.ts(x)` files and import from here.
 | `test/mocks/next-cache.ts` | `nextCacheMock()` factory for `vi.mock("next/cache", …)` |
 | `test/mocks/server-only.ts` | empty stub aliased for `import "server-only"` |
 | `test/utils/render.tsx` | RTL `render` wrapped in `NextIntlClientProvider` + `userEvent` |
-| `playwright.config.ts` | E2E config; dev server boots with Notion env unset |
+| `playwright.config.ts` | E2E config; dev server boots with `DATABASE_URL` unset (PGlite demo seed) |
 
 ## Scripts
 
@@ -59,18 +59,62 @@ import { render, screen, userEvent } from "../../test/utils/render";
 
 ---
 
-## The mock-catalog fallback rule (read this first)
+## The PGlite rule (read this first)
+
+Catalogue reads run against Postgres, and the test suite never needs Notion
+env for them. `getCatalogTools()` / `getCatalogTool(id)` read from **PGlite**
+— an in-process Postgres, migrated and seeded with demo data (two tools:
+`form-4`, `trotec-speedy-400`) — whenever `DATABASE_URL` is unset, which is
+the default in every test. No MSW, no `vi.stubEnv` for Notion, no network.
+
+- **The seeded demo database** (most catalogue tests): leave `DATABASE_URL`
+  unset and call `getDb()` from `../../src/lib/db/client` — it lazily creates
+  and memoises one PGlite instance per test file. Put `resetDbForTests()` in
+  an `afterEach` if a test stubs `DATABASE_URL` to something else.
+- **An isolated database** (schema tests, or a test that needs to seed its own
+  rows without touching the shared demo data): call `createPgliteDb()` from
+  `../../src/lib/db/pglite` directly — it returns a fresh, empty (or
+  custom-seeded via its `seed` option) instance, migrated the same way Neon
+  is.
+- **`// @vitest-environment node` is required** at the top of any file that
+  creates or touches a PGlite database — jsdom (the suite's default
+  environment) doesn't have what PGlite's WASM build needs.
 
-`getCatalogTools()` / `getCatalogTool(id)` return the built-in mock catalog when
-`hasNotionCatalogEnv()` is false — i.e. **any** of the 8 Notion env vars
-(`NOTION_API_KEY` + the 7 `NOTION_DB_*`) is missing — **and** on any thrown
-error during the Notion fetch.
+```ts
+// @vitest-environment node
+import { createPgliteDb } from "../../src/lib/db/pglite";
+import type { Db } from "../../src/lib/db/types";
+
+let db: Db;
+
+beforeAll(async () => {
+  db = await createPgliteDb();
+});
+```
+
+```ts
+// @vitest-environment node
+import { getDb, resetDbForTests } from "../../src/lib/db/client";
+
+afterEach(() => {
+  resetDbForTests();
+});
+
+it("reads the seeded demo tools", async () => {
+  vi.stubEnv("DATABASE_URL", "");
+  const db = await getDb();
+  // ...
+});
+```
 
-- **Mock path** (default in tests): leave Notion env unset. Catalog comes from
-  `src/components/mock-catalog.ts`. No MSW needed.
-- **Real Notion path**: `vi.stubEnv` all 8 vars (set the `NOTION_DB_*` ones to
-  the `DB_IDS` sentinels so the default handlers route correctly), then let MSW
-  serve `api.notion.com`.
+`vi.unstubAllEnvs()` runs automatically after every test (setup file).
+
+**Write paths are still on Notion in this phase** (maintenance tickets,
+corrections, project submission, uploads, intake) — see
+`docs/specs/2026-09-14-v5-data-platform-design.md` §9. Testing those still
+uses the real-Notion MSW path: `vi.stubEnv` all 8 Notion vars (set the
+`NOTION_DB_*` ones to the `DB_IDS` sentinels so the default handlers route
+correctly), then let MSW serve `api.notion.com`.
 
 ```ts
 import { DB_IDS } from "../../test/msw/handlers";
@@ -87,8 +131,6 @@ function stubNotionEnv() {
 }
 ```
 
-`vi.unstubAllEnvs()` runs automatically after every test (setup file).
-
 ---
 
 ## Env stubbing for module-load-time reads
@@ -233,7 +275,7 @@ it("wires system + tools and runs a captured tool.execute", async () => {
   expect(captured.args.tools).toHaveProperty("report_issue");
   expect(captured.args.tools).toHaveProperty("web_fetch");
 
-  // Invoke a tool.execute directly (mock-catalog path — no Notion env):
+  // Invoke a tool.execute directly (PGlite demo seed — DATABASE_URL unset):
   const miss = await captured.args.tools.get_unit_details.execute({
     unit_label: "no-such-unit",
   });
@@ -251,5 +293,5 @@ Notes:
 - To test `report_issue.execute` filing a ticket, stub the Notion env and let
   MSW's `POST /pages` handler respond (returns `id: "created-page-1"`), then
   assert `result.success === true` and `result.ticket_id`.
-- For `get_unit_details` / `report_issue` against the **mock catalog** (no env),
-  the catalog units come from `mock-catalog.ts` (`Form 4 // A`, `Trotec Speedy 400`).
+- For `get_unit_details` against the **PGlite demo seed** (`DATABASE_URL`
+  unset), the catalog units are `Form 4 // A` and `Trotec Speedy 400`.