v0.4.0 release

.env.example

@@ -1,5 +1,12 @@
-# Encryption Key for Budget Files
-# Generate a secure random key for production use
-# You can use: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-VITE_ENCRYPTION_KEY=your-secure-encryption-key-here
+# Feedback Form Configuration
+# Google Form prefill URL (from your Google Form "Get prefilled link")
+# To get this: Open the form > Click menu (⋮) > Get prefilled link
+FEEDBACK_FORM_URL="https://docs.google.com/forms/d/e/YOUR_FORM_ID/viewform"
 
+# Google Form entry IDs for prefilling form fields
+# Get these by opening the form in edit mode, right-clicking input fields, and inspecting the HTML for entry.XXXXX values
+# Or use the browser's Network tab after submitting a test response and look for the entry parameters
+FEEDBACK_FORM_ENTRY_EMAIL="entry.XXXXXXXXXX"
+FEEDBACK_FORM_ENTRY_CATEGORY="entry.XXXXXXXXXX"
+FEEDBACK_FORM_ENTRY_SUBJECT="entry.XXXXXXXXXX"
+FEEDBACK_FORM_ENTRY_DETAILS="entry.XXXXXXXXXX"

.github/workflows/beta-release.yml

@@ -50,10 +50,32 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libsecret-1-dev libnss3-dev pkg-config fakeroot dpkg
 
+      - name: Build Electron app for macOS (signed + notarized)
+        if: matrix.os == 'macos-latest'
+        run: npm run build:${{ matrix.target }}
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: true
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          FEEDBACK_FORM_URL: ${{ vars.FEEDBACK_FORM_URL }}
+          FEEDBACK_FORM_ENTRY_EMAIL: ${{ vars.FEEDBACK_FORM_ENTRY_EMAIL }}
+          FEEDBACK_FORM_ENTRY_CATEGORY: ${{ vars.FEEDBACK_FORM_ENTRY_CATEGORY }}
+          FEEDBACK_FORM_ENTRY_SUBJECT: ${{ vars.FEEDBACK_FORM_ENTRY_SUBJECT }}
+          FEEDBACK_FORM_ENTRY_DETAILS: ${{ vars.FEEDBACK_FORM_ENTRY_DETAILS }}
+
       - name: Build Electron app for ${{ matrix.target }}
+        if: matrix.os != 'macos-latest'
         run: npm run build:${{ matrix.target }}
         env:
           CSC_IDENTITY_AUTO_DISCOVERY: false
+          FEEDBACK_FORM_URL: ${{ secrets.FEEDBACK_FORM_URL }}
+          FEEDBACK_FORM_ENTRY_EMAIL: ${{ secrets.FEEDBACK_FORM_ENTRY_EMAIL }}
+          FEEDBACK_FORM_ENTRY_CATEGORY: ${{ secrets.FEEDBACK_FORM_ENTRY_CATEGORY }}
+          FEEDBACK_FORM_ENTRY_SUBJECT: ${{ secrets.FEEDBACK_FORM_ENTRY_SUBJECT }}
+          FEEDBACK_FORM_ENTRY_DETAILS: ${{ secrets.FEEDBACK_FORM_ENTRY_DETAILS }}
 
       - name: Upload beta artifacts
         uses: actions/upload-artifact@v4

README.md

@@ -25,7 +25,10 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 - **Estimated taxes**: View federal, state, Social Security, Medicare, and additional withholdings
 - **Deductions tracking**: Monitor pre-tax and post-tax deductions
 - **Multiple views**: Switch between per-paycheck, monthly, and yearly perspectives
+- **Expanded cadence views**: Use weekly, bi-weekly, semi-monthly, monthly, quarterly, and yearly modes
+- **Paycheck-cadence defaults**: Automatically start in your paycheck cadence view with visible cadence cues
 - **Key metrics dashboard**: High-level summary of income, deductions, bills, and remaining funds
+- **Plan-wide search**: Jump directly to settings, sections, and common actions from one searchable overlay
 - **Customizable tabs**: Show/hide dashboard tabs, reorder tabs, manage your view
   - Manage Tabs button for tab customization
   - All tabs can be shown/hidden (at least one must remain visible)
@@ -47,6 +50,12 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 - Assign bills to specific accounts
 - Automatic calculation of per-paycheck and annual impact
 - View total bill allocation vs. remaining funds
+- Mark items as discretionary to control what is eligible for automated reallocation
+
+#### Smart Reallocation
+- Automatically rebalance eligible spending categories when Remaining falls below target
+- Uses safe-source guardrails (for example discretionary items and configurable contribution categories)
+- Review a clear summary of all amount changes after each automated reallocation
 
 #### Benefits & Deductions
 - Add any employer-provided benefits (health insurance, FSA, HSA, etc.)
@@ -77,6 +86,7 @@ Walk through initial configuration with an intuitive step-by-step wizard:
   - Social Security (6.2% default)
   - Medicare (1.45% default)
   - Additional withholding amounts
+- Configure tax lines as either percentages or fixed dollar amounts to match pay-stub behavior
 - Instant recalculation of net pay as you adjust rates
 
 ### 5) Plan Management
@@ -94,6 +104,10 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 - **Recent files**: Automatic tracking of recently opened plans
 - **Session persistence**: Window size, position, and active tab saved and restored
 
+#### Change Recovery & Audit History
+- **Undo/Redo support**: Reverse or reapply plan edits across core workflows
+- **Audit history overlay**: Review notable changes and roll back targeted edits when needed
+
 #### Export & Sharing
 - **PDF export**: Generate comprehensive PDF reports
   - Optional password protection for PDFs
@@ -107,6 +121,12 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 - **Cmd+N / Ctrl+N**: New budget plan
 - **Cmd+O / Ctrl+O**: Open existing plan
 - **Cmd+S / Ctrl+S**: Save current plan
+- **Cmd+Z / Ctrl+Z**: Undo
+- **Cmd+Shift+Z / Ctrl+Y**: Redo
+- **Cmd+F / Ctrl+F**: Open plan search
+- **Cmd+Plus / Ctrl+Plus**: Zoom in
+- **Cmd+Minus / Ctrl+Minus**: Zoom out
+- **Cmd+0 / Ctrl+0**: Reset zoom
 - **Keyboard shortcuts reference**: View a full list of all available shortcuts from the Help menu
 
 #### Native Menus
@@ -117,7 +137,7 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 - **Help menu**: Glossary, keyboard shortcuts reference, support/feedback
 
 #### Application Features
-- **Settings panel**: Configure theme (light/dark/system), enable/disable glossary tooltips
+- **Settings panel**: Configure appearance presets, dark-mode behavior, high-contrast mode, zoom/font scaling, and glossary tooltips
 - **Glossary**: Built-in financial terms reference accessible from Help menu or inline tooltips
 - **Keyboard shortcuts reference**: View all available shortcuts in a dedicated in-app dialog, accessible from the Help menu
 - **In-app feedback**: Submit bug reports and feature requests directly from within the app via the Help menu
@@ -128,10 +148,14 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 ### 7) User Interface & Experience
 
 #### Theme Support
-- **Light mode**: Clean, professional light theme
-- **Dark mode**: Eye-friendly dark theme
-- **System theme**: Automatically match your OS preference
-- **Persistent preference**: Theme choice saved across sessions
+- **Curated preset pairs**: Choose from more polished light/dark appearance presets
+- **Manual dark-mode overrides**: Adjust dark behavior independently when preferred
+- **High-contrast mode**: Boost readability and separation for accessibility-sensitive workflows
+- **Persistent preference**: Appearance choices saved across sessions
+
+#### Visual Refresh
+- App-wide Lucide iconography replaces legacy emoji indicators
+- Account icon picker lets you choose from a larger icon catalog per account
 
 #### Glossary & Help
 - **Interactive tooltips**: Hover over or click glossary terms for definitions
@@ -175,7 +199,7 @@ Walk through initial configuration with an intuitive step-by-step wizard:
 
 ### macOS: "App is damaged and can't be opened"
 
-If you see this error on macOS, it's because the app is not code-signed with an Apple Developer certificate. This is normal for open-source apps. To open the app:
+Official release builds are signed and notarized for macOS. If you still see this warning, it is usually due to a stale or partially downloaded artifact, or because you are running a local unsigned build. To open the app:
 
 **Option 1: Terminal command (remove quarantine flag)**
 1. Open Terminal

RELEASE_NOTES.md

@@ -6,28 +6,23 @@
 
 ### Features
 
-- Added a dedicated modal to edit plan name and plan year, including preset year options and validated custom year entry.
-- Added pause/resume support for deduction items to match other financial item cards.
-- Redesigned Key Metrics tab with a unified breakdown card offering three switchable views: Bars (individual flow bars per category), Stacked (proportional bar across all segments), and Pie (SVG donut chart with hover interactions). Selected view is persisted per plan file.
-- Added a semantic color system to the Key Metrics breakdown: expense categories use distinct warm hues, savings/flexible spending use cooler hues, and gross pay remains green.
-- Added a new "All Accounts Total" banner to Bills, Savings, and Loan views so totals across accounts are visible at a glance.
+- New theme preset options available to choose from in App Settings
+- Added undo and redo support across planning workflows, plus an audit history overlay so you can review and restore prior changes.
+- Added plan-wide search actions that can jump directly to settings, sections, and modals, including common add/edit/delete/pause tasks.
+- Added automated reallocation support when remaining spending is below target, with safe-source rules and a clear summary of what changed.
+- Added app-wide Lucide icon support with account icon selection, replacing legacy emoji-based iconography.
+
 
 ### Improvements
 
-- Improved account editing usability by prioritizing existing accounts, keeping add controls at the bottom, and improving smaller-window behavior.
-- Refined allocation row readability with cleaner category logic, earlier count indicators, and one-line ellipsis handling for very long category names.
-- Standardized and polished several shared UI surfaces (cards, headers, and modal interactions) for more consistent behavior across views.
-- Updated Key Metrics chart categorization to combine deductions and bills into a clearer "Bills & Deductions" grouping.
-- Improved Key Metrics stacked chart rendering so the bar reliably fills the full container width.
-- Improved Key Metrics card layout responsiveness so cards flow more naturally by available screen space.
+- Improved gross-to-net clarity with explicit pre-tax and post-tax deduction visibility in key breakdown views.
+- Expanded tax modeling so tax lines can be configured using either percentage rates or fixed amounts.
+- Expanded view mode flexibility with more cadence options, paycheck-cadence defaults, and better selector guidance.
+- Overhauled Appearance and Accessibility settings with curated light/dark preset pairs, manual dark-mode overrides, and a dedicated high-contrast mode.
+- Added app-level display scaling controls (zoom/font size) in Settings and View, including keyboard shortcuts for zoom in, zoom out, and reset.
+
 
 ### Bug Fixes
 
-- Fixed remaining amount behavior so negative remaining values are shown correctly and highlighted with a clear danger state.
-- Fixed retirement contribution rounding consistency to nearest cent across affected flows.
-- Fixed Setup Wizard tax defaults to avoid USD-centric assumptions when using non-USD currencies.
-- Fixed glossary term rendering so intended capitalization is preserved.
-- Fixed header drag-region interaction regressions that could block certain modal close/button interactions.
-- Fixed Key Metrics totals mismatches by aligning Remaining-for-Spending calculations between cards and charts.
-- Fixed Key Metrics savings calculations to include Savings & Investment Contributions and properly classify retirement contributions in savings.
-- Fixed Key Metrics bills totals to ignore paused/disabled bills.
+- Fixed cross-mode rounding and persistence behavior so values remain stable after editing, saving, and reopening.
+- Fixed several search interaction issues, including navigation/scroll behavior and action responsiveness for pause/resume controls.

app_updates/Implementations.md

@@ -1,5 +1,33 @@
 # Implementation Notes
 
+## Cross-Mode Rounding and Persistence Strategy
+
+### Goal
+Keep paycheck, monthly, and yearly views interchangeable for users without introducing save/reopen drift.
+
+### Source-of-Truth Decision
+- Do not force a single yearly canonical model across the whole app.
+- Keep canonical storage domain-specific so existing calculation paths stay coherent.
+- For manually edited account allocation categories in Pay Breakdown, store normalized per-paycheck values.
+- For bills, loans, savings, and other recurring items, keep their existing native/monthly/frequency-based storage models.
+
+### Why this approach
+- Account allocation categories are validated directly against per-paycheck net pay and reallocation logic.
+- Converting them to yearly storage would add unnecessary back-and-forth math in the screen that edits them most often.
+- Other domains already have stable storage models tied to their own business logic, so changing them all at once would create broad regression risk.
+
+### Current stabilization work
+- `convertFromDisplayMode()` now normalizes stored values to a consistent precision so monthly/yearly edits do not accumulate floating-point noise.
+- Pay Breakdown allocation editing now uses a dedicated allocation editor conversion utility rather than duplicating conversion + normalization inline.
+- Regression coverage now exists at three levels:
+  - conversion utility round trips
+  - allocation editor round trips
+  - save/load persistence round trips through `FileStorageService`
+
+### Remaining follow-up
+- Continue checking whether any other editable surfaces write display-mode-converted values back into stored state.
+- Keep item 5 separate from view-mode selector expansion work so data-integrity fixes and UX/view-option changes do not get conflated.
+
 ## Feedback System via GitHub Issues (Private Repo)
 
 ### **Goal**

app_updates/PLAN_TEMPLATE.md

@@ -0,0 +1,40 @@
+# vX.Y.Z Work Plan
+
+<!--
+  TEMPLATE — Copy this file, rename it to match the release (e.g. v0.5.0-list.md),
+  and delete this comment block before committing.
+-->
+
+Status keys:
+- `[ ]` Planned
+- `[-]` In Progress
+- `[x]` Done
+
+Release notes discipline:
+- [ ] Add a user-facing RELEASE_NOTES.md bullet when each parent item reaches Done.
+- [ ] Keep release-note wording focused on outcomes, not implementation details.
+
+---
+
+## 1. [Item Title]
+Parent status: `[ ] Planned`
+
+- [ ] Sub-task description.
+    - Task clarifications if necessary
+- [ ] Sub-task description.
+    - Task clarifications if necessary
+- [ ] Add/update tests where necessary
+
+Done definition:
+- [ ] [Verifiable outcome a user or reviewer can confirm.]
+
+---
+
+## Other items as necessary
+
+---
+
+## Final vX.Y.Z Exit Checklist
+- [ ] All parent items above are marked `[x] Done` or explicitly deferred.
+- [ ] RELEASE_NOTES.md updated with completed vX.Y.Z user-facing items.
+- [ ] Lint, typecheck, tests, and build pass for merged changes.