Begin UI update starting with Document table.

docs/ui/README.md

@@ -0,0 +1,59 @@
+# UI Documentation
+
+This folder contains UI-focused design and mapping documents that connect the database schema to user-facing workflows.
+
+## Document Types
+
+### user-journey.md
+
+A product and UX contract for a user-facing entity.
+
+Use this document to describe:
+- what the user is trying to do
+- which screen or action starts the workflow
+- which fields the user sees and edits
+- validation rules
+- expected success and failure outcomes
+- where the user goes next
+
+### schema-mapping.md
+
+A field-level mapping between schema, UI, and implementation.
+
+Use this document to describe:
+- the authoritative schema fields for an entity
+- which fields are shown, hidden, editable, or system-managed
+- current implementation behavior
+- intended target behavior
+- implementation gaps between current code and intended UX
+
+## Organization Rules
+
+- Store documents under `docs/ui/entities/<entity-name>/`.
+- Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
+- Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
+- Keep top-level `docs/` reserved for core architecture, requirements, schema, and system-wide reference material.
+
+## Current Entity Plan
+
+User-facing entities:
+- `document`
+- `person`
+- `source`
+- `job`
+
+Supporting entities:
+- `document-person`
+- `job-source`
+
+## Relationship to Core Docs
+
+These UI docs complement, but do not replace:
+- `docs/schema_v2.md`
+- `docs/requirements_v2.md`
+- `docs/architecture_v2.md`
+
+When there is a conflict:
+- schema definitions come from the database model and schema docs
+- user interaction intent comes from the user-journey docs
+- implementation truth comes from code and is recorded in schema-mapping docs as current-state evidence