Auto-seed dev PocketBase and share its schema with the tests

docs/entwicklung.md

@@ -17,8 +17,8 @@ the base for a local run — you layer an overlay on top of it.
 | File | Role |
 |---|---|
 | `compose.yaml` | Base, production-shaped: both services, **no** host ports, PocketBase data on the Unraid bind mount. Also holds the fixed project name `eb-stack`. |
-| `compose.dev.yaml` | Dev overlay: adds host ports (5000, 8090), builds the web image from local source instead of pulling it, swaps the Unraid bind mount for a throwaway volume, and seeds a local PocketBase superuser. |
-| `compose.test.yaml` | Test overlay: used **only** by the integration tests. Drops the fixed host port and container names so a test run does not collide with a running dev stack. |
+| `compose.dev.yaml` | Dev overlay: adds host ports (5000, 8090), builds the web image from local source instead of pulling it, swaps the Unraid bind mount for a throwaway volume, seeds a local PocketBase superuser, and mounts `pb/pb_migrations` so a fresh volume is auto-seeded (see below). |
+| `compose.test.yaml` | Test overlay: used **only** by the integration tests. Drops the fixed host port and container names so a test run does not collide with a running dev stack, and removes the seed mount so the dev seed does not run during tests. |
 
 > **Project name.** `name: eb-stack` is set once, in the base. The overlays
 > deliberately don't set their own `name:` — a competing `name:` across `-f`
@@ -88,11 +88,60 @@ dev stack — you can have DevEnvironment up in Rider and run `dotnet test` at t
 same time. The fixture cleans up before and after each run, so a hard-killed
 earlier run leaves nothing behind.
 
+The fixture creates the collections by importing the **same** schema file the dev
+seed uses (see the next section), so the schema is defined once. Its *records*,
+though, are fixed in `PocketBaseFixture` on purpose — the tests assert against
+values that file controls (a non-public draft page that must never show, an event
+at a known time), not against the dev seed's content. The test overlay therefore
+drops the `pb_migrations` mount so the dev seed does **not** run during tests.
+
 **Requirements:** Docker with the Compose plugin must be available when the tests
 run (they call `docker compose`).
 
 ---
 
+## Example content on a fresh volume (the dev seed)
+
+A fresh dev volume comes up populated, so a first `docker compose … up` shows a
+working site instead of an empty one. Two files under `pb/pb_migrations/` do this,
+and the dev overlay mounts that folder into PocketBase (`./pb/pb_migrations:/pb_migrations`):
+
+| File | Role |
+|---|---|
+| `collections_schema.json` | The four content collections (`pages`, `posts`, `events`, `faqs`) as PocketBase exports them. **The single source of truth for the schema** — the test fixture imports this same file. |
+| `<timestamp>_dev_seed.js` | The PocketBase migration. Reads the schema file, creates any missing collection, then inserts the example records. |
+
+Both steps are **idempotent**: a collection is created only if it is missing, and
+filled only while it is empty. So a populated volume — or the production DB, should
+this ever run there — is never touched. To start over from an empty, then freshly
+seeded volume:
+
+```bash
+docker volume rm eb-stack_pb_data_dev
+docker compose -f compose.yaml -f compose.dev.yaml up --build
+```
+
+> **Seed only in dev.** The `pb_migrations` mount lives in `compose.dev.yaml`
+> alone. The base (production) file does not mount it, and the test overlay
+> removes it again — production content is seeded by hand, never from this repo.
+
+### Refreshing the seed after a schema or content change
+
+The seed is generated from a running dev instance, not hand-edited. When you
+change a collection's schema in the admin UI, or want to capture the current
+example content as the new seed, re-export from the running dev PocketBase
+(authenticated as the dev superuser) and regenerate the two files. The schema file
+is the plain export of the four collections; the migration embeds the records the
+same way. After regenerating, prove it end to end:
+
+```bash
+docker volume rm eb-stack_pb_data_dev            # force a fresh volume
+docker compose -f compose.yaml -f compose.dev.yaml up --build
+dotnet test                                       # fixture imports the new schema
+```
+
+---
+
 ## Content while developing
 
 The app reads its content from PocketBase over the compose network
@@ -126,6 +175,12 @@ It takes three steps, all small because the plumbing is shared:
    `EventList`, `FaqList`) for the load-in-`OnInitializedAsync`, log-and-degrade
    pattern, and add a route smoke test plus a fixture seed.
 
+Also refresh the seed so the new collection comes up on a fresh volume and in the
+tests: re-export it into `pb/pb_migrations/collections_schema.json` (the shared
+schema) and add example rows to the dev seed migration — see *Refreshing the seed*
+above. The test fixture picks the new schema up automatically once it is in the
+file.
+
 Text pages need none of this — they are all served generically by
 `ContentPage` (`@page "/{Slug}"`), which is why a new `pages` record is live
 without a rebuild.