A real incident hit during directus Phase 1 task 1.5: 5 newly-created
collections were destroyed by a container rebuild because the baked-in
snapshot was stale. directus schema apply --yes enforces the snapshot
as the single source of truth — anything not in the snapshot gets
deleted.
This is correct for fresh-environment provisioning and prod, but
catastrophic during active schema development. Adding a callout to the
directus entity page so future readers see the operator rule alongside
the snapshot/apply pattern documentation:
Never restart or rebuild the Directus container while there are
uncommitted schema changes. Always: change → snapshot → commit →
rebuild/restart.
The recovery path (re-apply via MCP / admin UI, snapshot before
restart) is straightforward in dev but would be data-loss in prod.
Phase 3 hardening will introduce a DIRECTUS_SCHEMA_APPLY_MODE env var
with auto/dry-run/skip modes so dev environments default to
non-destructive behavior.
julian
417c21f49e