docs: promote documentation update to main (v2.4.0 release notes)

docs: promote documentation update to main (v2.4.0 release notes)

Author: steilerDev

README.md

@@ -38,7 +38,7 @@ 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 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, 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

RELEASE_SUMMARY.md

@@ -1,55 +1,47 @@
 ## What's New
 
-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.
+This release sharpens the **Budget Overview** so every cost in your project is traceable to the source funding it. Every line in the Cost Breakdown now carries a colored source attribution badge, the **Available Funds** row expands into a per-source Cost / Payback / Net view, and clicking a source detail row toggles it on or off -- with the entire breakdown (totals, projections, and subsidy math) recalculated server-side and the selection persisted in the URL so you can bookmark, share, or refresh a filtered view.
 
 ### What's new
 
-**Area hierarchy, everywhere it matters**
+**Source attribution everywhere**
 
-- 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.
+- Every leaf-level budget line in the Cost Breakdown shows a deterministic, color-coded badge for its financing source -- the same source always gets the same color across the table, between sessions, and in light and dark mode.
+- On desktop the badge shows the full source name; on mobile it collapses to a colored dot to keep rows compact.
+- A 10-slot palette guarantees consistent contrast in both themes; budget lines without a source assignment use a reserved "Unassigned" color.
 
-**Smarter area filters**
+**Available Funds row redesign**
 
-- 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.
+- Click the **Available Funds** row to expand it and see one row per financing source.
+- Each source row shows three numbers in dedicated columns: **Cost** (allocated against budget lines, perspective-aware), **Payback** (subsidy payback against lines funded from that source), and **Net** (remaining headroom after cost and payback).
+- It's the fastest way to spot which source is most depleted, which one is being subsidized, and which one still has slack.
 
-**Budget Overview redesign**
+**Per-source filter**
 
-- 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.
+- Click any source detail row to toggle that source on or off. The entire breakdown -- summary tiles, projected cost range, remaining budget, every nested area row -- recalculates against the visible set.
+- The selection is persisted in the URL as `?deselectedSources=<id>,<id>` so a filtered view can be bookmarked, shared, or reloaded without losing state.
+- Press **Escape** while a source row is focused to clear all deselections in one go.
+- A small "X of N selected" caption appears next to **Available Funds** while a filter is active.
 
-**Budget Sources redesign**
+**Server-side filter pipeline**
 
-- 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`.
+- The new filter is wired through to a single endpoint: `GET /api/budget/breakdown?deselectedSources=...`.
+- Subsidy payback math is computed against the filtered set on the server, so subsidies that no longer have qualifying budget lines drop out cleanly instead of double-counting.
+- Filter changes round-trip in a single request -- no client-side recomputation drift.
 
-**Navigation**
+### Fixes
 
-- **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.
+- Source detail rows stay visible even when every source is deselected, so the filter is never a dead-end.
+- Dark mode contrast and focus ring are corrected on the Cost Breakdown error banner.
 
-**Reliability**
+### Tooling
 
-- 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.
+- The `Quality Gates` workflow now supports `workflow_dispatch`, making it easy to re-run gates manually during a promotion.
 
 ### Breaking changes
 
-None. Existing bookmarks, links, URLs, and data model are preserved.
+None. Existing bookmarks, links, URLs, and data model are preserved. The `?deselectedSources=` query parameter is purely additive -- omit it (or leave it empty) to get the unchanged behavior.
 
 ### 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.
+No database migration is required. The new filter parameter is server-validated and silently ignores unknown source IDs, so older clients that don't send the parameter continue to work without changes.

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

@@ -56,6 +56,37 @@ The cost breakdown table is grouped by your **area hierarchy** rather than by ca
 
 Each row displays the estimated total, invoiced total, subsidy reduction, and remaining amount for that slice of the project.
 
+### Source Attribution Badges
+
+Every leaf-level budget line carries a **source attribution badge** so you can see at a glance which financing source funds each line:
+
+- Each source is assigned a deterministic color from a 10-slot palette -- the same source always gets the same color across the table, between sessions, and in both light and dark mode.
+- On **desktop**, the badge shows the full source name next to a colored dot (long names are truncated with the full name available on hover).
+- On **mobile**, only the colored dot is shown to keep the row compact; tapping the line still opens the full detail.
+- Lines without a source assignment are shown with a neutral "Unassigned" badge in a reserved color slot.
+
+### Available Funds Row
+
+The cost breakdown includes a dedicated **Available Funds** row at the top of the totals section. Click the row to expand it and see one line per financing source, with three columns:
+
+- **Cost** -- how much of that source has been allocated to budget lines (perspective-aware: switches between min, max, and average projection)
+- **Payback** -- the subsidy payback expected against budget lines funded from this source
+- **Net** -- the remaining headroom on that source after subtracting cost and adding back payback
+
+This makes it easy to spot which source is most depleted, which one is being subsidized, and which one still has slack -- all in a single glance.
+
+### Filter by Source
+
+Click any source detail row inside the **Available Funds** expansion to toggle that source on or off. Deselected sources are dropped from the entire breakdown:
+
+- The summary tiles, projected cost range, remaining budget, and every nested area row recalculate against the visible set.
+- A small "X of N selected" caption appears next to **Available Funds** while a filter is active.
+- The selection is **persisted in the URL** as `?deselectedSources=<id>,<id>` so you can bookmark a filtered view, share it with your bank or partner, or refresh without losing state.
+- Press **Escape** while focused on a source row to clear all deselections in one go.
+- Source detail rows stay visible even when every source is deselected -- the filter is never a dead-end; you can always click your way back in.
+
+Filtering happens **server-side** (`GET /api/budget/breakdown?deselectedSources=...`), which means subsidy payback math stays consistent with the visible set: subsidies that no longer have any qualifying budget lines drop out cleanly instead of double-counting.
+
 ## Financing Source Summary
 
 A summary of each financing source shows:

docs/src/guides/budget/index.md

@@ -16,7 +16,7 @@ The budget system provides:
 - **Work Item Budget Lines** -- Link estimated costs to work items with confidence levels that reflect estimate accuracy
 - **Invoices** -- Track vendor invoices and their line-item links to budget lines (vendor records now live under the Settings section -- see [Invoices & Vendors](vendors-and-invoices))
 - **Subsidy Programs** -- Manage percentage-based or fixed-amount subsidies that reduce your effective costs
-- **Budget Overview Dashboard** -- See your project's financial health grouped by **area hierarchy**, with clickable summary tiles, expandable nested rows, and print-friendly styling
+- **Budget Overview Dashboard** -- See your project's financial health grouped by **area hierarchy**, with clickable summary tiles, expandable nested rows, source attribution badges on every line, a per-source filter that updates the entire breakdown, and print-friendly styling
 
 ## How It Fits Together
 
@@ -35,4 +35,4 @@ When a vendor submits an **invoice**, you link the relevant budget lines to the
 - [Work Item Budgets](work-item-budgets) -- Add cost estimates to work items
 - [Invoices](vendors-and-invoices) -- Track invoices and link them to budget lines (vendors are managed from Settings)
 - [Subsidies](subsidies) -- Manage subsidy programs
-- [Budget Overview](budget-overview) -- Area-grouped cost breakdown, clickable tiles, and print output
+- [Budget Overview](budget-overview) -- Area-grouped cost breakdown, source attribution badges, per-source filter, clickable tiles, and print output