V4.1 major revision to docs. Removed all obsolete documents, updated v4.2 implementation scope and plan.

2026-08-13 15:32:40 -05:00
parent 171132919d
commit 28811d79ce
60 changed files with 1170 additions and 7471 deletions
@@ -1,80 +1,60 @@
-# UI Documentation
+# UI Behavioral Contracts

-This folder contains UI-focused design and mapping documents that connect the database schema to user-facing workflows.
+## Purpose

-## Document Types
+This directory defines the current user-facing behavior of the NiceGUI application. It records what each page is for, which routes and actions it exposes, what information it presents, and how success, empty, validation, and failure states behave.

-### user-journey.md
+These documents are written for maintainers and AI contributors. They are behavioral contracts, not historical implementation notes and not substitutes for the database schema.

-A product and UX contract for a user-facing entity.
+## Current Page Contracts

-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
+- [Home](pages/home.md)
+- [Documents](pages/documents.md)
+- [People](pages/people.md)
+- [Jobs](pages/jobs.md)
+- [Sources](pages/sources.md)

-### schema-mapping.md
+NiceGUI registers the routes shown in each contract without the `/ui` prefix. The application mounts NiceGUI under `/ui`, so `/documents` in page code is served to a browser as `/ui/documents`.

-A field-level mapping between schema, UI, and implementation.
+## Authority Hierarchy

-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
+When documents disagree, use this order:

-### acceptance-criteria.md
+1. User-facing page intent and accepted behavior: the page contracts in this directory.
+2. Visual and interaction styling: [UI Style Guide](../invariant/ui_style_guide.md).
+3. UI dependency and ownership boundaries: [UI contributor instructions](../../.github/instructions/ui.instructions.md).
+4. Durable failure behavior: [Error Handling invariant](../invariant/error_handling.md).
+5. Durable AI evidence behavior: [Digital Evidence and AI Processing Provenance](../invariant/ai_evidence_and_provenance.md).
+6. Data definitions and relationships: current models plus the [V4 schema](../ver4/schema_v4.md).
+7. Planned behavior changes: the applicable V4.x scope and implementation documents.
+8. Implementation truth: current code and tests.

-An implementation-ready checklist for CRUD behavior and quality gates.
+If code intentionally changes accepted page behavior, update the corresponding page contract in the same change. If code accidentally differs, correct the implementation rather than rewriting intent to match a defect.

-Use this document to describe:
- testable acceptance statements by flow (Create, Read, Update, Delete)
- success and failure behaviors
- first-release constraints
- cross-criteria quality gates
+## Contract Contents

-### traceability-matrix.md
+Each page contract contains:

-A criteria-to-code mapping that identifies implementation anchors and status.
+1. Purpose and user goals.
+2. Registered routes and navigation context.
+3. List, detail, and form behavior.
+4. Editable and system-managed information.
+5. Validation, empty, loading, and failure states.
+6. A concise acceptance checklist.
+7. Current implementation and test anchors.
+8. Known limitations and deferred work.

-Use this document to describe:
- acceptance criteria group to implementation file mapping
- delivery status (implemented, partial, planned)
- ordered implementation priorities
+## Maintenance Rules

-## Organization Rules
+- Describe current accepted behavior in present tense.
+- Do not mix an obsolete “first release” design with current behavior.
+- Keep future changes in versioned scope documents and link to them from a Deferred Work section.
+- Do not reproduce the complete database field inventory here; include only fields that affect page behavior.
+- Keep service, file, and test anchors current.
+- Do not create separate current-state, target-state, and traceability copies of the same contract.
+- Keep cross-page visual rules in the UI Style Guide instead of repeating them on each page.
+- Keep database joins such as `DocumentPerson` and `JobSource` in schema/architecture documentation unless they directly affect a page interaction.

- Store documents under `docs/ui/entities/<entity-name>/`.
- Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
- Create `acceptance-criteria.md` for user-facing entities.
- Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
- Keep one shared `traceability-matrix.md` under `docs/ui/entities/` to map criteria to implementation anchors.
- Keep top-level `docs/` reserved for core architecture, requirements, schema, and system-wide reference material.
+## Current Baseline

-## 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
+These contracts describe the V4 baseline with completed V4.1 UI behavior. Planned V4.2 evidence/provenance changes and draft V4.3 Settings/page-reordering changes are not described as current behavior.