release: promote photo-annotator polish to main

.env.example

@@ -24,7 +24,8 @@ SECURE_COOKIES=true
 
 # ─── Diary ─────────────────────────────────────────────
 # DIARY_AUTO_EVENTS=true                                # Set to false to disable automatic diary event logging
-# PHOTO_STORAGE_PATH=/app/data/photos                   # Directory for diary photo attachments
+# DIARY_DRAFT_RETENTION_DAYS=30                         # Days a draft entry sits untouched before automatic cleanup (0 = disabled)
+# PHOTO_STORAGE_PATH=/app/data/photos                   # Directory for diary photo attachments (originals + annotated copies)
 # PHOTO_MAX_FILE_SIZE_MB=20                             # Maximum photo upload size in MB
 
 # ─── OIDC ──────────────────────────────────────────────

CLAUDE.md

@@ -150,6 +150,20 @@ echo "Waiting for Quality Gates + E2E Gates..."; SECONDS=0; while true; do if [
 
 Replace `<PR>` with the PR number. The polling loop handles the "checks not yet reported" edge case — an empty bucket means we retry after 30s. Timeouts prevent agents from polling indefinitely if CI hangs.
 
+#### Auto-fix Bot `[skip ci]` Workaround
+
+The auto-fix bot (`.github/workflows/auto-fix.yml`) pushes cosmetic lint/format commits to `beta` with `[skip ci]` in the commit message. When that push lands on top of a recently-merged squash on `beta`, it advances the HEAD of any open `beta -> main` PR (e.g., the promotion PR) to a SHA that has **no CI runs** — leaving the PR `MERGEABLE` but `BLOCKED` on required checks that will never report.
+
+Symptoms: `gh pr checks <PR>` returns nothing for `Quality Gates` / `E2E Gates`; `gh run list --commit <sha>` is empty; PR is `BLOCKED` even though the prior HEAD's checks passed.
+
+**Fix:** the `Quality Gates` workflow exposes `workflow_dispatch:` for exactly this case. Re-trigger CI manually on the affected branch:
+
+```bash
+gh workflow run ci.yml --repo steilerDev/cornerstone --ref beta
+```
+
+GitHub reports the resulting `Quality Gates` / `E2E Gates` check buckets against the branch HEAD SHA, which is the same SHA the PR uses — so the required checks are satisfied automatically and the PR unblocks. Use the same polling pattern above (main variant for promotion PRs) to wait for completion. Do not push an empty/no-op commit just to retrigger CI — the dispatch is cleaner and avoids cluttering the commit log.
+
 ### GitHub Rate-Limit Retry Policy
 
 When `gh` or `git push` commands fail with a GitHub rate-limit error (primary API limit, secondary abuse limit, or `HTTP 403`/`HTTP 429` with a rate-limit message), retry with **exponential backoff** instead of aborting:

README.md

@@ -38,12 +38,12 @@ A self-hosted home building project management tool for homeowners. Track work i
 
 - **Work Items** -- Manage construction tasks with statuses, dates, area assignments, notes, subtasks, dependencies, and keyboard shortcuts -- every work item shows its full area ancestor path (e.g. `House / Ground Floor / Kitchen`) as a breadcrumb across lists, detail pages, pickers, and every place it is referenced
 - **Areas & Trades** -- Organize your project with hierarchical areas (rooms, floors, zones) and trade specialties (Electrical, Plumbing, etc.) for vendors; a dedicated "No Area" filter surfaces items that have not been classified yet
-- **Budget Management** -- Budget categories, financing sources with inline expansion and mass-move of attached lines, multi-budget-line invoice linking with itemized amounts, subsidies with caps, quotation tracking, and an area-grouped overview dashboard with source attribution badges on every line, a per-source filter (URL-persisted, server-side) that updates totals and subsidy math, clickable summary tiles, and print-friendly export
+- **Budget Management** -- Budget categories, financing sources with inline expansion and mass-move of attached lines, multi-budget-line invoice linking with itemized amounts, staged-payment deposits for invoices paid in instalments (deposit-aware paid/claimed rollups), subsidies with caps, quotation tracking, and an area-grouped overview dashboard with source attribution badges on every line, a per-source filter (URL-persisted, server-side) that updates totals and subsidy math, clickable summary tiles, and print-friendly export
 - **Timeline & Gantt Chart** -- Interactive Gantt chart with dependency arrows, critical path, zoom controls, milestones, and CPM-based auto-scheduling
 - **Calendar View** -- Monthly and weekly calendar grids with work items and milestones
 - **Household Items** -- Track furniture, appliances, and fixtures with categories, area assignment, delivery scheduling, budget integration, and work item linking
 - **Project Dashboard** -- At-a-glance project health with budget, timeline, invoice, and subsidy cards, mini Gantt preview, and customizable layout
-- **Construction Diary** -- Daily logs, site visits, delivery records, automatic system events, photo attachments, and digital signature capture
+- **Construction Diary** -- Daily logs, site visits, delivery records, automatic system events, photo attachments with in-browser annotation (rectangles, arrows, text, measurements, freehand), auto-saved drafts, and digital signature capture
 - **Document Integration** -- Browse and link documents from Paperless-ngx to work items, household items, and invoices
 - **Advanced List Views** -- Filter, sort, paginate, and customize columns across all list pages with the shared DataTable system
 - **Backup & Restore** -- Manual and scheduled backups with configurable retention, restore from the settings UI

RELEASE_SUMMARY.md

@@ -1,42 +1,70 @@
-# v2.5.0 Release Summary
+# v2.6.0 Release Summary
 
-A focused release that adds **Backup & Restore**, tightens budget VAT handling, and slims down the Budget Overview page. Migration 0031 backfills `includes_vat` on existing budget lines, runs automatically on first start, and requires no manual intervention.
+A feature-packed release that brings **in-browser photo annotation**, **staged-payment deposits** for invoices, and a much smoother **diary draft flow**. Migration 0032 (invoice deposits) runs automatically on first start -- no manual steps required.
 
 ## What's New
 
-- **Backup & Restore** -- Cornerstone now ships with a built-in backup feature that snapshots your entire app data directory (SQLite database + diary photos) into a single `tar.gz` archive. Trigger backups manually from the admin UI, run them on a cron schedule, set a retention limit, and restore from any archive in two clicks. Mount a separate volume to `/backups` (or wherever you point `BACKUP_DIR`) and you're set. See the [Backups guide](https://steilerDev.github.io/cornerstone/guides/backup) for setup, scheduling, and restore steps. (#1386)
+### Photo Annotation
 
-## Improvements
+Mark up diary photos directly in the browser. Open any diary photo in the viewer, click **Annotate**, and you get a full drawing canvas with nine tools:
 
-- **Consistent VAT handling across budget lines** (#1385) -- Direct pricing mode now applies the same VAT multiplier as unit pricing (quantity × unit price), so the **Price includes VAT** checkbox behaves identically regardless of which pricing mode you use. Planned amounts are now always stored as gross internally, which means the Budget Overview, Available Funds row, and printed reports compare every line on a like-for-like basis. The `includes_vat` flag is now `NOT NULL` at the database level (defaults to `true`); migration 0031 backfills any pre-existing `NULL` values.
+- **Select**, **Rectangle**, **Highlight**, **Arrow**, **Line**, **Ellipse**, **Text**, **Measurement** (dimension line with end ticks and a movable label), and **Freehand**
+- Six colours, four stroke widths, five font sizes -- pick before you draw, or change them on a selected shape to update it live
+- Drag to move, endpoint handles to reshape, undo/redo for everything including live edits
+- Annotated copies are saved as separate WebP files (quality 0.92); the original is preserved, and you can switch between **View original** and **View annotated** at any time
+- A **Reset to original** button discards your current annotations and starts over
+- Photo grids and viewers expose a quick-action **Edit** button that opens the viewer directly in annotation mode
 
-## Bug Fixes
+Signed diary entries cannot be annotated -- finish your markup before collecting signatures.
 
-- **Budget Overview is now the breakdown** (#1389) -- The Budget Health hero card has been removed from the top of the page. The overview now goes straight from the title bar into the Cost Breakdown Table. The Min / Avg / Max perspective toggle, source-filter, and Available Funds row all live inside the table and remain unchanged. The page is faster, prints cleaner, and removes a layer of summary metrics that mostly duplicated what the breakdown already shows.
-- **Source name now prints on the Budget Overview** (#1390) -- Print viewports (around 600-720 px) used to trigger the mobile breakpoint, which collapsed the source attribution badge to just a colored dot -- great on a phone, useless on a printout. Print mode now forces the full source name visible with a border-based color treatment, so the printed report shows the actual source attached to each budget line.
-- **Broken docs links on the Budget Overview page** (#1384) -- The "Related Pages" links to Work Items and Household Items pointed to non-existent `/overview` sub-paths and now point to the correct guide indices.
+See the [Photo Annotation guide](https://steilerDev.github.io/cornerstone/guides/diary/photo-annotation) for the full walkthrough.
 
-## What to Update
+### Invoice Deposits (Staged Payments)
 
-```bash
-docker pull steilerdev/cornerstone:latest
-```
+Track invoices that are paid in stages -- a deposit on signing, a milestone payment, and a final balance.
 
-Restart your container. Migration 0031 runs automatically on first start.
+- Add any number of deposits to an invoice from the **Deposits** section on the invoice detail page
+- Each deposit has its own amount, due date, status (Pending / Paid / Claimed), paid/claimed dates, and optional description
+- The form refuses to save if deposits would exceed the invoice total
+- Quick actions to **mark paid** and **mark claimed** -- with revert support to fix mistakes
+- Budget rollups across every linked work item and household item are now **deposit-aware**: `actualCostPaid` and `actualCostClaimed` reflect deposit-level status, so paid and claimed amounts show real cash flow rather than waiting for the full invoice to settle
+- Deposits cascade-delete with the parent invoice
 
-If you want to enable the new backup feature, mount a backup volume:
+See the [Invoice Deposits guide](https://steilerDev.github.io/cornerstone/guides/budget/invoice-deposits).
 
-```bash
-docker run -d \
-  --name cornerstone \
-  -p 3000:3000 \
-  -v cornerstone-data:/app/data \
-  -v cornerstone-backups:/backups \
-  steilerdev/cornerstone:latest
-```
+### Diary Drafts Overhaul
+
+Creating a diary entry no longer needs a separate "create" step.
+
+- Click a type card (Daily Log, Site Visit, Delivery, Issue, General Note) and Cornerstone immediately creates a **draft entry** and opens the edit page -- you start typing right away
+- Photos uploaded to a draft persist immediately, so you don't have to remember to "save" before attaching them
+- Auto-save runs continuously with a live status indicator (`Saving...`, `Saved`, or "save failed -- will retry")
+- Drafts are tagged with a **Draft** badge and **hidden from the diary list by default**; a dedicated **Drafts** filter chip toggles their visibility
+- Click **Save** to promote the draft to a full entry, or **Discard Draft** to delete it (and its photos) permanently
+- Abandoned drafts are cleaned up automatically after `DIARY_DRAFT_RETENTION_DAYS` days (default: 30; set to `0` to disable)
+
+### Photo Viewer Improvements
 
-Optionally set `BACKUP_CADENCE` (e.g., `0 2 * * *` for daily at 2 AM) and `BACKUP_RETENTION` (e.g., `7` to keep a week's worth of archives).
+- New **photo metadata sidepanel** with upload date, description, and area assignment
+- **Edit** quick-action button on the photo grid that opens the viewer directly in annotation mode
+- **Delete photo** action from the lightbox for entries that aren't signed
+- Thumbnail cache busting -- annotated thumbnails update immediately
+- Mobile-friendly: the metadata sidepanel collapses on small screens
 
----
+## Configuration
+
+New environment variable:
+
+| Variable                     | Default | Description                                                                   |
+| ---------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `DIARY_DRAFT_RETENTION_DAYS` | `30`    | Days an untouched draft sits before automatic cleanup. Set to `0` to disable. |
+
+No other configuration changes are required. Migration 0032 adds the `invoice_deposits` table and runs automatically on container start.
+
+## What to Update
+
+```bash
+docker pull steilerdev/cornerstone:latest
+```
 
-_Released: 2026-05-03_
+Restart your container. Schema migrations run on first boot.

client/src/components/photos/PhotoAnnotator/PhotoAnnotator.test.tsx

@@ -356,28 +356,13 @@ describe('PhotoAnnotator', () => {
     }
   });
 
-  it('shows Reset button when photo.annotatedAt is set', async () => {
-    const annotatedAt = '2026-05-17T10:00:00.000Z';
-    await renderAnnotator({ annotatedAt });
-    // Reset button — text from t('reset') = "Reset to original"
-    expect(screen.getByRole('button', { name: /Reset to original/i })).toBeInTheDocument();
-  });
-
-  it('clicking Reset button opens confirmation modal', async () => {
+  it('does NOT show in-annotator Reset button on an annotated photo', async () => {
+    // Reset button was removed; the PhotoViewer "Clear annotations" entry-point covers this.
     await renderAnnotator({ annotatedAt: '2026-05-17T10:00:00.000Z' });
-
-    const resetBtn = screen.getByRole('button', { name: /Reset to original/i });
-    fireEvent.click(resetBtn);
-
-    // Modal renders with a dialog role (from the Modal stub)
-    await waitFor(() => {
-      expect(screen.getByRole('dialog')).toBeInTheDocument();
-    });
+    expect(screen.queryByTestId('annotator-reset')).not.toBeInTheDocument();
   });
 
-  it('does NOT show Reset button when photo has no annotations (annotatedAt is null)', async () => {
-    // Reset button is conditional on photo.annotatedAt — it only appears for previously-annotated
-    // photos. When annotatedAt is null the button must be absent (E2E compatibility: round-7 behavior).
+  it('does NOT show Reset button when photo has no annotations', async () => {
     await renderAnnotator({ annotatedAt: null });
     expect(screen.queryByTestId('annotator-reset')).not.toBeInTheDocument();
   });