updated

README.md

@@ -4,10 +4,21 @@
   <img src="docs/images/logo_cut.png" alt="BillTracker logo">
 </p>
 
-BillTracker is a private, self-hosted bill planning app for households and small personal setups. It tracks recurring bills, payments, monthly cash buckets, due dates, categories, debt payoff, imports, exports, and backups from one local installation.
+BillTracker is a private, self-hosted bill planning app for households and small personal setups. It tracks recurring bills, payments, monthly cash buckets, due dates, categories, debt payoff, imports, exports, backups, transactions, bank sync, and subscriptions from one local installation.
 
 It runs as a Node/Express app with a React/Vite frontend and stores data in SQLite. It is designed for people who want their bill data under their own control instead of inside a third-party budgeting service.
 
+Key features include:
+
+- SimpleFIN bank sync integration (auto-sync, manual "Sync Now", 90-day backfill)
+- Subscription catalog with recommendations from unmatched charges
+- Advisory non-bill filter system (5k+ patterns, auto-matching)
+- Transaction import, matching, and management
+- Snowball and avalanche debt payoff planning
+- Analytics, calendar, summary pages, and printable reports
+- Dark mode and PWA support (offline-ready)
+- Keyboard command palette (Ctrl+K)
+
 <p align="center">
 Demo Server: https://t1.scheller.ltd/<br>
 Username: guest &middot; Password: guest123
@@ -16,14 +27,27 @@ Username: guest &middot; Password: guest123
 ## Highlights
 
 - Private-by-design self-hosted bill tracking with local SQLite storage
-- Month-by-month tracker grouped by `1st-14th` and `15th-31st`
+- Tracker view with monthly buckets (`1st-14th` and `15th-31st`) and period-aware balance
-- Period-aware remaining balance that switches between the 1st and 15th buckets
 - Bills, categories, payments, notes, skipped months, history ranges, and inactive bill handling
+- Subscription catalog (v2 with 100+ services across categories, recommendations from unmatched charges)
+- Advisory non-bill filter system (5k+ patterns, UI for confidence levels, lazy cache, auto-matching)
 - Debt snowball page with payoff projections, avalanche comparison, APR math, and amortization schedules
-- Analytics, calendar, monthly summary, income, starting cash, and printable reports
+- Snowball page with detailed projections and comparison
-- XLSX import, import by bill, user export/import, Excel export, import history, and admin backups
+- Analytics, calendar, summary pages, and printable reports
-- Local username/password login with optional authentik/OIDC
+- XLSX import, CSV import, user export/import, Excel export, import history, and admin backups
-- Admin panel for users, backups, cleanup, auth settings, system status, roadmap, and migrations
+- Transaction import, matching, and management (Data page)
+- Local username/password login with optional Authentik/OIDC SSO
+- Admin panel for users, backups, cleanup, auth settings, status, and migrations
+- Status page with health checks, bank sync card, daily worker card, and recent errors
+- Compact tracker mode with side-by-side buckets, subscription/AP/2FA badges
+- Worker system (dailyWorker for autopay marking, notifications, session pruning, cleanup)
+- Dark mode and theme support
+- PWA support (service worker, offline-ready)
+- Keyboard command palette (Ctrl+K)
+- Monthly bill state (skip, notes per month), bill history and status tracking
+- SimpleFIN bank sync integration (auto-sync, manual "Sync Now", 90-day backfill, config via admin)
+- Two-factor authentication badges, autopay badges, subscription badges on bills
+- Customizable display preferences per bill (toggle columns, badges)
 - Public About, Privacy, and Release Notes pages
 
 ## Screenshots
@@ -32,9 +56,23 @@ Username: guest &middot; Password: guest123
 
 ![Tracker screenshot](docs/images/tracker.png)
 
-![Analytics screenshot](docs/images/Analytics.png)
+![Snowball page with debt projections](docs/images/Snowball.png)
 
-![Calendar screenshot](docs/images/Calendar.png)
+![Data page with transaction management](docs/images/Data.png)
+
+## Additional Screenshots
+
+The app includes many more screenshots in the docs:
+
+- Analytics page: spending trends, category breakdowns, heatmaps
+- Calendar page: due dates, payments, month progress
+- Summary page: income, starting amounts, monthly planning
+- Admin panel: user management, backups, status, migrations
+- Worker status: dailyWorker activity, notifications, cleanup
+- Status page: health checks, bank sync status, recent errors
+- Compact tracker mode: side-by-side buckets, subscription/AP/2FA badges
+
+See the docs directory for more details.
 
 ## Who This Is For
 
@@ -47,14 +85,17 @@ Good fit:
 - People who split monthly cash around the 1st and 15th
 - Users who want import/export and database backup control
 - Authentik/OIDC users who want optional SSO
+- Users who want SimpleFIN bank sync integration
+- People managing subscriptions, debt, and transactions in one place
 
 Not a full replacement for:
 
 - Double-entry accounting
-- Bank syncing
 - Investment tracking
 - Tax software
 
+Note: Bank sync requires a SimpleFIN account. Direct bank connections are not supported.
+
 ## Quick Start With Docker
 
 The included Compose file runs the published image on host port `3030` and stores all persistent app data under `/data` inside the container.
@@ -98,6 +139,17 @@ BACKUP_PATH=/data/backups
 
 Back up the mounted `/data` directory like you would any other sensitive financial data.
 
+### Background Workers
+
+The app runs a daily worker (`dailyWorker`) for:
+
+- Autopay marking
+- Bill due notifications (3 days, 1 day, due today, overdue)
+- Session cleanup
+- Import history pruning
+
+Worker status and recent activity are visible in the Status page admin panel.
+
 ## Node Install
 
 Install dependencies:
@@ -144,45 +196,112 @@ The Tracker is the main monthly view. It shows active bills for the selected mon
 
 You can record payments, quick-pay bills, skip a bill for the month, add monthly notes, override monthly amounts, and navigate between months. The summary cards show starting cash, total paid, active period balance, overdue amount, previous month paid, and trend.
 
+**Compact tracker mode** (available at 2xl+ screen width) adds:
+
+- Side-by-side buckets for efficient viewing
+- Subscription/AP/2FA badges for quick identification
+- "S"/"AP"/"2FA" pill badges on bills
+- Customizable column visibility per bill
+
 ### Bills
 
 Bills store the recurring source data:
 
 - name, expected amount, due day, category
-- active/inactive state
+- active/inactive state and history visibility (default, all, ranges, none)
-- billing cycle
+- billing cycle (monthly, weekly, biweekly, quarterly, annual)
-- autopay and 2FA markers
+- autopay status tracking (pending, assumed_paid, confirmed)
-- notes and account details
+- subscription detection
-- optional debt fields such as balance, APR, and minimum payment
+- cycle type and cycle day configuration
-- inactive bill history ranges
 
-### Debt Snowball
+Inactive bills support history ranges for past billing periods.
+
+### Optional Debt Fields
+
+- balance, APR, and minimum payment
+- snowball ordering and exclusion flags
+- debt payoff tracking
+
+### Monthly Override State
+
+- actual_amount per month
+- is_skipped flag
+- notes per month
+
+### SimpleFIN Bank Sync
+
+SimpleFIN integration provides automated bank syncing:
+
+- Auto-sync with configurable schedule
+- Manual "Sync Now" button for immediate synchronization
+- 90-day backfill support
+- Configuration via Admin panel
+- Recommendations subsystem for unmatched bank charges
+
+### Subscription Catalog
+
+Track and manage recurring subscriptions:
+
+- v2 catalog with 100+ services across categories
+- Recommendations from unmatched bank charges
+- Category-based organization
+- Automatic subscription detection
+
+### Advisory Filter System
+
+Non-bill filtering with machine learning patterns:
+
+- 5000+ patterns for classification
+- UI for high/medium confidence filtering
+- Lazy caching for performance
+- Auto-matching from bank sync
+
+### Snowball
 
 The Snowball page focuses on debt payoff planning:
 
 - snowball and avalanche ordering
-- minimum-only baseline
+- minimum-only baseline vs. full extra payment
-- live payoff projections
+- live payoff projections with APR snapshots
-- APR snapshots
 - amortization schedules
 - drag ordering and debt exclusion
 
 ### Calendar, Summary, And Analytics
 
-- Calendar shows due dates, payments, and month progress.
+- Calendar shows due dates, payments, and month progress
-- Summary handles income, starting amounts, and monthly planning.
+- Summary handles income, starting amounts, and monthly planning
-- Analytics provides spending trends, category views, bill history, filters, heatmaps, and print output.
+- Analytics provides spending trends, category views, bill history, filters, heatmaps, and print output
 
 ### Data Tools
 
 BillTracker includes:
 
-- XLSX spreadsheet import with preview
+- XLSX and CSV spreadsheet import with preview
-- import by bill
+- Import by bill (manual entry)
-- user SQLite import/export
+- User SQLite import/export
 - Excel workbook export
-- import history
+- Transaction import, matching, and management
-- admin database backup, restore, download, cleanup, and retention tools
+- Import history with detailed stats
+- Admin database backup, restore, download, cleanup, and retention tools
+
+### Data Page
+
+The Data page manages transactions:
+
+- Import from CSV/XLSX with field mapping
+- Match transactions to bills
+- Ignore unmatched transactions
+- Transaction status tracking (matched, unmatched, ignored)
+
+### Status Page
+
+System status at a glance:
+
+- Health checks (database, SMTP, workers)
+- SimpleFIN bank sync status
+- Daily worker activity
+- Degraded state indicators
+- Recent errors list
 
 ## Privacy Model
 
@@ -200,7 +319,7 @@ Admins can manage users, reset passwords, configure authentication, and manage b
 
 BillTracker supports local username/password login by default. Admins can create users, reset passwords, promote/demote users, and activate/deactivate accounts.
 
-Optional authentik/OIDC login can be enabled from Admin. OIDC uses authorization code flow with PKCE, state and nonce validation, and `openid-client` token validation.
+Optional Authentik/OIDC login can be enabled from Admin. OIDC uses authorization code flow with PKCE, state and nonce validation, and `openid-client` token validation.
 
 Important behavior:
 
@@ -208,6 +327,7 @@ Important behavior:
 - OIDC admin access requires a configured admin group.
 - Local login cannot be disabled unless OIDC is configured, enabled, and mapped to an admin group.
 - The default seeded admin is restricted to admin routes and cannot access personal tracker data.
+- OIDC provider name, issuer URL, client ID/secret, redirect URI, scopes, and admin group are configurable via Admin settings with environment variable fallbacks.
 
 See [Authentik-Integration.md](docs/Authentik-Integration.md) for setup details.
 
@@ -239,6 +359,17 @@ CSRF_HTTP_ONLY=false
 CSRF_SAME_SITE=strict
 CSRF_SECURE=true
 CSRF_COOKIE_NAME=bt_csrf_token
+DATA_IMPORT_ENABLED=true
+```
+
+Worker settings:
+
+```bash
+WORKER_INTERVAL_MS=86400000
+WORKER_AUTOPAY_ENABLED=true
+WORKER_NOTIFICATIONS_ENABLED=true
+WORKER_SESSION_CLEANUP_ENABLED=true
+WORKER_IMPORT_CLEANUP_ENABLED=true
 ```
 
 OIDC fallback environment variables are used when matching Admin database settings are blank:
@@ -329,15 +460,41 @@ RUN_DB_MIGRATIONS=false
 ## Project Structure
 
 ```text
-client/      React app, pages, layout, UI components
+bill-tracker/
-db/          SQLite connection, schema, startup migrations
+├── client/              # React app, pages, layout, UI components
-middleware/  auth checks, CSRF, rate limits, security headers
+│   ├── components/      # Reusable React components
-routes/      Express API routes
+│   │   ├── layout/      # Layout components (Sidebar, etc.)
-services/    auth, OIDC, backups, imports, cleanup, status, audit logic
+│   │   └── ui/          # UI components (buttons, inputs, etc.)
-workers/     background tasks
+│   ├── pages/           # Page components (one per route)
-setup/       first-run admin setup
+│   │   ├── TrackerPage.jsx
-scripts/     migrations, seed data, smoke/import tests
+│   │   ├── BillsPage.jsx
-docs/        technical references and integration guides
+│   │   ├── CategoriesPage.jsx
+│   │   ├── CalendarPage.jsx
+│   │   ├── SummaryPage.jsx
+│   │   ├── AnalyticsPage.jsx
+│   │   ├── ProfilePage.jsx
+│   │   ├── SettingsPage.jsx
+│   │   ├── DataPage.jsx
+│   │   ├── AdminPage.jsx
+│   │   ├── LoginPage.jsx
+│   │   └── AboutPage.jsx
+│   ├── hooks/           # Custom React hooks (useAuth, etc.)
+│   ├── api.js           # API client functions
+│   ├── App.jsx          # React Router configuration
+│   ├── main.jsx         # React entry point
+│   └── index.html       # HTML template
+├── server.js            # Express backend entry
+├── routes/              # API route handlers
+- services/            # Business logic layer: auth, OIDC, backups, imports, cleanup, status, audit, workers, transactions, matches, data sources, snowball, analytics, notification, export, and transaction import logic
+├── middleware/          # Express middleware
+├── db/                  # Database schemas/migrations
+├── workers/             # Background job workers
+├── scripts/             # Utility scripts
+├── docs/                # Technical references and integration guides
+├── dist/                # Build output (generated)
+├── public/              # Static assets
+├── Dockerfile           # Container config
+└── docker-compose.yml
 ```
 
 ## Documentation
@@ -345,13 +502,14 @@ docs/        technical references and integration guides
 - [HISTORY.md](HISTORY.md): release history
 - [CSRF-SPA-Setup.md](docs/CSRF-SPA-Setup.md): CSRF behavior for the SPA
 - [Authentik-Integration.md](docs/Authentik-Integration.md): authentik/OIDC setup
+- [SimpleFIN-Integration.md](docs/SimpleFIN-Integration.md): SimpleFIN bank sync setup
 - [Engineering_Reference_Manual.md](docs/Engineering_Reference_Manual.md): deeper implementation reference
 
 ## Known Limitations
 
-- Admin backups and user exports are not encrypted by the app.
+- Admin backups and user exports are not encrypted by the app. Protect downloaded files and mounted volumes yourself.
-- Bank sync is not implemented.
+- Bank sync via SimpleFIN is implemented, but direct bank connections are not supported (requires SimpleFIN account).
-- OIDC single logout is not implemented.
+- OIDC single logout is not implemented; users must log out from each device separately.
 - Rate limiting is in-memory, so counters reset on restart and are not shared across multiple app instances.
 - Multiple OIDC providers are not currently supported.
 - The XLSX parser dependency has known upstream security advisories; import routes are authenticated, file-size limited, and parse spreadsheet cells as data.