# Directus production reference

This directory documents how the Next.js application integrates with the production Directus instance. It is evidence for development and review; it is not an automated migration source and must not be applied to production without a separate, reviewed change process.

## Evidence and authority

- `schema.yaml` is the fresh schema snapshot collected from production Directus 12.1.1 on 2026-07-10. It is the authoritative schema evidence in this directory for that collection time.
- `reference/` contains immutable, sanitized source evidence collected from the same deployment: deployment inventory, Compose and Nginx summaries, environment-variable names, roles, policies, access assignments, permissions, settings metadata, flows, operations, user-field metadata, and system-table layouts.
- `../app/schema.yaml` is an older Directus 11.12.0 snapshot. It remains useful as historical application evidence, but it is not the current production schema. It must remain in place alongside the current snapshot.
- The Markdown files directly under `directus/` are human-readable interpretations of the application source and raw evidence. When prose conflicts with raw evidence, re-check the evidence and update the prose.
- `env.example` is a names-and-placeholders contract. It contains no production values.

The exports intentionally exclude users, user-specific access assignments, credentials, sessions, uploaded data, and flow option values. Consequently, a static credential's actual user/role binding and the detailed behavior inside flows cannot be proven from this material.

## Documents

- `deployment.md`: production topology and explicitly configured versus unobserved settings.
- `auth-contract.md`: application-to-Directus authentication and account operations.
- `permissions.md`: role, policy, field, filter, validation, and preset matrix.
- `flows.md`: flow and operation graphs, with unresolved behavior called out.
- `schema-differences.md`: structural comparison with `../app/schema.yaml`.
- `integration-testing.md`: proposed disposable integration-test environment.

## Refresh procedure

1. Collect from the running production instance without changing it.
2. Sanitize the result before it enters the repository. Exclude secret values, credentials, user rows, email addresses, sessions, cookies, uploaded files, and sensitive flow options.
3. Store a new schema snapshot under `snapshots/`, using a date or version, for example `snapshots/schema-directus-12.1.1-2026-07-10.yaml`. Do not overwrite `schema.yaml` or `../app/schema.yaml` as part of a historical refresh.
4. Store supporting sanitized exports in a correspondingly dated reference location, or clearly record which snapshot they describe.
5. Record the Directus version, database vendor, collection time, and checksums.
6. Compare the new snapshot to the preceding production snapshot and update the human-readable documents only from observed differences.
7. Run a sensitive-data scan and `git diff --check`, then review the complete diff before committing.

The current collection process is described only by its outputs; the exact export commands are not present. That part of the refresh procedure is therefore **unresolved** and should be documented when a repeatable sanitized collection script is added.