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

docs/ui/pages/home.md

@@ -0,0 +1,63 @@
+# Home Page Contract
+
+## Purpose
+
+Home provides a user-maintained landing page for the local archive. It combines one current image with Markdown text and lets the operator edit both without changing application source or prompt assets.
+
+## Routes
+
+| Route | Browser path | Purpose |
+| --- | --- | --- |
+| `/homepage` | `/ui/homepage` | View current homepage image and Markdown. |
+| `/homepage/edit` | `/ui/homepage/edit` | Upload an image and edit Markdown. |
+
+The application root and `/ui` redirect to `/ui/homepage`.
+
+## View Behavior
+
+- The visible page heading is **Home**; the browser tab title is **VibeScribe Home**.
+- The latest homepage image appears in the shared dark-room viewer.
+- Saved Markdown is rendered in the **Home Text** card.
+- Missing text displays `No homepage text saved yet.`
+- Missing image displays the viewer's empty state.
+- **Edit Home Page** opens the edit route.
+
+## Edit Behavior
+
+- The image upload accepts JPEG, PNG, GIF, WebP, BMP, and TIFF files.
+- A successful upload immediately stores the file, updates the preview to that image, and displays a positive notification.
+- The Markdown textarea is initialized from the currently stored homepage text.
+- **Save** writes the textarea content, displays `Homepage saved`, and returns to Home.
+- **Cancel** returns to Home without saving textarea changes. An image already uploaded during the edit session remains stored.
+
+## Storage Contract
+
+- Homepage content is mutable application data under `data/homepage`.
+- Markdown is stored in `homepage.md`.
+- Uploaded images keep a sanitized basename.
+- The view selects the supported image with the most recent modification time.
+- Homepage files are not transcription prompts and are not database records.
+
+## Acceptance Checklist
+
+- `/`, `/ui`, and the application brand reach Home.
+- Home renders with or without stored Markdown and image content.
+- Edit loads existing Markdown.
+- A supported image upload updates the preview and becomes the latest homepage image.
+- Save persists Markdown and returns to Home.
+- Cancel does not save changed Markdown.
+
+## Implementation Anchors
+
+- `src/transcription/ui/pages/home_page.py`
+- `src/transcription/ui/homepage_store.py`
+- `src/transcription/ui/components/app_shell.py`
+- `tests/ui/test_upload_page.py`
+- `tests/ui/test_navigation_and_mounts.py`
+- `tests/ui/test_pages_registration.py`
+
+## Known Limitations
+
+- Homepage storage is fixed under the repository/application `data` directory rather than a configured application-data root.
+- Uploading an image is immediate and is not rolled back by Cancel.
+- The editor does not currently delete or select among previously uploaded images.