docs: update documentation for beta->main promotion (#1332) (#1349)

Refresh user-facing documentation to reflect the area-tree hierarchy
rework, Budget Overview and Budget Sources redesigns, Vendors move into
Settings, tightened reverse-proxy handling, and the TypeScript 6.0
upgrade included in the upcoming stable release.

- docs/src: update work items, household items, budget, and
  getting-started guides to cover area breadcrumbs across the app, the
  "No Area" filter, the area-grouped Budget Overview with clickable
  tiles and print styling, the inline-expansion / multi-select /
  mass-move workflow on Budget Sources, and the narrower trustProxy
  behavior for reverse-proxy users.
- docs/src/guides/budget/vendors-and-invoices.md: document the move of
  Vendors into the Settings section while invoices stay in Budget.
- README.md: refresh the Features section (Work Items, Areas & Trades,
  Budget Management) without touching the protected NOTE block.
- RELEASE_SUMMARY.md: rewrite for this release - area hierarchy,
  Budget Overview + Sources redesign, navigation, reliability, and
  TypeScript 6.0 tooling; note no database migration is required and
  describe the trustProxy behavior change for self-hosters.
- .env.example: add a short note next to TRUST_PROXY explaining that
  only the first proxy hop is trusted and rate limiting is now
  spoof-resistant.

Co-authored-by: Frank Steiler <frank@steiler.de>
Co-authored-by: Claude docs-writer (Opus 4.6) <noreply@anthropic.com>

Author: 3 people

.env.example

@@ -4,7 +4,8 @@ HOST=0.0.0.0
 LOG_LEVEL=info
 NODE_ENV=production
 
-# Set to true when running behind a reverse proxy (e.g., nginx)
+# Set to true when running behind a reverse proxy (e.g., nginx, Caddy, Traefik).
+# Only the first proxy hop is trusted; rate limiting uses a spoof-resistant key.
 # TRUST_PROXY=false
 
 # Public-facing base URL — required when behind a reverse proxy

README.md

@@ -36,9 +36,9 @@ A self-hosted home building project management tool for homeowners. Track work i
 
 ## Features
 
-- **Work Items** -- Manage construction tasks with statuses, dates, area assignments, notes, subtasks, dependencies, and keyboard shortcuts
-- **Areas & Trades** -- Organize your project with hierarchical areas (rooms, floors, zones) and trade specialties (Electrical, Plumbing, etc.) for vendors
-- **Budget Management** -- Budget categories, financing sources, multi-budget-line invoice linking with itemized amounts, subsidies with caps, quotation tracking, and an overview dashboard with projections
+- **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 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

RELEASE_SUMMARY.md

@@ -1,12 +1,55 @@
 ## What's New
 
-This release overhauls every list page in the application with a powerful DataTable system -- bringing filtering, sorting, pagination, and customizable columns to Work Items, Milestones, Vendors, Invoices, Household Items, and User Management. It also adds a full backup and restore capability with scheduled backups and retention policies, configurable from the Settings page.
+This release puts your **project's area hierarchy** at the center of every view. Work items, household items, pickers, budget summaries, and every embedded reference now surface the full area ancestor path (`House / Ground Floor / Kitchen`) as a breadcrumb, so you always know where a task, item, or cost belongs. Budget Sources gains inline expansion with multi-select mass-move, Budget Overview replaces the category breakdown with an expandable area tree and adds clickable summary tiles plus print-friendly output, and Vendors moves into the Settings section to match how the rest of the app is organized.
 
-### Highlights
+### What's new
 
-- **DataTable across all list pages** -- Every list view now supports column-level filtering (text, enum, boolean, date range, number range, and entity filters), multi-column sorting, pagination, column reordering, and persistent column settings.
-- **Backup & Restore** -- Create manual backups or schedule automatic backups with a cron expression. Set a retention policy to automatically prune old backups. Restore from any backup directly in the Settings UI.
-- **Consistent page layout** -- All list pages share a standardized layout with unified navigation, giving the app a more cohesive feel.
-- **Translated category names** -- Predefined categories (trades, budget categories, household item categories) are now displayed in the user's language.
-- **DateRangePicker** -- Date range filters use a purpose-built calendar picker with range highlighting instead of native date inputs.
-- **UI improvements** -- Floating menu button, iPadOS Safari sidebar fix, visual cleanup across multiple pages.
+**Area hierarchy, everywhere it matters**
+
+- Work items and household items display the full area ancestor path as a breadcrumb on list pages, detail pages, and create pages.
+- Pickers (work item, household item, budget line) show the area as a secondary line under each result.
+- Every place a work item is embedded -- diary entries, invoices, household item dependencies -- now includes the area breadcrumb for instant context.
+- A shared `AreaBreadcrumb` component keeps the appearance consistent across the app.
+
+**Smarter area filters**
+
+- The Area filter on Work Items and Household Items lists correctly matches every descendant when you pick a parent area, at any depth of nesting.
+- A dedicated **No Area** option on both lists surfaces items that have not yet been assigned to any area.
+
+**Budget Overview redesign**
+
+- The cost breakdown is now grouped by **area hierarchy** instead of by category, with nested rows you can expand to drill into children and leaf-level budget lines.
+- The old "Unassigned" bucket is renamed **No Area** to match the rest of the app.
+- Every summary tile at the top of the page is clickable -- click a tile to instantly select the underlying budget lines that add up to that number.
+- Full print styling: clean page margins, nested group boxes, inner item separators, and the app's chrome suppressed in print. `Cmd+P` / `Ctrl+P` produces a clean PDF or paper copy.
+
+**Budget Sources redesign**
+
+- Click any financing source to expand it **inline** and see every budget line attached to it -- no navigation away.
+- Budget lines are grouped into a hierarchical **area tree**, with dense columnar rows and horizontal dividers between work item groups.
+- **Multi-select across groups** lets you tick budget lines spread across multiple areas and sources; the selection is preserved as you expand and collapse.
+- A new **mass-move modal** reassigns the entire selection to a different source in a single operation.
+- New API endpoints power this view: `GET /api/budget-sources/:sourceId/budget-lines` and `PATCH /api/budget-sources/:sourceId/budget-lines/move`.
+
+**Navigation**
+
+- **Vendors** has moved out of the Budget subnav into **Settings**. Vendor records are master data -- names, trades, contact info -- so they sit alongside Users, Areas, and Trades. Invoices stay in the Budget section because they are transactional.
+
+**Reliability**
+
+- Reverse-proxy handling is tightened: with `TRUST_PROXY=true`, only the first proxy hop is trusted, and rate limiting uses a resilient client identifier that no longer can be spoofed by a user-supplied `X-Forwarded-For` header. No configuration change is needed to benefit -- upgrading is enough.
+
+**Tooling**
+
+- TypeScript is upgraded to **6.0** with `noUncheckedIndexedAccess` enabled across the codebase, catching a whole class of latent array-access bugs.
+- Docker Scout comparisons against the previous stable tag are now part of the release pipeline.
+
+### Breaking changes
+
+None. Existing bookmarks, links, URLs, and data model are preserved.
+
+### Migration notes
+
+- **No database migration is required.** Area ancestor data is resolved on read -- every response that references a work item, household item, or budget line now includes the full ancestor chain automatically. Existing clients and integrations continue to work; they just see a richer payload.
+- **Reverse-proxy users**: `TRUST_PROXY=true` still means "I am running behind a reverse proxy, please read the forwarded headers," so no setting needs to change. What changes is that the server now trusts only the first proxy hop and computes rate-limit keys in a way that cannot be spoofed by an external `X-Forwarded-For`. If you were previously relying on chained / multi-hop proxy headers being trusted all the way to the origin client, review your proxy topology -- see the [reverse proxy guide](https://steilerDev.github.io/cornerstone/getting-started/docker-setup#behind-a-reverse-proxy) for the current behavior.
+- **Vendors menu move**: Vendors has moved from `Budget > Vendors` to `Settings > Vendors`. Direct URLs to individual vendor detail pages continue to resolve; only the top-level menu entry relocated.

docs/src/getting-started/configuration.md

@@ -32,7 +32,7 @@ All configuration is done through environment variables. The defaults are suitab
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TRUST_PROXY` | `false` | Set to `true` when running behind a reverse proxy (nginx, Caddy, Traefik, etc.) |
+| `TRUST_PROXY` | `false` | Set to `true` when running behind a reverse proxy (nginx, Caddy, Traefik, etc.). Only the first proxy hop is trusted, and rate limiting uses a resilient client identifier that resists `X-Forwarded-For` spoofing. |
 | `EXTERNAL_URL` | -- | Public-facing base URL (e.g., `https://myhouse.example.com`). Used for OIDC callback, CalDAV/CardDAV discovery, and `.mobileconfig` generation. |
 
 When deploying behind a reverse proxy, set `TRUST_PROXY=true` so the server correctly reads forwarded headers (`X-Forwarded-For`, `X-Forwarded-Proto`, etc.). Set `EXTERNAL_URL` to the public URL users access your instance at -- this ensures OIDC callbacks, CalDAV/CardDAV discovery, and Apple configuration profiles work correctly regardless of internal networking.

docs/src/getting-started/docker-setup.md

@@ -49,6 +49,10 @@ SECURE_COOKIES=true
 
 `TRUST_PROXY` tells Cornerstone to read forwarded headers (`X-Forwarded-For`, `X-Forwarded-Proto`, etc.). This is required for secure cookies and OIDC redirects to work properly behind a proxy.
 
+:::note Safer proxy handling
+Cornerstone's proxy handling has been tightened: when `TRUST_PROXY=true`, only the **first** proxy hop is trusted (your own reverse proxy), and the rate-limit plugin uses a resilient client identifier that cannot be spoofed by a user-supplied `X-Forwarded-For` header. In short, you still need to set `TRUST_PROXY=true` when running behind nginx/Caddy/Traefik, but that setting no longer exposes rate limiting to header spoofing from the public internet. No configuration change is required to benefit from this -- upgrading to the current release is enough.
+:::
+
 :::tip Large file uploads
 
 Cornerstone supports photo uploads which can produce large request payloads. Most reverse proxies limit request body size by default (e.g., nginx defaults to 1 MB). Make sure your proxy is configured to allow sufficiently large uploads -- for example, in **nginx**:

docs/src/guides/budget/budget-overview.md

@@ -5,7 +5,11 @@ title: Budget Overview
 
 # Budget Overview
 
-The budget overview dashboard at **Budget > Overview** gives you a high-level view of your project's financial health. It shows totals by budget category, financing source allocations, and four different "remaining budget" perspectives.
+The budget overview dashboard at **Budget > Overview** gives you a high-level view of your project's financial health. It surfaces totals across financing sources, four different "remaining budget" perspectives, and a cost breakdown grouped by **area hierarchy**.
+
+## Summary Tiles
+
+At the top of the overview you see a set of summary tiles -- Total Budget, Total Estimated, Total Invoiced, Total Remaining, and one per financing source. Each tile is **clickable**: clicking a tile selects every matching budget line in the table below, so you can jump straight from a headline number into the underlying lines that drive it. Click the same tile again (or click in empty space) to clear the selection.
 
 ## Remaining Budget Perspectives
 
@@ -41,13 +45,16 @@ The margin applied to non-invoiced budget lines depends on the confidence level:
 | Quote | +/- 5% |
 | Invoice | 0% (actual cost used) |
 
-## Category Breakdown
+## Cost Breakdown by Area
 
-The overview groups costs by budget category, showing:
+The cost breakdown table is grouped by your **area hierarchy** rather than by category. This makes it easy to see what each room, floor, or zone of the project actually costs.
 
-- Total estimated amount for the category
-- Progress bar indicating how much has been invoiced vs estimated
-- Subsidy reductions applied to the category
+- Each **area** is a row. Its totals roll up every descendant area beneath it.
+- Clicking a row expands it to show child areas and, at the leaf level, the individual budget lines.
+- Nested rows are visually indented so the tree is easy to scan.
+- Budget lines whose work item or household item has no area assigned are collected in a dedicated **No Area** bucket at the bottom of the table (previously labeled "Unassigned").
+
+Each row displays the estimated total, invoiced total, subsidy reduction, and remaining amount for that slice of the project.
 
 ## Financing Source Summary
 
@@ -57,8 +64,24 @@ A summary of each financing source shows:
 - Current depletion (based on actual invoice costs)
 - Remaining balance
 
+For a much deeper view of each source -- including every budget line attached to it, grouped by area and work item, with multi-select and mass-move -- see [Financing Sources](financing-sources).
+
 ## Subsidy Impact
 
 Approved and disbursed [subsidies](subsidies) are factored into the overview calculations. The dashboard shows how much each subsidy reduces the total cost for its linked category. Pending and rejected subsidies are excluded from calculations.
 
+## Printing the Overview
+
+The Budget Overview has dedicated **print styling** so you can hand your bank, accountant, or partner a clean PDF or paper copy.
+
+- Use your browser's Print command (`Cmd+P` on macOS, `Ctrl+P` on Windows/Linux) directly from the overview page.
+- The app chrome -- sidebar, navigation, floating buttons -- is suppressed in print.
+- Page margins, title spacing, and nested area group boxes are tuned for A4/Letter output.
+- Inner item separators keep individual budget lines readable when an area group contains many children.
+- The browser's own print header/footer is suppressed; pick your target (printer or "Save as PDF") and go.
+
+:::tip
+If the exported PDF does not match what you see on screen, make sure your browser's "Background graphics" option is enabled in the print dialog -- the nested group boxes rely on background color to stay legible.
+:::
+
 ![Budget overview dashboard](/img/screenshots/budget-overview-light.png)

docs/src/guides/budget/financing-sources.md

@@ -5,7 +5,7 @@ title: Financing Sources
 
 # Financing Sources
 
-Financing sources represent where the money for your construction project comes from. Each source has a total amount, and Cornerstone tracks how much of each source has been depleted based on actual invoice costs.
+Financing sources represent where the money for your construction project comes from -- your construction loan, savings, a family loan, a subsidy. Each source has a total amount, and Cornerstone tracks how much of each source has been depleted based on actual invoice costs.
 
 ## Examples
 
@@ -15,30 +15,52 @@ Financing sources represent where the money for your construction project comes
 
 ## Creating a Financing Source
 
-Navigate to **Budget > Financing Sources** in the sidebar. Click **New Source** and provide:
+Navigate to **Budget > Sources** in the sidebar. Click **New Source** and provide:
 
 - **Name** -- A descriptive label (e.g., "Construction Loan")
 - **Total Amount** -- The total amount available from this source
 
 ## Depletion Tracking
 
-Each financing source displays how much has been spent. Depletion is calculated from the actual cost of invoices linked to budget lines that use this source:
+Each financing source shows how much has been spent. Depletion is calculated from the actual cost of invoices linked to budget lines that use this source:
 
 - **Invoiced amounts** are summed to show how much of the source has been used
 - A progress bar shows the percentage depleted
 - The remaining balance updates automatically as invoices are added
 
-This gives you a clear picture of how much funding remains in each source.
+## Inline Budget Line Expansion
+
+Click any source row on the sources page to expand it inline and see **every budget line attached to that source** directly beneath it -- no navigation away, no separate tab. The expanded panel is structured as a **hierarchical area tree** so you can see exactly which rooms, floors, and zones the source is funding:
+
+- Budget lines are grouped first by their **work item or household item**, with the full area breadcrumb (e.g. `House / Ground Floor / Kitchen`) shown next to the group header.
+- Work item groups are separated by horizontal dividers for easy scanning.
+- Each budget line is a **dense columnar row** showing the category, planned amount, invoiced amount, and status.
+- Clicking a work item or household item link jumps to that item's detail page, with the correct area ancestor resolved.
+
+![Financing sources page with inline expansion](/img/screenshots/budget-sources-light.png)
+
+## Multi-Select and Mass-Move
+
+Need to reassign a batch of budget lines from one source to another -- for example, when a subsidy payout comes in and you want to move those lines off your construction loan? The sources page supports **multi-select across groups**:
+
+1. Expand one or more sources.
+2. Tick the checkboxes next to any number of budget lines -- your selection is **preserved as you expand and collapse different areas or sources**, so you can build up a batch across the tree.
+3. Click **Move selected** to open the **mass-move modal**.
+4. Pick the target financing source and confirm.
+
+Every selected line is reassigned to the new source in a single operation, and the depletion totals on both the source you moved from and the source you moved to update immediately.
+
+:::tip
+The mass-move modal is the fastest way to model a "what if" on your budget -- for example, splitting costs that were originally booked against your savings onto a newly approved loan, without editing each budget line individually.
+:::
 
 ## Managing Sources
 
-From the financing sources page you can:
+From the sources page you can:
 
 - **Edit** a source's name or total amount
 - **Delete** a source that is no longer needed
 
 :::caution
-Deleting a financing source will fail if any budget lines reference it. Reassign or remove those budget lines first.
+Deleting a financing source will fail if any budget lines reference it. Use mass-move to reassign those lines first, then delete.
 :::
-
-![Financing sources page](/img/screenshots/budget-sources-light.png)