fix: health check now probes HTTP directly with 3-min timeout

The previous approach relied on Docker's container health status, but
Docker's healthcheck (start_period:30s + 3x15s retries = ~75s) marks
the container "unhealthy" before NestJS finishes cold-starting after a
fresh image build (New Relic + TypeORM + Redis + BullMQ init can take
2-3 minutes).

Changes:
- Primary check is now direct wget to localhost:3000/api from the host
- Docker health status used only for informational logging
- Total timeout increased from 130s to 190s (~3 min) for cold starts
- Early exit if container has stopped/exited (no point waiting)
- More backend log lines (30 vs 20) shown on failure for diagnostics

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -13,6 +13,30 @@ AI_MODEL=qwen/qwen3.5-397b-a17b
 # Set to 'true' to enable detailed AI prompt/response logging
 AI_DEBUG=false
 
+# Stripe Billing
+STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
+STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
+
+# Stripe Price IDs (Monthly)
+STRIPE_STARTER_MONTHLY_PRICE_ID=price_starter_monthly
+STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID=price_professional_monthly
+STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_enterprise_monthly
+
+# Stripe Price IDs (Annual — 25% discount)
+STRIPE_STARTER_ANNUAL_PRICE_ID=price_starter_annual
+STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID=price_professional_annual
+STRIPE_ENTERPRISE_ANNUAL_PRICE_ID=price_enterprise_annual
+
+# Trial configuration
+REQUIRE_PAYMENT_METHOD_FOR_TRIAL=false
+
+# Email (Resend)
+RESEND_API_KEY=re_your_resend_api_key
+
+# Application
+APP_URL=http://localhost
+INVITE_TOKEN_SECRET=dev-invite-secret
+
 # New Relic APM — set ENABLED=true and provide your license key to activate
 NEW_RELIC_ENABLED=false
 NEW_RELIC_LICENSE_KEY=your_new_relic_license_key_here

.gitea/workflows/deploy.yml

@@ -0,0 +1,65 @@
+# ---------------------------------------------------------------------------
+# Production Deployment Workflow for HOA LedgerIQ
+#
+# Trigger: Manual only (workflow_dispatch) — production deploys are intentional.
+# Runner:  Self-hosted on the production server at /opt/hoa-ledgeriq.
+#
+# This workflow does NOT use actions/checkout. The runner operates directly
+# on the production directory. The deploy script itself handles git pull.
+# ---------------------------------------------------------------------------
+
+name: Deploy to Production
+
+on:
+  workflow_dispatch:
+    inputs:
+      seed_existing:
+        description: "Mark existing migrations as applied without running them (first deployment only)"
+        required: false
+        default: "false"
+        type: boolean
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: /opt/hoa-ledgeriq
+
+    steps:
+      - name: Pre-deploy info
+        run: |
+          echo "## Pre-Deploy Info" >> $GITHUB_STEP_SUMMARY
+          echo "- **Server:** $(hostname)" >> $GITHUB_STEP_SUMMARY
+          echo "- **Directory:** $(pwd)" >> $GITHUB_STEP_SUMMARY
+          echo "- **Current commit:** $(git rev-parse --short HEAD)" >> $GITHUB_STEP_SUMMARY
+          echo "- **Branch:** $(git branch --show-current || echo 'detached')" >> $GITHUB_STEP_SUMMARY
+          echo "- **Triggered by:** ${{ github.actor }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Seed existing:** ${{ inputs.seed_existing }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Started at:** $(date -Iseconds)" >> $GITHUB_STEP_SUMMARY
+
+      - name: Run deployment
+        run: |
+          DEPLOY_FLAGS=""
+          if [ "${{ inputs.seed_existing }}" = "true" ]; then
+            DEPLOY_FLAGS="--seed-existing"
+          fi
+          bash scripts/deploy-prod.sh $DEPLOY_FLAGS
+        env:
+          TERM: xterm
+
+      - name: Deployment result
+        if: always()
+        run: |
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "## Deployment Result" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ job.status }}" = "success" ]; then
+            echo "- **Status:** Successful" >> $GITHUB_STEP_SUMMARY
+            echo "- **Commit:** $(git rev-parse --short HEAD)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- **Status:** FAILED (auto-rollback triggered)" >> $GITHUB_STEP_SUMMARY
+            echo "- **Commit (after rollback):** $(git rev-parse --short HEAD)" >> $GITHUB_STEP_SUMMARY
+            echo "- Check the deploy log on the server for details" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "- **Completed at:** $(date -Iseconds)" >> $GITHUB_STEP_SUMMARY

CLAUDE.md

@@ -0,0 +1,229 @@
+# CLAUDE.md – HOA Financial Platform (HOALedgerIQ)
+
+## Project Overview
+
+Multi-tenant SaaS platform for HOA (Homeowners Association) financial management. Handles chart of accounts, journal entries, budgets, invoices, payments, reserve planning, and board scenario planning.
+
+---
+
+## Stack & Framework
+
+| Layer     | Technology                                          |
+| --------- | --------------------------------------------------- |
+| Backend   | **NestJS 10** (TypeScript), runs on port 3000       |
+| Frontend  | **React 18** + Vite 5 + Mantine UI + Zustand       |
+| Database  | **PostgreSQL** via **TypeORM 0.3**                  |
+| Cache     | **Redis** (BullMQ for queues)                       |
+| Auth      | **Passport.js** – JWT access + httpOnly refresh     |
+| Payments  | **Stripe** (checkout, subscriptions, webhooks)      |
+| Email     | **Resend**                                          |
+| AI        | NVIDIA API (Qwen model) for investment advisor      |
+| Monitoring| **New Relic** APM (app name: `HOALedgerIQ_App`)     |
+| Infra     | Docker Compose (dev + prod), Nginx reverse proxy    |
+
+---
+
+## Auth Pattern
+
+- **Access token**: JWT, 1-hour TTL, payload `{ sub, email, orgId, role, isSuperadmin }`
+- **Refresh token**: 64-byte random, SHA256-hashed in DB, 30-day TTL, sent as httpOnly cookie `ledgeriq_rt`
+- **MFA**: TOTP via `otplib`, challenge token (5-min TTL), recovery codes
+- **Passkeys**: WebAuthn via `@simplewebauthn/server`
+- **SSO**: Google OAuth 2.0, Azure AD
+- **Password hashing**: bcryptjs, cost 12
+- **Rate limiting**: 100 req/min global (Throttler), custom per endpoint
+
+### Guards & Middleware
+
+- `TenantMiddleware` – extracts `orgId` from JWT, sets tenant schema (60s cache)
+- `JwtAuthGuard` – Passport JWT guard on all protected routes
+- `WriteAccessGuard` – blocks write ops for `viewer` role and `past_due` orgs
+- `@AllowViewer()` decorator – exempts read endpoints from WriteAccessGuard
+
+### Roles
+
+`president`, `treasurer`, `secretary`, `member_at_large`, `manager`, `homeowner`, `admin`, `viewer`
+
+---
+
+## Multi-Tenant Architecture
+
+- **Shared schema** (`shared`): users, organizations, user_organizations, refresh_tokens, invite_tokens, login_history, cd_rates
+- **Tenant schemas** (dynamic, per org): accounts, journal_entries, budgets, invoices, payments, units, vendors, etc.
+- Schema name stored in `shared.organizations.schema_name`
+
+---
+
+## Route Map (180+ endpoints)
+
+### Auth (`/api/auth`)
+| Method | Path                    | Purpose                          |
+| ------ | ----------------------- | -------------------------------- |
+| POST   | /login                  | Email/password login             |
+| POST   | /refresh                | Refresh access token (cookie)    |
+| POST   | /logout                 | Revoke refresh token             |
+| POST   | /logout-everywhere      | Revoke all sessions              |
+| GET    | /profile                | Current user profile             |
+| POST   | /register               | Register (disabled by default)   |
+| POST   | /activate               | Activate invited user            |
+| POST   | /forgot-password        | Request password reset           |
+| POST   | /reset-password         | Reset with token                 |
+| PATCH  | /change-password        | Change password (authed)         |
+| POST   | /switch-org             | Switch active organization       |
+
+### Auth MFA (`/api/auth/mfa`)
+| POST | /setup | POST /enable | POST /verify | POST /disable | GET /status |
+
+### Auth Passkeys (`/api/auth/passkeys`)
+| POST /register-options | POST /register | POST /login-options | POST /login | GET / | DELETE /:id |
+
+### Admin (`/api/admin`) – superadmin only
+| GET /metrics | GET /users | GET /organizations | PUT /organizations/:id/subscription | POST /impersonate/:userId | POST /tenants |
+
+### Organizations (`/api/organizations`)
+| POST / | GET / | PATCH /settings | GET /members | POST /members | PUT /members/:id/role | DELETE /members/:id |
+
+### Accounts (`/api/accounts`)
+| GET / | GET /trial-balance | POST / | PUT /:id | PUT /:id/set-primary | POST /bulk-opening-balances | POST /:id/opening-balance | POST /:id/adjust-balance |
+
+### Journal Entries (`/api/journal-entries`)
+| GET / | GET /:id | POST / | POST /:id/post | POST /:id/void |
+
+### Budgets (`/api/budgets`)
+| GET /:year | PUT /:year | GET /:year/vs-actual | POST /:year/import | GET /:year/template |
+
+### Invoices (`/api/invoices`)
+| GET / | GET /:id | POST /generate-preview | POST /generate-bulk | POST /apply-late-fees |
+
+### Payments (`/api/payments`)
+| GET / | GET /:id | POST / | PUT /:id | DELETE /:id |
+
+### Units (`/api/units`)
+| GET / | GET /:id | POST / | PUT /:id | DELETE /:id | GET /export | POST /import |
+
+### Vendors (`/api/vendors`)
+| GET / | GET /:id | POST / | PUT /:id | GET /export | POST /import | GET /1099-data |
+
+### Reports (`/api/reports`)
+| GET /dashboard | GET /balance-sheet | GET /income-statement | GET /cash-flow | GET /cash-flow-sankey | GET /aging | GET /year-end | GET /cash-flow-forecast | GET /quarterly |
+
+### Board Planning (`/api/board-planning`)
+Scenarios CRUD, scenario investments, scenario assessments, projections, budget plans – 28 endpoints total.
+
+### Other Modules
+- `/api/fiscal-periods` – list, close, lock
+- `/api/reserve-components` – CRUD
+- `/api/capital-projects` – CRUD
+- `/api/projects` – CRUD + planning + import/export
+- `/api/assessment-groups` – CRUD + summary + default
+- `/api/monthly-actuals` – GET/POST /:year/:month
+- `/api/health-scores` – latest + calculate
+- `/api/investment-planning` – snapshot, market-rates, recommendations
+- `/api/investment-accounts` – CRUD
+- `/api/attachments` – upload, list, download, delete (10MB limit)
+- `/api/onboarding` – progress get/patch
+- `/api/billing` – trial, checkout, webhook, subscription, portal
+
+---
+
+## Database
+
+- **Connection pool**: min 5, max 30, 30s idle, 5s connect timeout
+- **Migrations**: SQL files in `db/migrations/` (manual execution, no ORM runner)
+- **Init script**: `db/init/00-init.sql` (shared schema DDL)
+
+---
+
+## Key File Paths
+
+| Purpose                | Path                                              |
+| ---------------------- | ------------------------------------------------- |
+| NestJS bootstrap       | `backend/src/main.ts`                             |
+| Root module            | `backend/src/app.module.ts`                       |
+| Auth controller        | `backend/src/modules/auth/auth.controller.ts`     |
+| Auth service           | `backend/src/modules/auth/auth.service.ts`        |
+| Refresh token svc      | `backend/src/modules/auth/refresh-token.service.ts` |
+| JWT strategy           | `backend/src/modules/auth/strategies/jwt.strategy.ts` |
+| Tenant middleware      | `backend/src/database/tenant.middleware.ts`        |
+| Write-access guard     | `backend/src/common/guards/write-access.guard.ts` |
+| DB schema init         | `db/init/00-init.sql`                             |
+| Env example            | `.env.example`                                    |
+| Docker compose (dev)   | `docker-compose.yml`                              |
+| Frontend entry         | `frontend/src/main.tsx`                           |
+| Frontend pages         | `frontend/src/pages/`                             |
+
+---
+
+## Environment Variables (critical)
+
+```
+DATABASE_URL          – PostgreSQL connection string
+REDIS_URL             – Redis connection
+JWT_SECRET            – JWT signing key
+INVITE_TOKEN_SECRET   – Invite token signing
+STRIPE_SECRET_KEY     – Stripe API key
+STRIPE_WEBHOOK_SECRET – Stripe webhook verification
+RESEND_API_KEY        – Email service
+NEW_RELIC_APP_NAME    – "HOALedgerIQ_App"
+NEW_RELIC_LICENSE_KEY  – New Relic license
+APP_URL               – Base URL for email links
+```
+
+---
+
+## New Relic
+
+- **App name**: `HOALedgerIQ_App` (env: `NEW_RELIC_APP_NAME`)
+- Enabled via `NEW_RELIC_ENABLED=true`
+- NRQL query library: `load-tests/analysis/nrql-queries.sql`
+
+---
+
+## Load Testing
+
+### Run k6 scenarios
+
+```bash
+# Auth + Dashboard flow (staging)
+k6 run --env TARGET_ENV=staging load-tests/scenarios/auth-dashboard-flow.js
+
+# CRUD flow (staging)
+k6 run --env TARGET_ENV=staging load-tests/scenarios/crud-flow.js
+
+# Local dev
+k6 run --env TARGET_ENV=local load-tests/scenarios/auth-dashboard-flow.js
+```
+
+### Conventions
+
+- Scenarios live in `load-tests/scenarios/`
+- Config in `load-tests/config/environments.json` (staging/production/local thresholds)
+- Test users parameterized from `load-tests/config/user-pool.csv`
+- Baseline results stored in `load-tests/analysis/baseline.json`
+- NRQL queries for New Relic in `load-tests/analysis/nrql-queries.sql`
+- All k6 scripts use `SharedArray` for user pool, `http.batch()` for parallel requests
+- Custom metrics: `*_duration` trends + `*_error_rate` rates per journey
+- Thresholds: p95 latency + error rate per environment
+
+### User Pool CSV Format
+
+```
+email,password,orgId,role
+```
+
+Roles match the app: `treasurer`, `admin`, `president`, `manager`, `member_at_large`, `viewer`, `homeowner`
+
+---
+
+## Fix Conventions
+
+- Backend tests: `npm run test` (Jest, `*.spec.ts` co-located with source)
+- E2E tests: `npm run test:e2e`
+- Backend build: `npm run build` (NestJS CLI)
+- Frontend dev: `npm run dev` (Vite, port 5173)
+- Frontend build: `npm run build`
+- Always run `npm run build` in `backend/` after changes to verify compilation
+- TypeORM entities use decorators (`@Entity`, `@Column`, etc.)
+- Multi-tenant: any new module touching tenant data must use `TenantService` to get the correct schema connection
+- New endpoints need `@UseGuards(JwtAuthGuard)` and should respect `WriteAccessGuard`
+- Use `@AllowViewer()` on read-only endpoints

ONBOARDING-AND-AUTH.md

@@ -1,8 +1,8 @@
 # HOA LedgerIQ -- Payment, Onboarding & Authentication Guide
 
-> **Version:** 2026.03.17
-> **Last updated:** March 17, 2026
-> **Migration:** `db/migrations/015-saas-onboarding-auth.sql`
+> **Version:** 2026.03.18
+> **Last updated:** March 18, 2026
+> **Migrations:** `db/migrations/015-saas-onboarding-auth.sql`, `db/migrations/017-billing-enhancements.sql`
 
 ---
 
@@ -10,17 +10,22 @@
 
 1. [High-Level Flow](#1-high-level-flow)
 2. [Stripe Billing & Checkout](#2-stripe-billing--checkout)
-3. [Provisioning Pipeline](#3-provisioning-pipeline)
-4. [Account Activation (Magic Link)](#4-account-activation-magic-link)
-5. [Guided Onboarding Checklist](#5-guided-onboarding-checklist)
-6. [Authentication & Sessions](#6-authentication--sessions)
-7. [Multi-Factor Authentication (TOTP)](#7-multi-factor-authentication-totp)
-8. [Single Sign-On (SSO)](#8-single-sign-on-sso)
-9. [Passkeys (WebAuthn)](#9-passkeys-webauthn)
-10. [Environment Variables Reference](#10-environment-variables-reference)
-11. [Manual Intervention & Ops Tasks](#11-manual-intervention--ops-tasks)
-12. [What's Stubbed vs. Production-Ready](#12-whats-stubbed-vs-production-ready)
-13. [API Endpoint Reference](#13-api-endpoint-reference)
+3. [14-Day Free Trial](#3-14-day-free-trial)
+4. [Monthly / Annual Billing](#4-monthly--annual-billing)
+5. [Provisioning Pipeline](#5-provisioning-pipeline)
+6. [Account Activation (Magic Link)](#6-account-activation-magic-link)
+7. [Guided Onboarding Checklist](#7-guided-onboarding-checklist)
+8. [Subscription Management & Upgrade/Downgrade](#8-subscription-management--upgradedowngrade)
+9. [ACH / Invoice Billing](#9-ach--invoice-billing)
+10. [Access Control & Grace Periods](#10-access-control--grace-periods)
+11. [Authentication & Sessions](#11-authentication--sessions)
+12. [Multi-Factor Authentication (TOTP)](#12-multi-factor-authentication-totp)
+13. [Single Sign-On (SSO)](#13-single-sign-on-sso)
+14. [Passkeys (WebAuthn)](#14-passkeys-webauthn)
+15. [Environment Variables Reference](#15-environment-variables-reference)
+16. [Manual Intervention & Ops Tasks](#16-manual-intervention--ops-tasks)
+17. [What's Stubbed vs. Production-Ready](#17-whats-stubbed-vs-production-ready)
+18. [API Endpoint Reference](#18-api-endpoint-reference)
 
 ---
 
@@ -30,28 +35,26 @@
 Visitor hits /pricing
         |
         v
-Selects a plan (Starter $29 / Professional $79 / Enterprise $199)
+Selects plan (Starter / Professional / Enterprise)
+Chooses billing frequency (Monthly / Annual — 25% discount)
+Enters email + business name
         |
         v
-POST /api/billing/create-checkout-session
+POST /api/billing/start-trial (no card required)
         |
         v
-Redirect to Stripe Checkout (hosted by Stripe)
+Backend creates Stripe customer + subscription with trial_period_days=14
+Backend provisions: org -> schema -> user -> invite token -> email
         |
         v
-Stripe fires `checkout.session.completed` webhook
+Frontend navigates to /onboarding/pending?session_id=xxx
+  (polls GET /api/billing/status every 3s)
         |
         v
-Backend provisions: org -> schema -> user -> invite token -> "email"
-        |
-        v
-Frontend polls GET /api/billing/status?session_id=xxx
-        |  (OnboardingPendingPage polls every 3s)
-        v
 Status returns "active" -> user is redirected to /login
         |
         v
-User clicks activation link from "email" (logged to console + DB)
+User clicks activation link from email
         |
         v
 GET /activate?token=xxx -> validates token
@@ -61,184 +64,295 @@ POST /activate -> sets password + name, issues session
 Redirect to /onboarding (4-step guided wizard)
         |
         v
-Dashboard
+Dashboard (14-day trial active)
+        |
+        v
+Day 11: Stripe fires customer.subscription.trial_will_end webhook
+Backend sends trial-ending reminder email
+        |
+        v
+User adds payment method via Stripe Portal (Settings > Manage Billing)
+        |
+        v
+Trial ends -> Stripe charges card -> subscription becomes 'active'
+  OR: No card -> subscription cancelled -> org archived
 ```
 
 ---
 
 ## 2. Stripe Billing & Checkout
 
-### Plans
+### Plans & Pricing
 
-| Plan ID        | Name         | Price   | Unit Limit |
-|---------------|--------------|---------|------------|
-| `starter`      | Starter      | $29/mo  | 50 units   |
-| `professional` | Professional | $79/mo  | 200 units  |
-| `enterprise`   | Enterprise   | $199/mo | Unlimited  |
+| Plan | Monthly | Annual (25% off) | Unit Limit |
+|------|---------|-------------------|------------|
+| Starter | $29/mo | $261/yr ($21.75/mo) | 50 units |
+| Professional | $79/mo | $711/yr ($59.25/mo) | 200 units |
+| Enterprise | Custom | Custom | Unlimited |
 
-### Checkout Flow
+### Stripe Products & Prices
 
-1. **Frontend** (`PricingPage.tsx`): User enters email + business name, selects a plan.
-2. **API call**: `POST /api/billing/create-checkout-session`
-   - Body: `{ planId, email?, businessName? }`
-   - Returns: `{ url }` (Stripe hosted checkout URL)
-   - No auth required.
-3. **Redirect**: Frontend does `window.location.href = url` to send user to Stripe.
-4. **On success**: Stripe redirects to `/onboarding/pending?session_id={CHECKOUT_SESSION_ID}`.
-5. **On cancel**: Stripe redirects back to `/pricing`.
+Each plan has **two Stripe Prices** (monthly and annual):
+
+| Env Variable | Description |
+|-------------|-------------|
+| `STRIPE_STARTER_MONTHLY_PRICE_ID` | Starter monthly recurring price |
+| `STRIPE_STARTER_ANNUAL_PRICE_ID` | Starter annual recurring price |
+| `STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID` | Professional monthly recurring price |
+| `STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID` | Professional annual recurring price |
+| `STRIPE_ENTERPRISE_MONTHLY_PRICE_ID` | Enterprise monthly recurring price |
+| `STRIPE_ENTERPRISE_ANNUAL_PRICE_ID` | Enterprise annual recurring price |
+
+Backward compatibility: `STRIPE_STARTER_PRICE_ID` (old single var) maps to monthly if the new `_MONTHLY_` var is not set.
+
+### Two Billing Paths
+
+| Path | Audience | Payment | Trial |
+|------|----------|---------|-------|
+| **Path A: Self-serve (Card)** | Starter & Professional | Automatic card charge | 14-day no-card trial |
+| **Path B: Invoice / ACH** | Enterprise (admin-set) | Invoice with Net-30 terms | Admin configures |
 
 ### Webhook Events Handled
 
-The webhook endpoint is `POST /api/webhooks/stripe`.
-
 | Event | Action |
 |-------|--------|
-| `checkout.session.completed` | Triggers full provisioning pipeline |
-| `invoice.payment_succeeded` | Sets org status to `active` (handles reactivation after failed payment) |
-| `invoice.payment_failed` | Sends payment-failed "email" (stubbed) |
+| `checkout.session.completed` | Triggers full provisioning pipeline (card-required flow) |
+| `invoice.payment_succeeded` | Sets org status to `active` (reactivation after trial/past_due) |
+| `invoice.payment_failed` | Sets org to `past_due`, sends payment-failed email |
 | `customer.subscription.deleted` | Sets org status to `archived` |
+| `customer.subscription.trial_will_end` | Sends trial-ending reminder email (3 days before) |
+| `customer.subscription.updated` | Syncs plan, interval, status, and collection_method to DB |
 
 All webhook events are deduplicated via the `shared.stripe_events` table (idempotency by Stripe event ID).
 
-### Stripe Customer Portal
+---
 
-`POST /api/billing/portal` (auth required) -- creates a Stripe Customer Portal session for managing subscription/payment methods. **Note: currently throws "not implemented" -- needs org-context customer ID lookup.**
+## 3. 14-Day Free Trial
+
+### How It Works
+
+1. User visits `/pricing`, selects a plan and billing frequency
+2. User enters email + business name (required)
+3. Clicks "Start Free Trial"
+4. Backend creates Stripe customer (no payment method)
+5. Backend creates subscription with `trial_period_days: 14`
+6. Backend provisions org with `status = 'trial'` immediately
+7. User receives activation email, sets password, starts using the app
+
+### Trial Configuration
+
+| Setting | Description |
+|---------|-------------|
+| `REQUIRE_PAYMENT_METHOD_FOR_TRIAL` | `false` (default): no-card trial. `true`: uses Stripe Checkout (card required upfront). |
+
+### Trial Lifecycle
+
+| Day | Event |
+|-----|-------|
+| 0 | Trial starts, full access granted |
+| 11 | `customer.subscription.trial_will_end` webhook fires |
+| 11 | Trial-ending email sent ("Your trial ends in 3 days") |
+| 14 | Trial ends |
+| 14 | If card on file: Stripe charges, subscription becomes `active` |
+| 14 | If no card: subscription cancelled, org set to `archived` |
+
+### Trial Behavior by Plan Frequency
+
+- **Monthly trial**: Trial ends, charge monthly price
+- **Annual trial**: Trial ends, charge full annual amount
+
+### Trial End Behavior
+
+Configured in Stripe subscription: `trial_settings.end_behavior.missing_payment_method: 'cancel'`
+
+When trial ends without a payment method, the subscription is cancelled and the org is archived. Users can resubscribe at any time.
 
 ---
 
-## 3. Provisioning Pipeline
+## 4. Monthly / Annual Billing
 
-When `checkout.session.completed` fires, the backend runs **inline provisioning** (no background queue):
+### Pricing Page Toggle
+
+The pricing page (`PricingPage.tsx`) features a segmented control toggle:
+- **Monthly**: Shows monthly prices ($29/mo, $79/mo)
+- **Annual (Save 25%)**: Shows effective monthly rate + annual total ($21.75/mo billed annually at $261/yr)
+
+The selected billing frequency is passed to the backend when starting a trial or creating a checkout session.
+
+### Annual Discount
+
+Annual pricing = Monthly price x 12 x 0.75 (25% discount):
+- Starter: $29 x 12 x 0.75 = **$261/yr**
+- Professional: $79 x 12 x 0.75 = **$711/yr**
+
+---
+
+## 5. Provisioning Pipeline
+
+When a trial starts or `checkout.session.completed` fires, the backend runs **inline provisioning**:
 
 1. **Create organization** in `shared.organizations` with:
-   - `name` = business name from checkout metadata
+   - `name` = business name from signup
    - `schema_name` = `tenant_{random_12_chars}`
-   - `status` = `active`
+   - `status` = `trial` (for trial) or `active` (for card checkout)
    - `plan_level` = selected plan
+   - `billing_interval` = `month` or `year`
    - `stripe_customer_id` + `stripe_subscription_id`
+   - `trial_ends_at` (if trial)
    - Uses `ON CONFLICT (stripe_customer_id)` for idempotency
 
-2. **Create tenant schema** via `TenantSchemaService.createTenantSchema()`:
-   - Runs the full tenant DDL (accounts, journal entries, etc.)
-   - Skips if schema already exists
-
-3. **Create or find user** in `shared.users` by email:
-   - New users are created with `is_email_verified = false` and no password
-   - Existing users are reused (linked to new org)
-
-4. **Create membership** in `shared.user_organizations`:
-   - Role: `president`
-   - Idempotent via `ON CONFLICT DO NOTHING`
-
-5. **Generate invite token** (JWT signed with `INVITE_TOKEN_SECRET`, 72-hour expiry):
-   - SHA-256 hash stored in `shared.invite_tokens`
-   - Raw token used in activation URL
-
-6. **Send activation "email"** (stubbed -- see section 12):
-   - Logged to console and `shared.email_log` table
-   - Contains activation URL: `{APP_URL}/activate?token={jwt}`
-
-7. **Initialize onboarding** progress row in `shared.onboarding_progress`
+2. **Create tenant schema** via `TenantSchemaService.createTenantSchema()`
+3. **Create or find user** in `shared.users` by email
+4. **Create membership** in `shared.user_organizations` (role: `president`)
+5. **Generate invite token** (JWT, 72-hour expiry)
+6. **Send activation email** with link to set password
+7. **Initialize onboarding** progress row
 
 ### Provisioning Status Polling
 
 `GET /api/billing/status?session_id=xxx` (no auth required)
 
-Returns: `{ status }` where status is one of:
+Accepts both Stripe checkout session IDs and subscription IDs. Returns: `{ status }` where status is:
 - `not_configured` -- Stripe not set up
 - `pending` -- no customer ID yet
-- `provisioning` -- org exists but not active yet
-- `active` -- ready to go
-
-The `OnboardingPendingPage` polls this every 3 seconds and redirects to `/login` once active.
+- `provisioning` -- org exists but not ready
+- `active` -- ready (includes `trial` status)
 
 ---
 
-## 4. Account Activation (Magic Link)
+## 6. Account Activation (Magic Link)
 
 ### Validate Token
 
-`GET /api/auth/activate?token=xxx` (no auth required)
-
-- Verifies JWT signature (using `INVITE_TOKEN_SECRET`)
-- Checks `shared.invite_tokens` for existence, expiration, and prior use
-- Returns: `{ valid, email, orgName, orgId, userId }`
+`GET /api/auth/activate?token=xxx` -- returns `{ valid, email, orgName, orgId, userId }`
 
 ### Activate Account
 
-`POST /api/auth/activate` (no auth required)
-
-- Body: `{ token, password, fullName }`
-- Password must be >= 8 characters
-- Sets `password_hash`, `first_name`, `last_name`, `is_email_verified = true`
-- Marks invite token as used (`used_at = NOW()`)
-- Issues full session (access token + refresh token cookie)
-- Frontend redirects to `/onboarding`
-
-### Frontend (ActivatePage.tsx)
-
-- Validates token on mount
-- Shows password setup form with strength indicator (color-coded bar)
-- On success: stores auth in Zustand and navigates to `/onboarding`
+`POST /api/auth/activate` -- body `{ token, password, fullName }` -- sets password, issues session
 
 ---
 
-## 5. Guided Onboarding Checklist
+## 7. Guided Onboarding Checklist
 
-### Required Steps
-
-| Step Key         | UI Label       | Description |
-|-----------------|----------------|-------------|
-| `profile`        | Profile        | Set up user profile |
-| `workspace`      | Workspace      | Configure organization settings |
-| `invite_member`  | Invite Member  | Invite at least one team member |
-| `first_workflow` | First Account  | Create the first chart-of-accounts entry |
-
-### API
-
-- `GET /api/onboarding/progress` (auth required): Returns `{ completedSteps[], completedAt, requiredSteps[] }`
-- `PATCH /api/onboarding/progress` (auth required): Body `{ step }` -- marks a step complete
-
-Steps are stored as a PostgreSQL text array. When all 4 required steps are complete, `completed_at` is set. Users can skip onboarding via a "Finish Later" button (navigates to dashboard).
-
-### Frontend (OnboardingPage.tsx)
-
-- Mantine Stepper with 4 steps
-- Each step calls `PATCH /onboarding/progress` on completion
-- Celebration screen shown when all steps are done
+| Step Key | UI Label | Description |
+|----------|----------|-------------|
+| `profile` | Profile | Set up user profile |
+| `workspace` | Workspace | Configure organization settings |
+| `invite_member` | Invite Member | Invite at least one team member |
+| `first_workflow` | First Account | Create the first chart-of-accounts entry |
 
 ---
 
-## 6. Authentication & Sessions
+## 8. Subscription Management & Upgrade/Downgrade
+
+### Stripe Customer Portal
+
+Users manage their subscription through the **Stripe Customer Portal**, accessed via:
+- Settings page > Billing card > "Manage Billing" button
+- Calls `POST /api/billing/portal` which creates a portal session and returns the URL
+
+### What Users Can Do in the Portal
+
+- **Switch plans**: Change between Starter and Professional
+- **Switch billing frequency**: Monthly to Annual (and vice versa)
+- **Update payment method**: Add/change credit card
+- **Cancel subscription**: Cancels at end of current period
+- **View invoices**: See billing history
+
+### Upgrade/Downgrade Behavior
+
+| Change | Behavior |
+|--------|----------|
+| Monthly to Annual | Immediate. Prorate remaining monthly time, start annual cycle now. |
+| Annual to Monthly | Scheduled at end of current annual period. |
+| Starter to Professional | Immediate. Prorate price difference. |
+| Professional to Starter | Scheduled at end of current period. |
+
+Stripe handles proration automatically when configured with `proration_behavior: 'create_prorations'`.
+
+### Subscription Info Endpoint
+
+`GET /api/billing/subscription` (auth required) returns:
+```json
+{
+  "plan": "professional",
+  "planName": "Professional",
+  "billingInterval": "month",
+  "status": "active",
+  "collectionMethod": "charge_automatically",
+  "trialEndsAt": null,
+  "currentPeriodEnd": "2026-04-18T00:00:00.000Z",
+  "cancelAtPeriodEnd": false
+}
+```
+
+---
+
+## 9. ACH / Invoice Billing
+
+### Overview
+
+For enterprise customers who need to pay via ACH bank transfer or wire, an admin can switch the subscription's collection method from automatic card charge to invoice billing.
+
+### How It Works
+
+1. **Admin** calls `PUT /api/admin/organizations/:id/billing` with:
+   ```json
+   { "collectionMethod": "send_invoice", "daysUntilDue": 30 }
+   ```
+2. Stripe subscription is updated: `collection_method = 'send_invoice'`, `days_until_due = 30`
+3. At each billing cycle, Stripe generates an invoice and emails it to the customer
+4. Customer pays via ACH / wire / bank transfer
+5. When payment is received, Stripe marks invoice paid and org remains active
+
+### Access Rules for Invoice Customers
+
+| Stage | Access |
+|-------|--------|
+| Trial | Full |
+| Invoice issued | Full |
+| Due date passed | Read-only (past_due) |
+| 15+ days overdue | Admin may archive |
+
+### Switching Back
+
+To switch back to automatic card billing:
+```json
+{ "collectionMethod": "charge_automatically" }
+```
+
+---
+
+## 10. Access Control & Grace Periods
+
+### Organization Status Access Rules
+
+| Status | Access | Description |
+|--------|--------|-------------|
+| `trial` | **Full** | 14-day trial, all features available |
+| `active` | **Full** | Paid subscription, all features available |
+| `past_due` | **Read-only** | Payment failed or invoice overdue. Users can view data but cannot create/edit/delete. |
+| `suspended` | **Blocked** | Admin suspended. 403 on all org-scoped endpoints. |
+| `archived` | **Blocked** | Subscription cancelled. 403 on all org-scoped endpoints. Data preserved. |
+
+### Implementation
+
+- **Tenant Middleware** (`tenant.middleware.ts`): Blocks `suspended` and `archived` with 403. Sets `req.orgPastDue = true` for `past_due`.
+- **WriteAccessGuard** (`write-access.guard.ts`): Blocks POST/PUT/PATCH/DELETE for `past_due` orgs with message: "Your subscription is past due. Please update your payment method."
+
+---
+
+## 11. Authentication & Sessions
 
 ### Token Architecture
 
 | Token | Type | Lifetime | Storage |
 |-------|------|----------|---------|
-| Access token | JWT | 1 hour | Frontend Zustand store (memory/localStorage) |
-| Refresh token | Opaque (base64url, 64 bytes) | 30 days | httpOnly cookie (`ledgeriq_rt`) |
-| MFA challenge | JWT | 5 minutes | Frontend state (in-memory only) |
+| Access token | JWT | 1 hour | Frontend Zustand store |
+| Refresh token | Opaque (64 bytes) | 30 days | httpOnly cookie (`ledgeriq_rt`) |
+| MFA challenge | JWT | 5 minutes | Frontend state |
 | Invite/activation | JWT | 72 hours | URL query parameter |
 
-### Refresh Token Flow
-
-1. Access token expires (401 from any API call)
-2. Axios interceptor catches 401, calls `POST /api/auth/refresh`
-3. Refresh token is sent automatically via httpOnly cookie
-4. Server validates token hash in `shared.refresh_tokens` table
-5. New access token issued (refresh token is NOT rotated)
-6. Original failed request is replayed with new token
-7. Concurrent requests are queued during refresh (no thundering herd)
-
-### Cookie Configuration
-
-- Name: `ledgeriq_rt`
-- Path: `/api/auth`
-- httpOnly: `true`
-- Secure: `true` in production, `false` in dev
-- SameSite: `strict`
-- Max-Age: 30 days
-
 ### Session Endpoints
 
 | Method | Path | Auth | Description |
@@ -246,107 +360,38 @@ Steps are stored as a PostgreSQL text array. When all 4 required steps are compl
 | `POST` | `/api/auth/login` | No | Email + password login |
 | `POST` | `/api/auth/register` | No | Create account |
 | `POST` | `/api/auth/refresh` | Cookie | Refresh access token |
-| `POST` | `/api/auth/logout` | Cookie | Revoke current refresh token |
-| `POST` | `/api/auth/logout-everywhere` | JWT | Revoke all user sessions |
-| `POST` | `/api/auth/switch-org` | JWT | Switch org context (new tokens) |
+| `POST` | `/api/auth/logout` | Cookie | Revoke current session |
+| `POST` | `/api/auth/logout-everywhere` | JWT | Revoke all sessions |
+| `POST` | `/api/auth/switch-org` | JWT | Switch organization |
 
 ---
 
-## 7. Multi-Factor Authentication (TOTP)
-
-### Setup Flow
-
-1. User goes to Settings > Security > Two-Factor Auth tab
-2. `POST /api/auth/mfa/setup` -- returns `{ qrCodeDataUrl, secret, uri }`
-3. User scans QR code in authenticator app (Google Authenticator, Authy, etc.)
-4. User enters 6-digit code to confirm
-5. `POST /api/auth/mfa/enable` with `{ token }` -- returns `{ recoveryCodes[] }`
-6. **User must save their 10 recovery codes** (displayed once, bcrypt-hashed in DB)
-
-### Login with MFA
-
-1. `POST /api/auth/login` returns `{ mfaRequired: true, mfaToken }` instead of session
-2. Frontend shows 6-digit PIN input (or recovery code input)
-3. `POST /api/auth/mfa/verify` with `{ mfaToken, token, useRecovery? }`
-4. On success: full session issued (access token + refresh cookie)
-
-### Recovery Codes
-
-- 10 codes generated on MFA enable
-- Each code is single-use (removed from array after verification)
-- Codes are bcrypt-hashed in `shared.users.recovery_codes` (JSON array)
+## 12. Multi-Factor Authentication (TOTP)
 
 ### MFA Endpoints
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| `POST` | `/api/auth/mfa/setup` | JWT | Generate QR + secret |
-| `POST` | `/api/auth/mfa/enable` | JWT | Verify code and enable MFA |
-| `POST` | `/api/auth/mfa/verify` | No (uses mfaToken) | Verify during login |
-| `POST` | `/api/auth/mfa/disable` | JWT | Disable MFA (requires password) |
-| `GET`  | `/api/auth/mfa/status` | JWT | Check if MFA is enabled |
-
-### Tech Stack
-
-- Library: `otplib` v4 (`generateSecret`, `generateURI`, `verifySync`)
-- QR codes: `qrcode` package (data URL output)
-- Recovery codes: `crypto.randomBytes` + `bcryptjs`
+| `POST` | `/api/auth/mfa/setup` | JWT | Generate QR code + secret |
+| `POST` | `/api/auth/mfa/enable` | JWT | Enable MFA with TOTP code |
+| `POST` | `/api/auth/mfa/verify` | mfaToken | Verify during login |
+| `POST` | `/api/auth/mfa/disable` | JWT | Disable (requires password) |
+| `GET` | `/api/auth/mfa/status` | JWT | Check MFA status |
 
 ---
 
-## 8. Single Sign-On (SSO)
+## 13. Single Sign-On (SSO)
 
-### Supported Providers
+| Provider | Env Vars Required |
+|----------|-------------------|
+| Google | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_CALLBACK_URL` |
+| Microsoft/Azure AD | `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `AZURE_CALLBACK_URL` |
 
-| Provider | Library | Env Vars Required |
-|----------|---------|-------------------|
-| Google | `passport-google-oauth20` | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_CALLBACK_URL` |
-| Microsoft/Azure AD | `passport-azure-ad` | `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `AZURE_CALLBACK_URL` |
-
-SSO providers are **conditionally loaded** -- they only appear on the login page if their env vars are configured. The `GET /api/auth/sso/providers` endpoint returns `{ google: boolean, azure: boolean }`.
-
-### SSO Login Flow
-
-1. Frontend redirects to `/api/auth/google` or `/api/auth/azure`
-2. Passport handles OAuth redirect to provider
-3. Provider redirects back to `/api/auth/{provider}/callback`
-4. Backend creates or links user via `SsoService.findOrCreateSsoUser()`
-5. Session tokens issued, redirect to `/sso-callback?token={accessToken}`
-
-### Account Linking
-
-- SSO fields stored on `shared.users`: `sso_provider`, `sso_id`
-- If email matches existing user, SSO is auto-linked on first login
-- Users can unlink: `DELETE /api/auth/sso/unlink/:provider`
-
-### SSO Endpoints
-
-| Method | Path | Auth | Description |
-|--------|------|------|-------------|
-| `GET` | `/api/auth/sso/providers` | No | List configured providers |
-| `GET` | `/api/auth/google/callback` | No (OAuth) | Google callback |
-| `GET` | `/api/auth/azure/callback` | No (OAuth) | Azure callback |
-| `DELETE` | `/api/auth/sso/unlink/:provider` | JWT | Unlink SSO provider |
+SSO providers are conditionally loaded based on env vars.
 
 ---
 
-## 9. Passkeys (WebAuthn)
-
-### Registration Flow (authenticated user)
-
-1. `POST /api/auth/passkeys/register-options` -- returns WebAuthn creation options
-2. Browser `navigator.credentials.create()` via `@simplewebauthn/browser`
-3. `POST /api/auth/passkeys/register` with `{ response, deviceName? }`
-4. Credential stored in `shared.user_passkeys`
-
-### Login Flow (unauthenticated)
-
-1. `POST /api/auth/passkeys/login-options` with `{ email? }` -- returns assertion options
-2. Browser `navigator.credentials.get()` via `@simplewebauthn/browser`
-3. `POST /api/auth/passkeys/login` with `{ response, challenge }`
-4. Full session issued on success
-
-### Passkey Endpoints
+## 14. Passkeys (WebAuthn)
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
@@ -354,157 +399,141 @@ SSO providers are **conditionally loaded** -- they only appear on the login page
 | `POST` | `/api/auth/passkeys/register` | JWT | Complete registration |
 | `POST` | `/api/auth/passkeys/login-options` | No | Get authentication options |
 | `POST` | `/api/auth/passkeys/login` | No | Authenticate with passkey |
-| `GET`  | `/api/auth/passkeys` | JWT | List registered passkeys |
+| `GET` | `/api/auth/passkeys` | JWT | List user's passkeys |
 | `DELETE` | `/api/auth/passkeys/:id` | JWT | Remove a passkey |
 
-### Configuration
-
-- `WEBAUTHN_RP_ID` -- Relying party ID (e.g., `localhost` for dev, `yourdomain.com` for prod)
-- `WEBAUTHN_RP_ORIGIN` -- Expected origin (e.g., `http://localhost` or `https://yourdomain.com`)
-- Passkey removal is blocked if the user has no password and no other passkeys (prevents lockout)
-
 ---
 
-## 10. Environment Variables Reference
+## 15. Environment Variables Reference
 
 ### Stripe (Required for billing)
 
-| Variable | Example | Description |
-|----------|---------|-------------|
-| `STRIPE_SECRET_KEY` | `sk_test_...` | Stripe secret key. Must NOT contain "placeholder" to activate. |
-| `STRIPE_WEBHOOK_SECRET` | `whsec_...` | Webhook endpoint signing secret |
-| `STRIPE_STARTER_PRICE_ID` | `price_...` | Stripe Price ID for Starter plan |
-| `STRIPE_PROFESSIONAL_PRICE_ID` | `price_...` | Stripe Price ID for Professional plan |
-| `STRIPE_ENTERPRISE_PRICE_ID` | `price_...` | Stripe Price ID for Enterprise plan |
+| Variable | Description |
+|----------|-------------|
+| `STRIPE_SECRET_KEY` | Stripe secret key. Must NOT contain "placeholder" to activate. |
+| `STRIPE_WEBHOOK_SECRET` | Webhook endpoint signing secret |
+| `STRIPE_STARTER_MONTHLY_PRICE_ID` | Stripe Price ID for Starter monthly |
+| `STRIPE_STARTER_ANNUAL_PRICE_ID` | Stripe Price ID for Starter annual |
+| `STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID` | Stripe Price ID for Professional monthly |
+| `STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID` | Stripe Price ID for Professional annual |
+| `STRIPE_ENTERPRISE_MONTHLY_PRICE_ID` | Stripe Price ID for Enterprise monthly |
+| `STRIPE_ENTERPRISE_ANNUAL_PRICE_ID` | Stripe Price ID for Enterprise annual |
 
-### SSO (Optional -- features hidden when not set)
+Legacy single-price vars (`STRIPE_STARTER_PRICE_ID`, etc.) are still supported as fallback for monthly prices.
 
-| Variable | Example | Description |
+### Trial Configuration
+
+| Variable | Default | Description |
 |----------|---------|-------------|
-| `GOOGLE_CLIENT_ID` | `xxx.apps.googleusercontent.com` | Google OAuth client ID |
-| `GOOGLE_CLIENT_SECRET` | `GOCSPX-...` | Google OAuth client secret |
-| `GOOGLE_CALLBACK_URL` | `http://localhost/api/auth/google/callback` | OAuth redirect URI |
-| `AZURE_CLIENT_ID` | `uuid` | Azure AD application (client) ID |
-| `AZURE_CLIENT_SECRET` | `...` | Azure AD client secret |
-| `AZURE_TENANT_ID` | `uuid` | Azure AD tenant (directory) ID |
-| `AZURE_CALLBACK_URL` | `http://localhost/api/auth/azure/callback` | OAuth redirect URI |
+| `REQUIRE_PAYMENT_METHOD_FOR_TRIAL` | `false` | Set to `true` to require card upfront via Stripe Checkout |
+
+### SSO (Optional)
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
+| `GOOGLE_CALLBACK_URL` | OAuth redirect URI |
+| `AZURE_CLIENT_ID` | Azure AD application (client) ID |
+| `AZURE_CLIENT_SECRET` | Azure AD client secret |
+| `AZURE_TENANT_ID` | Azure AD tenant ID |
+| `AZURE_CALLBACK_URL` | OAuth redirect URI |
 
 ### WebAuthn / Passkeys
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `WEBAUTHN_RP_ID` | `localhost` | Relying party identifier (your domain) |
+| `WEBAUTHN_RP_ID` | `localhost` | Relying party identifier |
 | `WEBAUTHN_RP_ORIGIN` | `http://localhost` | Expected browser origin |
 
 ### Other
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `INVITE_TOKEN_SECRET` | `dev-invite-secret` | Secret for signing invite/activation JWTs. **Change in production.** |
-| `APP_URL` | `http://localhost` | Base URL for generated links (activation emails, Stripe redirects) |
+| `INVITE_TOKEN_SECRET` | `dev-invite-secret` | Secret for invite/activation JWTs |
+| `APP_URL` | `http://localhost` | Base URL for generated links |
+| `RESEND_API_KEY` | -- | Resend email provider API key |
 
 ---
 
-## 11. Manual Intervention & Ops Tasks
+## 16. Manual Intervention & Ops Tasks
 
-### Before Going Live
+### Stripe Dashboard Setup
 
-1. **Set up Stripe products and prices** in the Stripe Dashboard:
-   - Create 3 products (Starter, Professional, Enterprise)
-   - Create monthly recurring prices for each
-   - Copy the Price IDs into `STRIPE_STARTER_PRICE_ID`, etc.
+1. **Create Products and Prices** for each plan:
+   - Starter: monthly ($29/mo recurring) + annual ($261/yr recurring)
+   - Professional: monthly ($79/mo recurring) + annual ($711/yr recurring)
+   - Enterprise: monthly + annual (custom pricing)
+   - Copy all Price IDs to env vars
 
-2. **Configure the Stripe webhook** in the Stripe Dashboard:
-   - Endpoint URL: `https://yourdomain.com/api/webhooks/stripe`
-   - Events to subscribe: `checkout.session.completed`, `invoice.payment_succeeded`, `invoice.payment_failed`, `customer.subscription.deleted`
-   - Copy the webhook signing secret to `STRIPE_WEBHOOK_SECRET`
+2. **Configure Stripe Webhook** endpoint:
+   - URL: `https://yourdomain.com/api/webhooks/stripe`
+   - Events: `checkout.session.completed`, `invoice.payment_succeeded`, `invoice.payment_failed`, `customer.subscription.deleted`, `customer.subscription.trial_will_end`, `customer.subscription.updated`
 
-3. **Replace the email stub** with a real provider:
-   - `backend/src/modules/email/email.service.ts` currently logs to console + DB
-   - Swap in Resend, SendGrid, SES, or your preferred provider
-   - The four email methods to implement: `sendActivationEmail`, `sendWelcomeEmail`, `sendPaymentFailedEmail`, `sendInviteMemberEmail`
+3. **Configure Stripe Customer Portal**:
+   - Enable plan switching (allow switching between monthly and annual prices)
+   - Enable payment method updates
+   - Enable cancellation
+   - Enable invoice history
 
-4. **Set production secrets**:
-   - `INVITE_TOKEN_SECRET` -- use a strong random string (not `dev-invite-secret`)
-   - `JWT_SECRET` -- already required, verify it's strong
-   - `WEBAUTHN_RP_ID` and `WEBAUTHN_RP_ORIGIN` -- set to your production domain
+4. **Set production secrets**: `INVITE_TOKEN_SECRET`, `JWT_SECRET`, `WEBAUTHN_RP_ID`, `WEBAUTHN_RP_ORIGIN`
 
-5. **Configure SSO providers** (if desired):
-   - Register apps in Google Cloud Console and/or Azure AD
-   - Set the callback URLs to your production domain
-   - Add client IDs and secrets to env vars
-
-6. **Set up the Stripe Customer Portal** in Stripe Dashboard:
-   - Configure allowed actions (cancel, upgrade/downgrade, payment method updates)
-   - The `/api/billing/portal` endpoint needs the org-context customer ID lookup completed
+5. **Configure SSO providers** (optional)
 
 ### Ongoing Ops
 
-7. **Refresh token cleanup**: The `RefreshTokenService.cleanupExpired()` method deletes tokens that have been expired or revoked for 7+ days. **This is not currently called on a schedule.** Options:
-   - Add a cron job / scheduled task that calls it periodically
-   - Or add a NestJS `@Cron()` decorator (requires `@nestjs/schedule`)
+- **Refresh token cleanup**: Schedule `RefreshTokenService.cleanupExpired()` periodically
+- **Monitor `shared.email_log`**: Check for failed email deliveries
+- **ACH/Invoice customers**: Admin sets up via `PUT /api/admin/organizations/:id/billing`
 
-8. **Monitor `shared.email_log`**: While email is stubbed, activation URLs are only visible in:
-   - Backend console logs (look for lines starting with `EMAIL STUB`)
-   - The `shared.email_log` table (query: `SELECT * FROM shared.email_log ORDER BY sent_at DESC`)
+### Finding activation URLs (dev/testing)
 
-9. **Finding activation URLs manually** (dev/testing):
-   ```sql
-   SELECT to_email, metadata->>'activationUrl' AS url, sent_at
-   FROM shared.email_log
-   WHERE template = 'activation'
-   ORDER BY sent_at DESC
-   LIMIT 10;
-   ```
-
-10. **Resend an activation email**: `POST /api/auth/resend-activation` with `{ email }` is stubbed (always returns success). To manually generate a new token:
-    ```sql
-    -- Find the user and org
-    SELECT u.id AS user_id, uo.organization_id
-    FROM shared.users u
-    JOIN shared.user_organizations uo ON uo.user_id = u.id
-    WHERE u.email = 'user@example.com';
-    ```
-    Then call `authService.generateInviteToken(userId, orgId, email)` or trigger a fresh checkout.
-
-11. **Deprovisioning / cancellation**: When a Stripe subscription is deleted, the org is set to `archived`. Archived orgs:
-    - Block login (users see "Your organization has been suspended")
-    - Block API access (403 on org-scoped endpoints)
-    - Data is preserved (schema is NOT deleted)
-    - To restore: update `status` back to `active` in `shared.organizations`
+```sql
+SELECT to_email, metadata->>'activationUrl' AS url, sent_at
+FROM shared.email_log
+WHERE template = 'activation'
+ORDER BY sent_at DESC
+LIMIT 10;
+```
 
 ---
 
-## 12. What's Stubbed vs. Production-Ready
+## 17. What's Stubbed vs. Production-Ready
 
 | Component | Status | Notes |
 |-----------|--------|-------|
-| Stripe Checkout | **Ready** (test mode) | Switch to live keys for production |
-| Stripe Webhooks | **Ready** | Signature verification, idempotency, event dispatch all implemented |
-| Stripe Customer Portal | **Stubbed** | Endpoint exists but needs org-context customer ID lookup |
-| Provisioning (org + schema + user) | **Ready** | Inline (synchronous). Consider BullMQ queue for production scale. |
-| Email service | **Stubbed** | Logs to console + `shared.email_log`. Replace with real SMTP/API provider. |
-| Activation (magic link) | **Ready** | Works end-to-end (token generation, validation, password set, session issue) |
-| Onboarding checklist | **Ready** | Server-side progress tracking, step completion, UI wizard |
-| Refresh tokens | **Ready** | Creation, validation, revocation, cleanup method (needs scheduling) |
-| TOTP MFA | **Ready** | Setup, enable, verify, recovery codes, disable |
-| SSO (Google) | **Ready** (needs keys) | Conditional loading, user creation/linking |
-| SSO (Azure AD) | **Ready** (needs keys) | Uses deprecated `passport-azure-ad` (works, consider `@azure/msal-node`) |
-| Passkeys (WebAuthn) | **Ready** | Registration, authentication, removal with lockout protection |
-| Resend activation | **Stubbed** | Always returns success, no actual email sent |
+| Stripe Checkout (card-required flow) | **Ready** (test mode) | Switch to live keys for production |
+| Stripe Trial (no-card flow) | **Ready** (test mode) | Creates customer + subscription server-side |
+| Stripe Webhooks | **Ready** | All 6 events handled with idempotency |
+| Stripe Customer Portal | **Ready** | Full org-context customer ID lookup implemented |
+| Monthly/Annual Pricing | **Ready** | Toggle on pricing page, 6 Stripe Price IDs |
+| ACH/Invoice Billing | **Ready** | Admin endpoint switches collection method |
+| Provisioning | **Ready** | Inline, supports both trial and active status |
+| Email service | **Ready** (with Resend) | Falls back to stub logging if not configured |
+| Trial emails | **Ready** | Trial-ending and trial-expired templates |
+| Access control (past_due) | **Ready** | Read-only grace period for failed payments |
+| Activation (magic link) | **Ready** | Full end-to-end flow |
+| Onboarding checklist | **Ready** | Server-side progress tracking |
+| Refresh tokens | **Ready** | Needs scheduled cleanup |
+| TOTP MFA | **Ready** | Full setup, enable, verify, recovery |
+| SSO (Google/Azure) | **Ready** (needs keys) | Conditional loading |
+| Passkeys (WebAuthn) | **Ready** | Registration, authentication, removal |
 
 ---
 
-## 13. API Endpoint Reference
+## 18. API Endpoint Reference
 
-### Billing (no auth unless noted)
+### Billing
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| `POST` | `/api/billing/create-checkout-session` | No | Create Stripe Checkout, returns `{ url }` |
+| `POST` | `/api/billing/start-trial` | No | Start 14-day no-card trial |
+| `POST` | `/api/billing/create-checkout-session` | No | Create Stripe Checkout (card-required flow) |
 | `POST` | `/api/webhooks/stripe` | Stripe sig | Webhook receiver |
-| `GET`  | `/api/billing/status?session_id=` | No | Poll provisioning status |
-| `POST` | `/api/billing/portal` | JWT | Stripe Customer Portal (stubbed) |
+| `GET` | `/api/billing/status?session_id=` | No | Poll provisioning status |
+| `GET` | `/api/billing/subscription` | JWT | Get current subscription info |
+| `POST` | `/api/billing/portal` | JWT | Create Stripe Customer Portal session |
+| `PUT` | `/api/admin/organizations/:id/billing` | JWT (superadmin) | Switch billing method (card/invoice) |
 
 ### Auth
 
@@ -515,62 +544,44 @@ SSO providers are **conditionally loaded** -- they only appear on the login page
 | `POST` | `/api/auth/refresh` | Cookie | Refresh access token |
 | `POST` | `/api/auth/logout` | Cookie | Logout current session |
 | `POST` | `/api/auth/logout-everywhere` | JWT | Revoke all sessions |
-| `GET`  | `/api/auth/activate?token=` | No | Validate activation token |
+| `GET` | `/api/auth/activate?token=` | No | Validate activation token |
 | `POST` | `/api/auth/activate` | No | Set password + activate |
-| `POST` | `/api/auth/resend-activation` | No | Resend activation (stubbed) |
-| `GET`  | `/api/auth/profile` | JWT | Get user profile |
+| `POST` | `/api/auth/resend-activation` | No | Resend activation email |
+| `GET` | `/api/auth/profile` | JWT | Get user profile |
 | `POST` | `/api/auth/switch-org` | JWT | Switch organization |
 
-### MFA
-
-| Method | Path | Auth | Description |
-|--------|------|------|-------------|
-| `POST` | `/api/auth/mfa/setup` | JWT | Generate QR code + secret |
-| `POST` | `/api/auth/mfa/enable` | JWT | Enable MFA with TOTP code |
-| `POST` | `/api/auth/mfa/verify` | mfaToken | Verify during login |
-| `POST` | `/api/auth/mfa/disable` | JWT | Disable (requires password) |
-| `GET`  | `/api/auth/mfa/status` | JWT | Check MFA status |
-
-### SSO
-
-| Method | Path | Auth | Description |
-|--------|------|------|-------------|
-| `GET`  | `/api/auth/sso/providers` | No | List available providers |
-| `GET`  | `/api/auth/google/callback` | OAuth | Google callback handler |
-| `GET`  | `/api/auth/azure/callback` | OAuth | Azure callback handler |
-| `DELETE` | `/api/auth/sso/unlink/:provider` | JWT | Unlink SSO account |
-
-### Passkeys
-
-| Method | Path | Auth | Description |
-|--------|------|------|-------------|
-| `POST` | `/api/auth/passkeys/register-options` | JWT | Get registration options |
-| `POST` | `/api/auth/passkeys/register` | JWT | Complete registration |
-| `POST` | `/api/auth/passkeys/login-options` | No | Get authentication options |
-| `POST` | `/api/auth/passkeys/login` | No | Authenticate with passkey |
-| `GET`  | `/api/auth/passkeys` | JWT | List user's passkeys |
-| `DELETE` | `/api/auth/passkeys/:id` | JWT | Remove a passkey |
-
 ### Onboarding
 
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
-| `GET`  | `/api/onboarding/progress` | JWT | Get onboarding progress |
+| `GET` | `/api/onboarding/progress` | JWT | Get onboarding progress |
 | `PATCH` | `/api/onboarding/progress` | JWT | Mark step complete |
 
 ---
 
-## Database Tables Added (Migration 015)
+## Database Tables & Columns
+
+### Tables Added (Migration 015)
 
 | Table | Purpose |
 |-------|---------|
-| `shared.refresh_tokens` | Stores SHA-256 hashed refresh tokens with expiry/revocation |
-| `shared.stripe_events` | Idempotency ledger for Stripe webhook events |
-| `shared.invite_tokens` | Tracks activation/invite magic links |
+| `shared.refresh_tokens` | Hashed refresh tokens with expiry/revocation |
+| `shared.stripe_events` | Idempotency ledger for Stripe webhooks |
+| `shared.invite_tokens` | Activation/invite magic links |
 | `shared.onboarding_progress` | Per-org onboarding step completion |
-| `shared.user_passkeys` | WebAuthn credential storage |
-| `shared.email_log` | Stubbed email audit trail |
+| `shared.user_passkeys` | WebAuthn credentials |
+| `shared.email_log` | Email audit trail |
 
-Columns added to existing tables:
-- `shared.organizations`: `stripe_customer_id`, `stripe_subscription_id`, `trial_ends_at`
-- `shared.users`: `totp_verified_at`, `recovery_codes`, `webauthn_challenge`
+### Columns Added to `shared.organizations`
+
+| Column | Type | Migration | Description |
+|--------|------|-----------|-------------|
+| `stripe_customer_id` | VARCHAR(255) UNIQUE | 015 | Stripe customer ID |
+| `stripe_subscription_id` | VARCHAR(255) UNIQUE | 015 | Stripe subscription ID |
+| `trial_ends_at` | TIMESTAMPTZ | 015 | Trial expiration date |
+| `billing_interval` | VARCHAR(20) | 017 | `month` or `year` |
+| `collection_method` | VARCHAR(20) | 017 | `charge_automatically` or `send_invoice` |
+
+### Organization Status Values
+
+`active`, `trial`, `past_due`, `suspended`, `archived`

PARKING-LOT.md

@@ -0,0 +1,22 @@
+# Parking Lot — Features Hidden or Deferred
+
+This document tracks features that have been built but are currently hidden or deferred for future use.
+
+---
+
+## Invoices & Payments (Hidden as of 2026.03.19)
+
+**Status:** Built but hidden from navigation
+
+**What exists:**
+- Full Invoices page at `/invoices` with CRUD, generation, and management
+- Full Payments page at `/payments` with payment tracking and reconciliation
+- Backend API endpoints for both modules are fully functional
+- Routes remain registered in `App.tsx` (accessible via direct URL if needed)
+
+**Where hidden:**
+- `frontend/src/components/layout/Sidebar.tsx` — Navigation links commented out in the Transactions section
+
+**To re-enable:**
+1. Uncomment the Invoices and Payments entries in `Sidebar.tsx` (search for "PARKING-LOT.md")
+2. No other changes needed — routes and backend are intact

backend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hoa-ledgeriq-backend",
-  "version": "2026.3.17",
+  "version": "2026.3.19",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoa-ledgeriq-backend",
-      "version": "2026.3.17",
+      "version": "2026.3.19",
       "dependencies": {
         "@nestjs/common": "^10.4.15",
         "@nestjs/config": "^3.3.0",

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoa-ledgeriq-backend",
-  "version": "2026.3.17",
+  "version": "2026.3.24",
   "description": "HOA LedgerIQ - Backend API",
   "private": true,
   "scripts": {

backend/src/app.module.ts

@@ -7,6 +7,7 @@ import { AppController } from './app.controller';
 import { DatabaseModule } from './database/database.module';
 import { TenantMiddleware } from './database/tenant.middleware';
 import { WriteAccessGuard } from './common/guards/write-access.guard';
+import { CapabilityGuard } from './common/guards/capability.guard';
 import { NoCacheInterceptor } from './common/interceptors/no-cache.interceptor';
 import { AuthModule } from './modules/auth/auth.module';
 import { OrganizationsModule } from './modules/organizations/organizations.module';
@@ -33,6 +34,8 @@ import { BoardPlanningModule } from './modules/board-planning/board-planning.mod
 import { BillingModule } from './modules/billing/billing.module';
 import { EmailModule } from './modules/email/email.module';
 import { OnboardingModule } from './modules/onboarding/onboarding.module';
+import { IdeasModule } from './modules/ideas/ideas.module';
+import { ShadowAiModule } from './modules/shadow-ai/shadow-ai.module';
 import { ScheduleModule } from '@nestjs/schedule';
 
 @Module({
@@ -88,6 +91,8 @@ import { ScheduleModule } from '@nestjs/schedule';
     BillingModule,
     EmailModule,
     OnboardingModule,
+    IdeasModule,
+    ShadowAiModule,
     ScheduleModule.forRoot(),
   ],
   controllers: [AppController],
@@ -96,6 +101,10 @@ import { ScheduleModule } from '@nestjs/schedule';
       provide: APP_GUARD,
       useClass: WriteAccessGuard,
     },
+    {
+      provide: APP_GUARD,
+      useClass: CapabilityGuard,
+    },
     {
       provide: APP_INTERCEPTOR,
       useClass: NoCacheInterceptor,

backend/src/common/decorators/capability.decorator.ts

@@ -0,0 +1,14 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const CAPABILITIES_KEY = 'required_capabilities';
+
+/**
+ * Decorator to require specific capabilities on an endpoint.
+ * User must have ALL listed capabilities to access the endpoint.
+ *
+ * Usage:
+ *   @RequireCapability('financials.accounts.edit')
+ *   @RequireCapability('financials.accounts.view', 'financials.accounts.edit')
+ */
+export const RequireCapability = (...capabilities: string[]) =>
+  SetMetadata(CAPABILITIES_KEY, capabilities);

backend/src/common/guards/capability.guard.ts

@@ -0,0 +1,83 @@
+import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { DataSource } from 'typeorm';
+import { CAPABILITIES_KEY } from '../decorators/capability.decorator';
+import { resolveCapabilities } from '../permissions';
+
+@Injectable()
+export class CapabilityGuard implements CanActivate {
+  // Cache org settings (including permissionOverrides) per orgId
+  private settingsCache = new Map<string, { settings: Record<string, any>; cachedAt: number }>();
+  private static readonly CACHE_TTL = 60_000; // 60 seconds
+
+  constructor(
+    private reflector: Reflector,
+    private dataSource: DataSource,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const requiredCapabilities = this.reflector.getAllAndOverride<string[]>(CAPABILITIES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    // No capabilities required — pass through (backward compatible)
+    if (!requiredCapabilities || requiredCapabilities.length === 0) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+
+    // No authenticated user — let other guards handle auth
+    if (!user) return true;
+
+    // Superadmins bypass all capability checks
+    if (user.isSuperadmin) return true;
+
+    const role = user.role;
+    const orgId = user.orgId;
+
+    if (!role || !orgId) return true;
+
+    // Get org settings (with caching)
+    const settings = await this.getOrgSettings(orgId);
+    const userCapabilities = resolveCapabilities(role, settings?.permissionOverrides);
+
+    // User must have ALL required capabilities
+    const hasAll = requiredCapabilities.every((cap) => userCapabilities.has(cap));
+    if (!hasAll) {
+      throw new ForbiddenException(
+        'You do not have the required permissions for this action.',
+      );
+    }
+
+    return true;
+  }
+
+  private async getOrgSettings(orgId: string): Promise<Record<string, any> | null> {
+    const cached = this.settingsCache.get(orgId);
+    if (cached && Date.now() - cached.cachedAt < CapabilityGuard.CACHE_TTL) {
+      return cached.settings;
+    }
+    try {
+      const result = await this.dataSource.query(
+        `SELECT settings FROM shared.organizations WHERE id = $1`,
+        [orgId],
+      );
+      if (result.length > 0) {
+        const settings = result[0].settings || {};
+        this.settingsCache.set(orgId, { settings, cachedAt: Date.now() });
+        return settings;
+      }
+    } catch {
+      // Non-critical — fall through to use defaults only
+    }
+    return null;
+  }
+
+  /** Clear cached settings for an org (call after settings update) */
+  clearCache(orgId: string) {
+    this.settingsCache.delete(orgId);
+  }
+}

backend/src/common/guards/write-access.guard.ts

@@ -30,6 +30,13 @@ export class WriteAccessGuard implements CanActivate {
       throw new ForbiddenException('Read-only users cannot modify data');
     }
 
+    // Block writes for past_due organizations (grace period: read-only access)
+    if (request.orgPastDue) {
+      throw new ForbiddenException(
+        'Your subscription is past due. Please update your payment method to continue making changes.',
+      );
+    }
+
     return true;
   }
 }

backend/src/common/permissions/capabilities.ts

@@ -0,0 +1,65 @@
+/**
+ * Capability taxonomy for the HOA Financial Platform.
+ *
+ * Pattern: {area}.{feature}.{action}
+ * Actions: view, edit, approve, manage
+ *
+ * Add new capabilities here when new features are built.
+ * The default role matrix in ./default-role-capabilities.ts must also be updated.
+ */
+export const CAPABILITIES = {
+  // Dashboard
+  DASHBOARD_VIEW: 'dashboard.view',
+
+  // Financials
+  FINANCIALS_ACCOUNTS_VIEW: 'financials.accounts.view',
+  FINANCIALS_ACCOUNTS_EDIT: 'financials.accounts.edit',
+  FINANCIALS_CASHFLOW_VIEW: 'financials.cashflow.view',
+  FINANCIALS_CASHFLOW_EDIT: 'financials.cashflow.edit',
+  FINANCIALS_ACTUALS_VIEW: 'financials.actuals.view',
+  FINANCIALS_ACTUALS_EDIT: 'financials.actuals.edit',
+  FINANCIALS_BUDGETS_VIEW: 'financials.budgets.view',
+  FINANCIALS_BUDGETS_EDIT: 'financials.budgets.edit',
+  FINANCIALS_BUDGETS_APPROVE: 'financials.budgets.approve',
+
+  // Assessments
+  ASSESSMENTS_UNITS_VIEW: 'assessments.units.view',
+  ASSESSMENTS_UNITS_EDIT: 'assessments.units.edit',
+  ASSESSMENTS_GROUPS_VIEW: 'assessments.groups.view',
+  ASSESSMENTS_GROUPS_EDIT: 'assessments.groups.edit',
+
+  // Board Planning
+  PLANNING_BUDGETS_VIEW: 'planning.budgets.view',
+  PLANNING_BUDGETS_EDIT: 'planning.budgets.edit',
+  PLANNING_PROJECTS_VIEW: 'planning.projects.view',
+  PLANNING_PROJECTS_EDIT: 'planning.projects.edit',
+  PLANNING_SCENARIOS_VIEW: 'planning.scenarios.view',
+  PLANNING_SCENARIOS_EDIT: 'planning.scenarios.edit',
+  PLANNING_SCENARIOS_APPROVE: 'planning.scenarios.approve',
+  PLANNING_INVESTMENTS_VIEW: 'planning.investments.view',
+  PLANNING_INVESTMENTS_EDIT: 'planning.investments.edit',
+
+  // Board Reference
+  REFERENCE_VENDORS_VIEW: 'reference.vendors.view',
+  REFERENCE_VENDORS_EDIT: 'reference.vendors.edit',
+
+  // Transactions
+  TRANSACTIONS_VIEW: 'transactions.view',
+  TRANSACTIONS_EDIT: 'transactions.edit',
+  TRANSACTIONS_APPROVE: 'transactions.approve',
+
+  // Reports
+  REPORTS_VIEW: 'reports.view',
+
+  // Settings & Administration
+  SETTINGS_ORG_VIEW: 'settings.org.view',
+  SETTINGS_ORG_EDIT: 'settings.org.edit',
+  SETTINGS_MEMBERS_VIEW: 'settings.members.view',
+  SETTINGS_MEMBERS_MANAGE: 'settings.members.manage',
+  SETTINGS_PERMISSIONS_MANAGE: 'settings.permissions.manage',
+} as const;
+
+export type Capability = (typeof CAPABILITIES)[keyof typeof CAPABILITIES];
+
+/** Set of all valid capability strings, for validation */
+export const ALL_CAPABILITIES = new Set<string>(Object.values(CAPABILITIES));

backend/src/common/permissions/default-role-capabilities.ts

@@ -0,0 +1,157 @@
+import { CAPABILITIES, Capability } from './capabilities';
+
+const C = CAPABILITIES;
+
+/**
+ * Default capability sets per role.
+ *
+ * These represent sensible defaults for a typical HOA. Tenant admins can
+ * customize per-role capabilities via permission overrides in org settings.
+ *
+ * Roles not listed here (e.g. unknown future roles) get zero capabilities.
+ */
+export const DEFAULT_ROLE_CAPABILITIES: Record<string, readonly Capability[]> = {
+  president: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW, C.FINANCIALS_ACCOUNTS_EDIT,
+    C.FINANCIALS_CASHFLOW_VIEW, C.FINANCIALS_CASHFLOW_EDIT,
+    C.FINANCIALS_ACTUALS_VIEW, C.FINANCIALS_ACTUALS_EDIT,
+    C.FINANCIALS_BUDGETS_VIEW, C.FINANCIALS_BUDGETS_EDIT, C.FINANCIALS_BUDGETS_APPROVE,
+    C.ASSESSMENTS_UNITS_VIEW, C.ASSESSMENTS_UNITS_EDIT,
+    C.ASSESSMENTS_GROUPS_VIEW, C.ASSESSMENTS_GROUPS_EDIT,
+    C.PLANNING_BUDGETS_VIEW, C.PLANNING_BUDGETS_EDIT,
+    C.PLANNING_PROJECTS_VIEW, C.PLANNING_PROJECTS_EDIT,
+    C.PLANNING_SCENARIOS_VIEW, C.PLANNING_SCENARIOS_EDIT, C.PLANNING_SCENARIOS_APPROVE,
+    C.PLANNING_INVESTMENTS_VIEW, C.PLANNING_INVESTMENTS_EDIT,
+    C.REFERENCE_VENDORS_VIEW, C.REFERENCE_VENDORS_EDIT,
+    C.TRANSACTIONS_VIEW, C.TRANSACTIONS_EDIT, C.TRANSACTIONS_APPROVE,
+    C.REPORTS_VIEW,
+    C.SETTINGS_ORG_VIEW, C.SETTINGS_ORG_EDIT,
+    C.SETTINGS_MEMBERS_VIEW, C.SETTINGS_MEMBERS_MANAGE,
+    C.SETTINGS_PERMISSIONS_MANAGE,
+  ],
+
+  admin: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW, C.FINANCIALS_ACCOUNTS_EDIT,
+    C.FINANCIALS_CASHFLOW_VIEW, C.FINANCIALS_CASHFLOW_EDIT,
+    C.FINANCIALS_ACTUALS_VIEW, C.FINANCIALS_ACTUALS_EDIT,
+    C.FINANCIALS_BUDGETS_VIEW, C.FINANCIALS_BUDGETS_EDIT, C.FINANCIALS_BUDGETS_APPROVE,
+    C.ASSESSMENTS_UNITS_VIEW, C.ASSESSMENTS_UNITS_EDIT,
+    C.ASSESSMENTS_GROUPS_VIEW, C.ASSESSMENTS_GROUPS_EDIT,
+    C.PLANNING_BUDGETS_VIEW, C.PLANNING_BUDGETS_EDIT,
+    C.PLANNING_PROJECTS_VIEW, C.PLANNING_PROJECTS_EDIT,
+    C.PLANNING_SCENARIOS_VIEW, C.PLANNING_SCENARIOS_EDIT, C.PLANNING_SCENARIOS_APPROVE,
+    C.PLANNING_INVESTMENTS_VIEW, C.PLANNING_INVESTMENTS_EDIT,
+    C.REFERENCE_VENDORS_VIEW, C.REFERENCE_VENDORS_EDIT,
+    C.TRANSACTIONS_VIEW, C.TRANSACTIONS_EDIT, C.TRANSACTIONS_APPROVE,
+    C.REPORTS_VIEW,
+    C.SETTINGS_ORG_VIEW, C.SETTINGS_ORG_EDIT,
+    C.SETTINGS_MEMBERS_VIEW, C.SETTINGS_MEMBERS_MANAGE,
+    C.SETTINGS_PERMISSIONS_MANAGE,
+  ],
+
+  vice_president: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW,
+    C.FINANCIALS_CASHFLOW_VIEW,
+    C.FINANCIALS_ACTUALS_VIEW,
+    C.FINANCIALS_BUDGETS_VIEW,
+    C.ASSESSMENTS_UNITS_VIEW,
+    C.ASSESSMENTS_GROUPS_VIEW,
+    C.PLANNING_BUDGETS_VIEW,
+    C.PLANNING_PROJECTS_VIEW,
+    C.PLANNING_SCENARIOS_VIEW,
+    C.PLANNING_INVESTMENTS_VIEW,
+    C.REFERENCE_VENDORS_VIEW,
+    C.TRANSACTIONS_VIEW,
+    C.REPORTS_VIEW,
+    C.SETTINGS_ORG_VIEW,
+    C.SETTINGS_MEMBERS_VIEW,
+  ],
+
+  treasurer: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW, C.FINANCIALS_ACCOUNTS_EDIT,
+    C.FINANCIALS_CASHFLOW_VIEW, C.FINANCIALS_CASHFLOW_EDIT,
+    C.FINANCIALS_ACTUALS_VIEW, C.FINANCIALS_ACTUALS_EDIT,
+    C.FINANCIALS_BUDGETS_VIEW, C.FINANCIALS_BUDGETS_EDIT,
+    C.ASSESSMENTS_UNITS_VIEW, C.ASSESSMENTS_UNITS_EDIT,
+    C.ASSESSMENTS_GROUPS_VIEW, C.ASSESSMENTS_GROUPS_EDIT,
+    C.PLANNING_BUDGETS_VIEW, C.PLANNING_BUDGETS_EDIT,
+    C.PLANNING_PROJECTS_VIEW, C.PLANNING_PROJECTS_EDIT,
+    C.PLANNING_SCENARIOS_VIEW, C.PLANNING_SCENARIOS_EDIT,
+    C.PLANNING_INVESTMENTS_VIEW, C.PLANNING_INVESTMENTS_EDIT,
+    C.REFERENCE_VENDORS_VIEW, C.REFERENCE_VENDORS_EDIT,
+    C.TRANSACTIONS_VIEW, C.TRANSACTIONS_EDIT,
+    C.REPORTS_VIEW,
+    C.SETTINGS_MEMBERS_VIEW,
+  ],
+
+  secretary: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW,
+    C.FINANCIALS_CASHFLOW_VIEW,
+    C.FINANCIALS_ACTUALS_VIEW,
+    C.FINANCIALS_BUDGETS_VIEW,
+    C.ASSESSMENTS_UNITS_VIEW,
+    C.ASSESSMENTS_GROUPS_VIEW,
+    C.PLANNING_BUDGETS_VIEW,
+    C.PLANNING_PROJECTS_VIEW,
+    C.PLANNING_SCENARIOS_VIEW,
+    C.PLANNING_INVESTMENTS_VIEW,
+    C.REFERENCE_VENDORS_VIEW,
+    C.REPORTS_VIEW,
+  ],
+
+  member_at_large: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW,
+    C.FINANCIALS_CASHFLOW_VIEW,
+    C.FINANCIALS_ACTUALS_VIEW,
+    C.FINANCIALS_BUDGETS_VIEW,
+    C.ASSESSMENTS_UNITS_VIEW,
+    C.ASSESSMENTS_GROUPS_VIEW,
+    C.PLANNING_BUDGETS_VIEW,
+    C.PLANNING_PROJECTS_VIEW,
+    C.PLANNING_SCENARIOS_VIEW,
+    C.PLANNING_INVESTMENTS_VIEW,
+    C.REFERENCE_VENDORS_VIEW,
+    C.REPORTS_VIEW,
+  ],
+
+  manager: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW,
+    C.FINANCIALS_CASHFLOW_VIEW,
+    C.FINANCIALS_ACTUALS_VIEW, C.FINANCIALS_ACTUALS_EDIT,
+    C.FINANCIALS_BUDGETS_VIEW,
+    C.ASSESSMENTS_UNITS_VIEW, C.ASSESSMENTS_UNITS_EDIT,
+    C.ASSESSMENTS_GROUPS_VIEW,
+    C.REFERENCE_VENDORS_VIEW, C.REFERENCE_VENDORS_EDIT,
+    C.TRANSACTIONS_VIEW, C.TRANSACTIONS_EDIT,
+    C.REPORTS_VIEW,
+  ],
+
+  homeowner: [
+    C.DASHBOARD_VIEW,
+    C.REPORTS_VIEW,
+  ],
+
+  viewer: [
+    C.DASHBOARD_VIEW,
+    C.FINANCIALS_ACCOUNTS_VIEW,
+    C.FINANCIALS_CASHFLOW_VIEW,
+    C.FINANCIALS_ACTUALS_VIEW,
+    C.FINANCIALS_BUDGETS_VIEW,
+    C.ASSESSMENTS_UNITS_VIEW,
+    C.ASSESSMENTS_GROUPS_VIEW,
+    C.PLANNING_BUDGETS_VIEW,
+    C.PLANNING_PROJECTS_VIEW,
+    C.PLANNING_SCENARIOS_VIEW,
+    C.PLANNING_INVESTMENTS_VIEW,
+    C.REFERENCE_VENDORS_VIEW,
+    C.TRANSACTIONS_VIEW,
+    C.REPORTS_VIEW,
+  ],
+};

backend/src/common/permissions/index.ts

@@ -0,0 +1,5 @@
+export { CAPABILITIES, ALL_CAPABILITIES } from './capabilities';
+export type { Capability } from './capabilities';
+export { DEFAULT_ROLE_CAPABILITIES } from './default-role-capabilities';
+export { resolveCapabilities, resolveCapabilitiesArray } from './resolve-permissions';
+export type { PermissionOverrides } from './resolve-permissions';

backend/src/common/permissions/resolve-permissions.ts

@@ -0,0 +1,57 @@
+import { ALL_CAPABILITIES } from './capabilities';
+import { DEFAULT_ROLE_CAPABILITIES } from './default-role-capabilities';
+
+export interface PermissionOverrides {
+  [role: string]: {
+    grant?: string[];
+    revoke?: string[];
+  };
+}
+
+/**
+ * Resolve effective capabilities for a role, applying tenant overrides.
+ *
+ * 1. Start with default capabilities for the role
+ * 2. Add any granted capabilities from overrides
+ * 3. Remove any revoked capabilities from overrides
+ *
+ * Unknown capabilities in grant/revoke are silently ignored (they may
+ * come from an older version of the overrides).
+ */
+export function resolveCapabilities(
+  role: string,
+  overrides?: PermissionOverrides | null,
+): Set<string> {
+  const defaults = DEFAULT_ROLE_CAPABILITIES[role] || [];
+  const result = new Set<string>(defaults);
+
+  if (overrides && overrides[role]) {
+    const roleOverride = overrides[role];
+
+    if (roleOverride.grant) {
+      for (const cap of roleOverride.grant) {
+        if (ALL_CAPABILITIES.has(cap)) {
+          result.add(cap);
+        }
+      }
+    }
+
+    if (roleOverride.revoke) {
+      for (const cap of roleOverride.revoke) {
+        result.delete(cap);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convenience: resolve to a sorted array (for API responses).
+ */
+export function resolveCapabilitiesArray(
+  role: string,
+  overrides?: PermissionOverrides | null,
+): string[] {
+  return Array.from(resolveCapabilities(role, overrides)).sort();
+}

backend/src/common/utils/ai-caller.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared utility for calling OpenAI-compatible chat completion APIs.
+ * Used by both production AI features and shadow AI benchmarking.
+ */
+
+export interface AICallerParams {
+  apiUrl: string;
+  apiKey: string;
+  model: string;
+  messages: Array<{ role: string; content: string }>;
+  temperature: number;
+  maxTokens: number;
+  timeoutMs?: number;
+}
+
+export interface AICallerResult {
+  content: string;
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+  responseTimeMs: number;
+  rawResponse: string;
+}
+
+export async function callOpenAICompatible(params: AICallerParams): Promise<AICallerResult> {
+  const { apiUrl, apiKey, model, messages, temperature, maxTokens, timeoutMs = 600000 } = params;
+
+  const requestBody = {
+    model,
+    messages,
+    temperature,
+    max_tokens: maxTokens,
+  };
+
+  const bodyString = JSON.stringify(requestBody);
+  const startTime = Date.now();
+
+  const { URL } = await import('url');
+  const https = await import('https');
+
+  const aiResult = await new Promise<{ status: number; body: string }>((resolve, reject) => {
+    // Normalize: strip trailing slash and /chat/completions if user included it
+    let baseUrl = apiUrl.replace(/\/+$/, '');
+    if (baseUrl.endsWith('/chat/completions')) {
+      baseUrl = baseUrl.slice(0, -'/chat/completions'.length);
+    }
+    const url = new URL(`${baseUrl}/chat/completions`);
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || 443,
+      path: url.pathname,
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(bodyString, 'utf-8'),
+      },
+      timeout: timeoutMs,
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        resolve({ status: res.statusCode!, body: data });
+      });
+    });
+
+    req.on('error', (err) => reject(err));
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Request timed out after ${timeoutMs / 1000}s`));
+    });
+
+    req.write(bodyString);
+    req.end();
+  });
+
+  const responseTimeMs = Date.now() - startTime;
+
+  if (aiResult.status >= 400) {
+    throw new Error(`AI API returned ${aiResult.status}: ${aiResult.body}`);
+  }
+
+  const data = JSON.parse(aiResult.body);
+  const content = data.choices?.[0]?.message?.content || null;
+
+  if (!content) {
+    throw new Error('AI model returned empty content');
+  }
+
+  // Clean response: strip markdown fences and thinking blocks
+  let cleaned = content.trim();
+  if (cleaned.startsWith('```')) {
+    cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```\s*$/, '');
+  }
+  cleaned = cleaned.replace(/<think>[\s\S]*?<\/think>\s*/g, '').trim();
+
+  const usage = data.usage || undefined;
+
+  return {
+    content: cleaned,
+    usage,
+    responseTimeMs,
+    rawResponse: content,
+  };
+}

backend/src/database/tenant.middleware.ts

@@ -9,6 +9,7 @@ export interface TenantRequest extends Request {
   orgId?: string;
   userId?: string;
   userRole?: string;
+  orgPastDue?: boolean;
 }
 
 @Injectable()
@@ -41,6 +42,10 @@ export class TenantMiddleware implements NestMiddleware {
               });
               return;
             }
+            // past_due: allow through with read-only flag (WriteAccessGuard enforces)
+            if (orgInfo.status === 'past_due') {
+              req.orgPastDue = true;
+            }
             req.tenantSchema = orgInfo.schemaName;
           }
           req.orgId = decoded.orgId;

backend/src/modules/accounts/accounts.controller.ts

@@ -3,6 +3,7 @@ import {
 } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { AccountsService } from './accounts.service';
 import { CreateAccountDto } from './dto/create-account.dto';
 import { UpdateAccountDto } from './dto/update-account.dto';
@@ -16,24 +17,28 @@ export class AccountsController {
 
   @Get()
   @ApiOperation({ summary: 'List all accounts' })
+  @RequireCapability('financials.accounts.view')
   findAll(@Query('fundType') fundType?: string, @Query('includeArchived') includeArchived?: string) {
     return this.accountsService.findAll(fundType, includeArchived === 'true');
   }
 
   @Get('trial-balance')
   @ApiOperation({ summary: 'Get trial balance' })
+  @RequireCapability('financials.accounts.view')
   getTrialBalance(@Query('asOfDate') asOfDate?: string) {
     return this.accountsService.getTrialBalance(asOfDate);
   }
 
   @Put(':id/set-primary')
   @ApiOperation({ summary: 'Set account as primary for its fund type' })
+  @RequireCapability('financials.accounts.edit')
   setPrimary(@Param('id') id: string) {
     return this.accountsService.setPrimary(id);
   }
 
   @Post('bulk-opening-balances')
   @ApiOperation({ summary: 'Set opening balances for multiple accounts' })
+  @RequireCapability('financials.accounts.edit')
   bulkSetOpeningBalances(
     @Body() dto: { asOfDate: string; entries: { accountId: string; targetBalance: number }[] },
   ) {
@@ -42,6 +47,7 @@ export class AccountsController {
 
   @Post(':id/opening-balance')
   @ApiOperation({ summary: 'Set opening balance for an account at a specific date' })
+  @RequireCapability('financials.accounts.edit')
   setOpeningBalance(
     @Param('id') id: string,
     @Body() dto: { targetBalance: number; asOfDate: string; memo?: string },
@@ -51,6 +57,7 @@ export class AccountsController {
 
   @Post(':id/adjust-balance')
   @ApiOperation({ summary: 'Adjust account balance to a target amount' })
+  @RequireCapability('financials.accounts.edit')
   adjustBalance(
     @Param('id') id: string,
     @Body() dto: { targetBalance: number; asOfDate: string; memo?: string },
@@ -58,20 +65,32 @@ export class AccountsController {
     return this.accountsService.adjustBalance(id, dto);
   }
 
+  @Post('transfer')
+  @ApiOperation({ summary: 'Transfer funds between asset accounts' })
+  @RequireCapability('financials.accounts.edit')
+  transferFunds(
+    @Body() dto: { fromAccountId: string; toAccountId: string; amount: number; transferDate: string; memo?: string },
+  ) {
+    return this.accountsService.transferFunds(dto);
+  }
+
   @Get(':id')
   @ApiOperation({ summary: 'Get account by ID' })
+  @RequireCapability('financials.accounts.view')
   findOne(@Param('id') id: string) {
     return this.accountsService.findOne(id);
   }
 
   @Post()
   @ApiOperation({ summary: 'Create a new account' })
+  @RequireCapability('financials.accounts.edit')
   create(@Body() dto: CreateAccountDto) {
     return this.accountsService.create(dto);
   }
 
   @Put(':id')
   @ApiOperation({ summary: 'Update an account' })
+  @RequireCapability('financials.accounts.edit')
   update(@Param('id') id: string, @Body() dto: UpdateAccountDto) {
     return this.accountsService.update(id, dto);
   }

backend/src/modules/accounts/accounts.service.ts

@@ -74,9 +74,9 @@ export class AccountsService {
 
     // Create opening balance journal entry if initialBalance is provided and non-zero
     if (dto.initialBalance && dto.initialBalance !== 0) {
-      const now = new Date();
-      const year = now.getFullYear();
-      const month = now.getMonth() + 1;
+      const balanceDate = dto.initialBalanceDate ? new Date(dto.initialBalanceDate) : new Date();
+      const year = balanceDate.getFullYear();
+      const month = balanceDate.getMonth() + 1;
 
       // Find the current fiscal period
       const periods = await this.tenant.query(
@@ -111,12 +111,14 @@ export class AccountsService {
           );
         }
 
-        // Create the journal entry
+        // Create the journal entry (use provided balance date or today)
+        const entryDate = dto.initialBalanceDate || new Date().toISOString().split('T')[0];
         const jeInsert = await this.tenant.query(
           `INSERT INTO journal_entries (entry_date, description, entry_type, fiscal_period_id, is_posted, posted_at, created_by)
-           VALUES (CURRENT_DATE, $1, 'opening_balance', $2, true, NOW(), $3)
+           VALUES ($1::date, $2, 'opening_balance', $3, true, NOW(), $4)
            RETURNING id`,
           [
+            entryDate,
             `Opening balance for ${dto.name}`,
             fiscalPeriodId,
             '00000000-0000-0000-0000-000000000000',
@@ -358,6 +360,62 @@ export class AccountsService {
     return journalEntry;
   }
 
+  async transferFunds(dto: {
+    fromAccountId: string;
+    toAccountId: string;
+    amount: number;
+    transferDate: string;
+    memo?: string;
+  }) {
+    if (dto.amount <= 0) throw new BadRequestException('Transfer amount must be positive');
+    if (dto.fromAccountId === dto.toAccountId) throw new BadRequestException('Cannot transfer to the same account');
+
+    const fromAccount = await this.findOne(dto.fromAccountId);
+    const toAccount = await this.findOne(dto.toAccountId);
+
+    if (fromAccount.account_type !== 'asset') throw new BadRequestException('Source account must be an asset account');
+    if (toAccount.account_type !== 'asset') throw new BadRequestException('Destination account must be an asset account');
+
+    // Find fiscal period
+    const asOf = new Date(dto.transferDate);
+    const year = asOf.getFullYear();
+    const month = asOf.getMonth() + 1;
+    const periods = await this.tenant.query(
+      'SELECT id FROM fiscal_periods WHERE year = $1 AND month = $2',
+      [year, month],
+    );
+    if (!periods.length) {
+      throw new BadRequestException(`No fiscal period found for ${year}-${String(month).padStart(2, '0')}`);
+    }
+
+    const memo = dto.memo || `Transfer from ${fromAccount.name} to ${toAccount.name}`;
+
+    // Create journal entry: debit destination (increase), credit source (decrease)
+    const jeRows = await this.tenant.query(
+      `INSERT INTO journal_entries (entry_date, description, entry_type, fiscal_period_id, is_posted, posted_at, created_by)
+       VALUES ($1, $2, 'transfer', $3, true, NOW(), $4)
+       RETURNING *`,
+      [dto.transferDate, memo, periods[0].id, '00000000-0000-0000-0000-000000000000'],
+    );
+    const je = jeRows[0];
+
+    // Credit source account (reduces asset balance)
+    await this.tenant.query(
+      `INSERT INTO journal_entry_lines (journal_entry_id, account_id, debit, credit, memo)
+       VALUES ($1, $2, 0, $3, $4)`,
+      [je.id, dto.fromAccountId, dto.amount, memo],
+    );
+
+    // Debit destination account (increases asset balance)
+    await this.tenant.query(
+      `INSERT INTO journal_entry_lines (journal_entry_id, account_id, debit, credit, memo)
+       VALUES ($1, $2, $3, 0, $4)`,
+      [je.id, dto.toAccountId, dto.amount, memo],
+    );
+
+    return je;
+  }
+
   async getTrialBalance(asOfDate?: string) {
     const dateFilter = asOfDate
       ? `AND je.entry_date <= $1`

backend/src/modules/accounts/dto/create-account.dto.ts

@@ -37,6 +37,11 @@ export class CreateAccountDto {
   @IsOptional()
   initialBalance?: number;
 
+  @ApiProperty({ required: false, description: 'ISO date string (YYYY-MM-DD) for when the initial balance was accurate' })
+  @IsString()
+  @IsOptional()
+  initialBalanceDate?: string;
+
   @ApiProperty({ required: false, description: 'Annual interest rate as a percentage' })
   @IsOptional()
   interestRate?: number;

backend/src/modules/assessment-groups/assessment-groups.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Put, Body, Param, UseGuards } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { AssessmentGroupsService } from './assessment-groups.service';
 
 @ApiTags('assessment-groups')
@@ -11,23 +12,30 @@ export class AssessmentGroupsController {
   constructor(private service: AssessmentGroupsService) {}
 
   @Get()
+  @RequireCapability('assessments.groups.view')
   findAll() { return this.service.findAll(); }
 
   @Get('summary')
+  @RequireCapability('assessments.groups.view')
   getSummary() { return this.service.getSummary(); }
 
   @Get('default')
+  @RequireCapability('assessments.groups.view')
   getDefault() { return this.service.getDefault(); }
 
   @Get(':id')
+  @RequireCapability('assessments.groups.view')
   findOne(@Param('id') id: string) { return this.service.findOne(id); }
 
   @Post()
+  @RequireCapability('assessments.groups.edit')
   create(@Body() dto: any) { return this.service.create(dto); }
 
   @Put(':id')
+  @RequireCapability('assessments.groups.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.service.update(id, dto); }
 
   @Put(':id/set-default')
+  @RequireCapability('assessments.groups.edit')
   setDefault(@Param('id') id: string) { return this.service.setDefault(id); }
 }

backend/src/modules/auth/admin.controller.ts

@@ -5,6 +5,7 @@ import { AuthService } from './auth.service';
 import { UsersService } from '../users/users.service';
 import { OrganizationsService } from '../organizations/organizations.service';
 import { AdminAnalyticsService } from './admin-analytics.service';
+import { IdeasService } from '../ideas/ideas.service';
 import * as bcrypt from 'bcryptjs';
 
 @ApiTags('admin')
@@ -17,6 +18,7 @@ export class AdminController {
     private usersService: UsersService,
     private orgService: OrganizationsService,
     private analyticsService: AdminAnalyticsService,
+    private ideasService: IdeasService,
   ) {}
 
   private async requireSuperadmin(req: any) {
@@ -196,4 +198,45 @@ export class AdminController {
 
     return { success: true, organization: org };
   }
+
+  // ── Ideation ──
+
+  @Get('ideas')
+  async listAllIdeas(@Req() req: any) {
+    await this.requireSuperadmin(req);
+    return this.ideasService.findAll();
+  }
+
+  @Put('ideas/:id/status')
+  async updateIdeaStatus(
+    @Req() req: any,
+    @Param('id') id: string,
+    @Body() body: { status: string },
+  ) {
+    await this.requireSuperadmin(req);
+    const idea = await this.ideasService.updateStatus(id, body.status);
+    return { success: true, idea };
+  }
+
+  @Put('ideas/:id/note')
+  async updateIdeaNote(
+    @Req() req: any,
+    @Param('id') id: string,
+    @Body() body: { adminNote: string },
+  ) {
+    await this.requireSuperadmin(req);
+    const idea = await this.ideasService.updateNote(id, body.adminNote);
+    return { success: true, idea };
+  }
+
+  @Put('organizations/:id/settings')
+  async updateOrgSettings(
+    @Req() req: any,
+    @Param('id') id: string,
+    @Body() body: Record<string, any>,
+  ) {
+    await this.requireSuperadmin(req);
+    const org = await this.orgService.updateSettings(id, body);
+    return { success: true, organization: org };
+  }
 }

backend/src/modules/auth/auth.module.ts

@@ -17,11 +17,13 @@ import { JwtStrategy } from './strategies/jwt.strategy';
 import { LocalStrategy } from './strategies/local.strategy';
 import { UsersModule } from '../users/users.module';
 import { OrganizationsModule } from '../organizations/organizations.module';
+import { IdeasModule } from '../ideas/ideas.module';
 
 @Module({
   imports: [
     UsersModule,
     OrganizationsModule,
+    IdeasModule,
     PassportModule,
     JwtModule.registerAsync({
       imports: [ConfigModule],

backend/src/modules/auth/auth.service.ts

@@ -17,6 +17,7 @@ import { EmailService } from '../email/email.service';
 import { RegisterDto } from './dto/register.dto';
 import { User } from '../users/entities/user.entity';
 import { RefreshTokenService } from './refresh-token.service';
+import { resolveCapabilitiesArray } from '../../common/permissions';
 
 @Injectable()
 export class AuthService {
@@ -162,6 +163,12 @@ export class AuthService {
     // Generate new refresh token for org switch
     const refreshToken = await this.refreshTokenService.createRefreshToken(user.id);
 
+    const orgSettings = membership.organization.settings || {};
+    const capabilities = resolveCapabilitiesArray(
+      membership.role,
+      orgSettings.permissionOverrides,
+    );
+
     return {
       accessToken: this.jwtService.sign(payload),
       refreshToken,
@@ -169,7 +176,8 @@ export class AuthService {
         id: membership.organization.id,
         name: membership.organization.name,
         role: membership.role,
-        settings: membership.organization.settings || {},
+        settings: orgSettings,
+        capabilities,
       },
     };
   }
@@ -468,12 +476,16 @@ export class AuthService {
         hasSeenIntro: user.hasSeenIntro || false,
         mfaEnabled: user.mfaEnabled || false,
       },
-      organizations: orgs.map((uo) => ({
-        id: uo.organizationId,
-        name: uo.organization?.name,
-        status: uo.organization?.status,
-        role: uo.role,
-      })),
+      organizations: orgs.map((uo) => {
+        const settings = uo.organization?.settings || {};
+        return {
+          id: uo.organizationId,
+          name: uo.organization?.name,
+          status: uo.organization?.status,
+          role: uo.role,
+          capabilities: resolveCapabilitiesArray(uo.role, settings.permissionOverrides),
+        };
+      }),
     };
   }
 

backend/src/modules/billing/billing.controller.ts

@@ -1,34 +1,63 @@
 import {
   Controller,
   Post,
+  Put,
   Get,
   Body,
+  Param,
   Query,
   Req,
   UseGuards,
   RawBodyRequest,
   BadRequestException,
+  ForbiddenException,
   Request,
 } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
 import { Throttle } from '@nestjs/throttler';
 import { Request as ExpressRequest } from 'express';
+import { DataSource } from 'typeorm';
 import { BillingService } from './billing.service';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 
 @ApiTags('billing')
 @Controller()
 export class BillingController {
-  constructor(private billingService: BillingService) {}
+  constructor(
+    private billingService: BillingService,
+    private dataSource: DataSource,
+  ) {}
+
+  @Post('billing/start-trial')
+  @ApiOperation({ summary: 'Start a free trial (no card required)' })
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  async startTrial(
+    @Body() body: { planId: string; billingInterval?: 'month' | 'year'; email: string; businessName: string },
+  ) {
+    if (!body.planId) throw new BadRequestException('planId is required');
+    if (!body.email) throw new BadRequestException('email is required');
+    if (!body.businessName) throw new BadRequestException('businessName is required');
+    return this.billingService.startTrial(
+      body.planId,
+      body.billingInterval || 'month',
+      body.email,
+      body.businessName,
+    );
+  }
 
   @Post('billing/create-checkout-session')
   @ApiOperation({ summary: 'Create a Stripe Checkout Session' })
   @Throttle({ default: { limit: 10, ttl: 60000 } })
   async createCheckout(
-    @Body() body: { planId: string; email?: string; businessName?: string },
+    @Body() body: { planId: string; billingInterval?: 'month' | 'year'; email?: string; businessName?: string },
   ) {
     if (!body.planId) throw new BadRequestException('planId is required');
-    return this.billingService.createCheckoutSession(body.planId, body.email, body.businessName);
+    return this.billingService.createCheckoutSession(
+      body.planId,
+      body.billingInterval || 'month',
+      body.email,
+      body.businessName,
+    );
   }
 
   @Post('webhooks/stripe')
@@ -42,22 +71,63 @@ export class BillingController {
   }
 
   @Get('billing/status')
-  @ApiOperation({ summary: 'Check provisioning status for a checkout session' })
+  @ApiOperation({ summary: 'Check provisioning status for a checkout session or subscription' })
   async getStatus(@Query('session_id') sessionId: string) {
     if (!sessionId) throw new BadRequestException('session_id required');
     return this.billingService.getProvisioningStatus(sessionId);
   }
 
+  @Get('billing/subscription')
+  @ApiOperation({ summary: 'Get current subscription info' })
+  @ApiBearerAuth()
+  @UseGuards(JwtAuthGuard)
+  async getSubscription(@Request() req: any) {
+    const orgId = req.user.orgId;
+    if (!orgId) throw new BadRequestException('No organization context');
+    return this.billingService.getSubscriptionInfo(orgId);
+  }
+
   @Post('billing/portal')
   @ApiOperation({ summary: 'Create Stripe Customer Portal session' })
   @ApiBearerAuth()
   @UseGuards(JwtAuthGuard)
   async createPortal(@Request() req: any) {
-    // Lookup the org's stripe_customer_id
-    // Only allow president or superadmin
     const orgId = req.user.orgId;
     if (!orgId) throw new BadRequestException('No organization context');
-    // For now, we'd look this up from the org
-    throw new BadRequestException('Portal session requires stripe_customer_id lookup — implement per org context');
+    return this.billingService.createPortalSession(orgId);
+  }
+
+  // ─── Admin: Switch Billing Method (ACH / Invoice) ──────────
+
+  @Put('admin/organizations/:id/billing')
+  @ApiOperation({ summary: 'Switch organization billing method (superadmin only)' })
+  @ApiBearerAuth()
+  @UseGuards(JwtAuthGuard)
+  async updateBillingMethod(
+    @Request() req: any,
+    @Param('id') id: string,
+    @Body() body: { collectionMethod: 'charge_automatically' | 'send_invoice'; daysUntilDue?: number },
+  ) {
+    // Require superadmin
+    const userId = req.user.userId || req.user.sub;
+    const userRows = await this.dataSource.query(
+      `SELECT is_superadmin FROM shared.users WHERE id = $1`,
+      [userId],
+    );
+    if (!userRows.length || !userRows[0].is_superadmin) {
+      throw new ForbiddenException('Superadmin access required');
+    }
+
+    if (!['charge_automatically', 'send_invoice'].includes(body.collectionMethod)) {
+      throw new BadRequestException('collectionMethod must be "charge_automatically" or "send_invoice"');
+    }
+
+    await this.billingService.switchToInvoiceBilling(
+      id,
+      body.collectionMethod,
+      body.daysUntilDue || 30,
+    );
+
+    return { success: true };
   }
 }

backend/src/modules/billing/billing.service.ts

@@ -14,12 +14,15 @@ const PLAN_FEATURES: Record<string, { name: string; unitLimit: number }> = {
   enterprise: { name: 'Enterprise', unitLimit: 999999 },
 };
 
+type BillingInterval = 'month' | 'year';
+
 @Injectable()
 export class BillingService {
   private readonly logger = new Logger(BillingService.name);
   private stripe: Stripe | null = null;
   private webhookSecret: string;
-  private priceMap: Record<string, string>;
+  private priceMap: Record<string, { monthly: string; annual: string }>;
+  private requirePaymentForTrial: boolean;
 
   constructor(
     private configService: ConfigService,
@@ -37,27 +40,118 @@ export class BillingService {
     }
 
     this.webhookSecret = this.configService.get<string>('STRIPE_WEBHOOK_SECRET') || '';
+    this.requirePaymentForTrial =
+      this.configService.get<string>('REQUIRE_PAYMENT_METHOD_FOR_TRIAL') === 'true';
+
+    // Build price map with backward-compat: new monthly vars fall back to old single vars
     this.priceMap = {
-      starter: this.configService.get<string>('STRIPE_STARTER_PRICE_ID') || '',
-      professional: this.configService.get<string>('STRIPE_PROFESSIONAL_PRICE_ID') || '',
-      enterprise: this.configService.get<string>('STRIPE_ENTERPRISE_PRICE_ID') || '',
+      starter: {
+        monthly: this.configService.get<string>('STRIPE_STARTER_MONTHLY_PRICE_ID')
+          || this.configService.get<string>('STRIPE_STARTER_PRICE_ID') || '',
+        annual: this.configService.get<string>('STRIPE_STARTER_ANNUAL_PRICE_ID') || '',
+      },
+      professional: {
+        monthly: this.configService.get<string>('STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID')
+          || this.configService.get<string>('STRIPE_PROFESSIONAL_PRICE_ID') || '',
+        annual: this.configService.get<string>('STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID') || '',
+      },
+      enterprise: {
+        monthly: this.configService.get<string>('STRIPE_ENTERPRISE_MONTHLY_PRICE_ID')
+          || this.configService.get<string>('STRIPE_ENTERPRISE_PRICE_ID') || '',
+        annual: this.configService.get<string>('STRIPE_ENTERPRISE_ANNUAL_PRICE_ID') || '',
+      },
     };
   }
 
+  // ─── Price Resolution ────────────────────────────────────────
+
+  private getPriceId(planId: string, interval: BillingInterval): string {
+    const plan = this.priceMap[planId];
+    if (!plan) throw new BadRequestException(`Invalid plan: ${planId}`);
+    const priceId = interval === 'year' ? plan.annual : plan.monthly;
+    if (!priceId || priceId.includes('placeholder')) {
+      throw new BadRequestException(`Price not configured for ${planId} (${interval})`);
+    }
+    return priceId;
+  }
+
+  // ─── Trial Signup (No Card Required) ────────────────────────
+
+  /**
+   * Start a free trial without collecting payment.
+   * Creates a Stripe customer + subscription with trial_period_days,
+   * then provisions the organization immediately.
+   */
+  async startTrial(
+    planId: string,
+    billingInterval: BillingInterval,
+    email: string,
+    businessName: string,
+  ): Promise<{ success: boolean; subscriptionId: string }> {
+    if (!this.stripe) throw new BadRequestException('Stripe not configured');
+    if (!email) throw new BadRequestException('Email is required');
+    if (!businessName) throw new BadRequestException('Business name is required');
+
+    const priceId = this.getPriceId(planId, billingInterval);
+
+    // 1. Create Stripe customer
+    const customer = await this.stripe.customers.create({
+      email,
+      metadata: { plan_id: planId, business_name: businessName, billing_interval: billingInterval },
+    });
+
+    // 2. Create subscription with 14-day trial (no payment method)
+    const subscription = await this.stripe.subscriptions.create({
+      customer: customer.id,
+      items: [{ price: priceId }],
+      trial_period_days: 14,
+      payment_settings: {
+        save_default_payment_method: 'on_subscription',
+      },
+      trial_settings: {
+        end_behavior: { missing_payment_method: 'cancel' },
+      },
+      metadata: { plan_id: planId, business_name: businessName, billing_interval: billingInterval },
+    });
+
+    const trialEnd = subscription.trial_end
+      ? new Date(subscription.trial_end * 1000)
+      : new Date(Date.now() + 14 * 24 * 60 * 60 * 1000);
+
+    // 3. Provision organization immediately with trial status
+    await this.provisionOrganization(
+      customer.id,
+      subscription.id,
+      email,
+      planId,
+      businessName,
+      'trial',
+      billingInterval,
+      trialEnd,
+    );
+
+    this.logger.log(`Trial started for ${email}, plan=${planId}, interval=${billingInterval}`);
+    return { success: true, subscriptionId: subscription.id };
+  }
+
+  // ─── Checkout Session (Card-required flow / post-trial) ─────
+
   /**
    * Create a Stripe Checkout Session for a new subscription.
+   * Used when REQUIRE_PAYMENT_METHOD_FOR_TRIAL=true, or for
+   * post-trial conversion where the user adds a payment method.
    */
-  async createCheckoutSession(planId: string, email?: string, businessName?: string): Promise<{ url: string }> {
-    if (!this.stripe) {
-      throw new BadRequestException('Stripe not configured');
-    }
+  async createCheckoutSession(
+    planId: string,
+    billingInterval: BillingInterval = 'month',
+    email?: string,
+    businessName?: string,
+  ): Promise<{ url: string }> {
+    if (!this.stripe) throw new BadRequestException('Stripe not configured');
 
-    const priceId = this.priceMap[planId];
-    if (!priceId || priceId.includes('placeholder')) {
-      throw new BadRequestException(`Invalid plan: ${planId}`);
-    }
+    const priceId = this.getPriceId(planId, billingInterval);
 
-    const session = await this.stripe.checkout.sessions.create({
+    const sessionConfig: Stripe.Checkout.SessionCreateParams = {
       mode: 'subscription',
       payment_method_types: ['card'],
       line_items: [{ price: priceId, quantity: 1 }],
@@ -67,12 +161,28 @@ export class BillingService {
       metadata: {
         plan_id: planId,
         business_name: businessName || '',
+        billing_interval: billingInterval,
       },
-    });
+    };
 
+    // If trial is card-required, add trial period to checkout
+    if (this.requirePaymentForTrial) {
+      sessionConfig.subscription_data = {
+        trial_period_days: 14,
+        metadata: {
+          plan_id: planId,
+          business_name: businessName || '',
+          billing_interval: billingInterval,
+        },
+      };
+    }
+
+    const session = await this.stripe.checkout.sessions.create(sessionConfig);
     return { url: session.url! };
   }
 
+  // ─── Webhook Handling ───────────────────────────────────────
+
   /**
    * Handle a Stripe webhook event.
    */
@@ -117,19 +227,39 @@ export class BillingService {
       case 'customer.subscription.deleted':
         await this.handleSubscriptionDeleted(event.data.object as Stripe.Subscription);
         break;
+      case 'customer.subscription.trial_will_end':
+        await this.handleTrialWillEnd(event.data.object as Stripe.Subscription);
+        break;
+      case 'customer.subscription.updated':
+        await this.handleSubscriptionUpdated(event.data.object as Stripe.Subscription);
+        break;
       default:
         this.logger.log(`Unhandled Stripe event: ${event.type}`);
     }
   }
 
+  // ─── Provisioning Status ────────────────────────────────────
+
   /**
-   * Get provisioning status for a checkout session.
+   * Get provisioning status for a checkout session OR subscription ID.
    */
   async getProvisioningStatus(sessionId: string): Promise<{ status: string; activationUrl?: string }> {
     if (!this.stripe) return { status: 'not_configured' };
 
-    const session = await this.stripe.checkout.sessions.retrieve(sessionId);
-    const customerId = session.customer as string;
+    // Try as checkout session first
+    let customerId: string | null = null;
+    try {
+      const session = await this.stripe.checkout.sessions.retrieve(sessionId);
+      customerId = session.customer as string;
+    } catch {
+      // Not a checkout session — try looking up by subscription ID
+      try {
+        const subscription = await this.stripe.subscriptions.retrieve(sessionId);
+        customerId = subscription.customer as string;
+      } catch {
+        return { status: 'pending' };
+      }
+    }
 
     if (!customerId) return { status: 'pending' };
 
@@ -139,15 +269,56 @@ export class BillingService {
     );
 
     if (rows.length === 0) return { status: 'provisioning' };
-    if (rows[0].status === 'active') return { status: 'active' };
+    if (['active', 'trial'].includes(rows[0].status)) return { status: 'active' };
     return { status: 'provisioning' };
   }
 
+  // ─── Stripe Customer Portal ─────────────────────────────────
+
   /**
-   * Create a Stripe Customer Portal session.
+   * Create a Stripe Customer Portal session for managing subscription.
    */
-  async createPortalSession(customerId: string): Promise<{ url: string }> {
-    if (!this.stripe) throw new BadRequestException('Stripe not configured');
+  async createPortalSession(orgId: string): Promise<{ url: string }> {
+    if (!this.stripe) throw new BadRequestException('Stripe is not configured');
+
+    const rows = await this.dataSource.query(
+      `SELECT stripe_customer_id, stripe_subscription_id, status
+       FROM shared.organizations WHERE id = $1`,
+      [orgId],
+    );
+    if (rows.length === 0) {
+      throw new BadRequestException('Organization not found');
+    }
+
+    let customerId = rows[0].stripe_customer_id;
+
+    // Fallback: if customer ID is missing but subscription exists, retrieve customer from subscription
+    if (!customerId && rows[0].stripe_subscription_id) {
+      try {
+        const sub = await this.stripe.subscriptions.retrieve(rows[0].stripe_subscription_id) as Stripe.Subscription;
+        customerId = typeof sub.customer === 'string' ? sub.customer : sub.customer?.id;
+        if (customerId) {
+          // Backfill the customer ID for future calls
+          await this.dataSource.query(
+            `UPDATE shared.organizations SET stripe_customer_id = $1 WHERE id = $2`,
+            [customerId, orgId],
+          );
+          this.logger.log(`Backfilled stripe_customer_id=${customerId} for org=${orgId}`);
+        }
+      } catch (err) {
+        this.logger.warn(`Failed to retrieve customer from subscription: ${(err as Error).message}`);
+      }
+    }
+
+    if (!customerId) {
+      const status = rows[0].status;
+      if (status === 'trial') {
+        throw new BadRequestException(
+          'Billing portal is not available during your free trial. Add a payment method when your trial ends to manage your subscription.',
+        );
+      }
+      throw new BadRequestException('No Stripe customer found for this organization. Please contact support.');
+    }
 
     const session = await this.stripe.billingPortal.sessions.create({
       customer: customerId,
@@ -157,7 +328,105 @@ export class BillingService {
     return { url: session.url };
   }
 
-  // ─── Provisioning (inline, no BullMQ for now — add queue later) ─────
+  // ─── Subscription Info ──────────────────────────────────────
+
+  /**
+   * Get current subscription details for the Settings billing tab.
+   */
+  async getSubscriptionInfo(orgId: string): Promise<{
+    plan: string;
+    planName: string;
+    billingInterval: string;
+    status: string;
+    collectionMethod: string;
+    trialEndsAt: string | null;
+    currentPeriodEnd: string | null;
+    cancelAtPeriodEnd: boolean;
+    hasStripeCustomer: boolean;
+  }> {
+    const rows = await this.dataSource.query(
+      `SELECT plan_level, billing_interval, status, collection_method,
+              trial_ends_at, stripe_subscription_id, stripe_customer_id
+       FROM shared.organizations WHERE id = $1`,
+      [orgId],
+    );
+
+    if (rows.length === 0) throw new BadRequestException('Organization not found');
+
+    const org = rows[0];
+    let currentPeriodEnd: string | null = null;
+    let cancelAtPeriodEnd = false;
+
+    // Fetch live data from Stripe if available
+    if (this.stripe && org.stripe_subscription_id) {
+      try {
+        const sub = await this.stripe.subscriptions.retrieve(org.stripe_subscription_id, {
+          expand: ['items.data'],
+        }) as Stripe.Subscription;
+        // current_period_end is on the subscription item in newer Stripe API versions
+        const firstItem = sub.items?.data?.[0];
+        if (firstItem?.current_period_end) {
+          currentPeriodEnd = new Date(firstItem.current_period_end * 1000).toISOString();
+        }
+        cancelAtPeriodEnd = sub.cancel_at_period_end;
+      } catch {
+        // Non-critical — use DB data only
+      }
+    }
+
+    return {
+      plan: org.plan_level || 'starter',
+      planName: PLAN_FEATURES[org.plan_level]?.name || org.plan_level || 'Starter',
+      billingInterval: org.billing_interval || 'month',
+      status: org.status || 'active',
+      collectionMethod: org.collection_method || 'charge_automatically',
+      trialEndsAt: org.trial_ends_at ? new Date(org.trial_ends_at).toISOString() : null,
+      currentPeriodEnd,
+      cancelAtPeriodEnd,
+      hasStripeCustomer: !!org.stripe_customer_id,
+    };
+  }
+
+  // ─── Invoice / ACH Billing (Admin) ──────────────────────────
+
+  /**
+   * Switch a customer's subscription to invoice collection (ACH/wire).
+   * Admin-only operation for enterprise customers.
+   */
+  async switchToInvoiceBilling(
+    orgId: string,
+    collectionMethod: 'charge_automatically' | 'send_invoice',
+    daysUntilDue: number = 30,
+  ): Promise<void> {
+    if (!this.stripe) throw new BadRequestException('Stripe not configured');
+
+    const rows = await this.dataSource.query(
+      `SELECT stripe_subscription_id, stripe_customer_id FROM shared.organizations WHERE id = $1`,
+      [orgId],
+    );
+    if (rows.length === 0 || !rows[0].stripe_subscription_id) {
+      throw new BadRequestException('No Stripe subscription found for this organization');
+    }
+
+    const updateParams: Stripe.SubscriptionUpdateParams = {
+      collection_method: collectionMethod,
+    };
+    if (collectionMethod === 'send_invoice') {
+      updateParams.days_until_due = daysUntilDue;
+    }
+
+    await this.stripe.subscriptions.update(rows[0].stripe_subscription_id, updateParams);
+
+    // Update DB
+    await this.dataSource.query(
+      `UPDATE shared.organizations SET collection_method = $1, updated_at = NOW() WHERE id = $2`,
+      [collectionMethod, orgId],
+    );
+
+    this.logger.log(`Billing method updated for org ${orgId}: ${collectionMethod}`);
+  }
+
+  // ─── Webhook Handlers ──────────────────────────────────────
 
   private async handleCheckoutCompleted(session: Stripe.Checkout.Session): Promise<void> {
     const customerId = session.customer as string;
@@ -165,11 +434,27 @@ export class BillingService {
     const email = session.customer_email || session.customer_details?.email || '';
     const planId = session.metadata?.plan_id || 'starter';
     const businessName = session.metadata?.business_name || 'My HOA';
+    const billingInterval = (session.metadata?.billing_interval || 'month') as BillingInterval;
 
     this.logger.log(`Provisioning org for ${email}, plan=${planId}, customer=${customerId}`);
 
     try {
-      await this.provisionOrganization(customerId, subscriptionId, email, planId, businessName);
+      // Determine if this is a trial checkout (card required for trial)
+      let status: 'active' | 'trial' = 'active';
+      let trialEnd: Date | undefined;
+
+      if (this.stripe && subscriptionId) {
+        const sub = await this.stripe.subscriptions.retrieve(subscriptionId);
+        if (sub.status === 'trialing' && sub.trial_end) {
+          status = 'trial';
+          trialEnd = new Date(sub.trial_end * 1000);
+        }
+      }
+
+      await this.provisionOrganization(
+        customerId, subscriptionId, email, planId, businessName,
+        status, billingInterval, trialEnd,
+      );
     } catch (err: any) {
       this.logger.error(`Provisioning failed: ${err.message}`, err.stack);
     }
@@ -177,10 +462,10 @@ export class BillingService {
 
   private async handlePaymentSucceeded(invoice: Stripe.Invoice): Promise<void> {
     const customerId = invoice.customer as string;
-    // Activate tenant if it was pending
+    // Activate tenant if it was pending/trial
     await this.dataSource.query(
       `UPDATE shared.organizations SET status = 'active', updated_at = NOW()
-       WHERE stripe_customer_id = $1 AND status != 'active'`,
+       WHERE stripe_customer_id = $1 AND status IN ('trial', 'past_due')`,
       [customerId],
     );
   }
@@ -188,9 +473,17 @@ export class BillingService {
   private async handlePaymentFailed(invoice: Stripe.Invoice): Promise<void> {
     const customerId = invoice.customer as string;
     const rows = await this.dataSource.query(
-      `SELECT email FROM shared.organizations WHERE stripe_customer_id = $1`,
+      `SELECT email, name FROM shared.organizations WHERE stripe_customer_id = $1`,
       [customerId],
     );
+
+    // Set org to past_due for grace period (read-only access)
+    await this.dataSource.query(
+      `UPDATE shared.organizations SET status = 'past_due', updated_at = NOW()
+       WHERE stripe_customer_id = $1 AND status = 'active'`,
+      [customerId],
+    );
+
     if (rows.length > 0 && rows[0].email) {
       await this.emailService.sendPaymentFailedEmail(rows[0].email, rows[0].name || 'Your organization');
     }
@@ -207,6 +500,91 @@ export class BillingService {
     this.logger.log(`Subscription cancelled for customer ${customerId}`);
   }
 
+  private async handleTrialWillEnd(subscription: Stripe.Subscription): Promise<void> {
+    const customerId = subscription.customer as string;
+    const rows = await this.dataSource.query(
+      `SELECT id, email, name FROM shared.organizations WHERE stripe_customer_id = $1`,
+      [customerId],
+    );
+
+    if (rows.length === 0) return;
+
+    const org = rows[0];
+    const daysRemaining = 3; // This webhook fires 3 days before trial end
+    const settingsUrl = `${this.getAppUrl()}/settings`;
+
+    if (org.email) {
+      await this.emailService.sendTrialEndingEmail(
+        org.email,
+        org.name || 'Your organization',
+        daysRemaining,
+        settingsUrl,
+      );
+    }
+
+    this.logger.log(`Trial ending soon for customer ${customerId}, org ${org.id}`);
+  }
+
+  private async handleSubscriptionUpdated(subscription: Stripe.Subscription): Promise<void> {
+    const customerId = subscription.customer as string;
+
+    // Determine new status
+    let newStatus: string;
+    switch (subscription.status) {
+      case 'trialing':
+        newStatus = 'trial';
+        break;
+      case 'active':
+        newStatus = 'active';
+        break;
+      case 'past_due':
+        newStatus = 'past_due';
+        break;
+      case 'canceled':
+      case 'unpaid':
+        newStatus = 'archived';
+        break;
+      default:
+        return; // Don't update for other statuses
+    }
+
+    // Determine billing interval from the subscription items
+    let billingInterval: BillingInterval = 'month';
+    if (subscription.items?.data?.[0]?.price?.recurring?.interval === 'year') {
+      billingInterval = 'year';
+    }
+
+    // Determine plan from price metadata or existing mapping
+    let planId: string | null = null;
+    const activePriceId = subscription.items?.data?.[0]?.price?.id;
+    if (activePriceId) {
+      for (const [plan, prices] of Object.entries(this.priceMap)) {
+        if (prices.monthly === activePriceId || prices.annual === activePriceId) {
+          planId = plan;
+          break;
+        }
+      }
+    }
+
+    // Build update query dynamically
+    const updates: string[] = [`status = '${newStatus}'`, `billing_interval = '${billingInterval}'`, `updated_at = NOW()`];
+    if (planId) {
+      updates.push(`plan_level = '${planId}'`);
+    }
+    if (subscription.collection_method) {
+      updates.push(`collection_method = '${subscription.collection_method}'`);
+    }
+
+    await this.dataSource.query(
+      `UPDATE shared.organizations SET ${updates.join(', ')} WHERE stripe_customer_id = $1`,
+      [customerId],
+    );
+
+    this.logger.log(`Subscription updated for customer ${customerId}: status=${newStatus}, interval=${billingInterval}`);
+  }
+
+  // ─── Provisioning ──────────────────────────────────────────
+
   /**
    * Full provisioning flow: create org, schema, user, invite token, email.
    */
@@ -216,20 +594,26 @@ export class BillingService {
     email: string,
     planId: string,
     businessName: string,
+    status: 'active' | 'trial' = 'active',
+    billingInterval: BillingInterval = 'month',
+    trialEndsAt?: Date,
   ): Promise<void> {
     // 1. Create or upsert organization
     const schemaName = `tenant_${uuid().replace(/-/g, '').substring(0, 12)}`;
 
     const orgRows = await this.dataSource.query(
-      `INSERT INTO shared.organizations (name, schema_name, status, plan_level, stripe_customer_id, stripe_subscription_id, email)
-       VALUES ($1, $2, 'active', $3, $4, $5, $6)
+      `INSERT INTO shared.organizations
+         (name, schema_name, status, plan_level, stripe_customer_id, stripe_subscription_id, email, billing_interval, trial_ends_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
        ON CONFLICT (stripe_customer_id) DO UPDATE SET
          stripe_subscription_id = EXCLUDED.stripe_subscription_id,
          plan_level = EXCLUDED.plan_level,
-         status = 'active',
+         status = EXCLUDED.status,
+         billing_interval = EXCLUDED.billing_interval,
+         trial_ends_at = EXCLUDED.trial_ends_at,
          updated_at = NOW()
        RETURNING id, schema_name`,
-      [businessName, schemaName, planId, customerId, subscriptionId, email],
+      [businessName, schemaName, status, planId, customerId, subscriptionId, email, billingInterval, trialEndsAt || null],
     );
 
     const orgId = orgRows[0].id;
@@ -285,7 +669,7 @@ export class BillingService {
       [orgId],
     );
 
-    this.logger.log(`✅ Provisioning complete for org=${orgId}, user=${userId}`);
+    this.logger.log(`Provisioning complete for org=${orgId}, user=${userId}, status=${status}`);
   }
 
   private getAppUrl(): string {

backend/src/modules/board-planning/board-planning-projection.service.ts

@@ -25,12 +25,15 @@ export class BoardPlanningProjectionService {
     return this.computeProjection(scenarioId);
   }
 
-  /** Compute full projection for a scenario. */
+  /** Compute full projection for a scenario. Also auto-creates renewal records for auto_renew investments. */
   async computeProjection(scenarioId: string) {
     const scenarioRows = await this.tenant.query('SELECT * FROM board_scenarios WHERE id = $1', [scenarioId]);
     if (!scenarioRows.length) throw new NotFoundException('Scenario not found');
     const scenario = scenarioRows[0];
 
+    // Auto-create renewal investment records for auto_renew investments that have maturity dates
+    await this.ensureRenewalRecords(scenarioId);
+
     const investments = await this.tenant.query(
       'SELECT * FROM scenario_investments WHERE scenario_id = $1 ORDER BY purchase_date', [scenarioId],
     );
@@ -152,6 +155,53 @@ export class BoardPlanningProjectionService {
 
   // ── Private Helpers ──
 
+  /**
+   * For each auto_renew investment with a maturity_date, ensure a corresponding
+   * renewal investment record exists (starting at maturity_date, same term).
+   * The renewal record has auto_renew=false so it won't create infinite chains.
+   */
+  private async ensureRenewalRecords(scenarioId: string) {
+    const autoRenewInvestments = await this.tenant.query(
+      `SELECT * FROM scenario_investments
+       WHERE scenario_id = $1 AND auto_renew = true AND maturity_date IS NOT NULL AND executed_investment_id IS NULL`,
+      [scenarioId],
+    );
+
+    for (const inv of autoRenewInvestments) {
+      // Check if a renewal record already exists (linked by notes convention or same label pattern)
+      const renewalLabel = `${inv.label} (Renewal)`;
+      const existing = await this.tenant.query(
+        `SELECT id FROM scenario_investments WHERE scenario_id = $1 AND label = $2 AND purchase_date = $3`,
+        [scenarioId, renewalLabel, inv.maturity_date],
+      );
+
+      if (existing.length > 0) continue; // Already created
+
+      // Compute new maturity date from original term
+      let newMaturityDate: string | null = null;
+      const termMonths = parseInt(inv.term_months) || 0;
+      if (termMonths > 0 && inv.maturity_date) {
+        const d = new Date(inv.maturity_date);
+        d.setMonth(d.getMonth() + termMonths);
+        newMaturityDate = d.toISOString().split('T')[0];
+      }
+
+      await this.tenant.query(
+        `INSERT INTO scenario_investments
+          (scenario_id, label, investment_type, fund_type, principal, interest_rate,
+           term_months, institution, purchase_date, maturity_date, auto_renew, notes, sort_order)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, false, $11, $12)`,
+        [
+          scenarioId, renewalLabel, inv.investment_type, inv.fund_type,
+          inv.principal, inv.interest_rate, inv.term_months || null,
+          inv.institution, inv.maturity_date, newMaturityDate,
+          `Auto-created renewal of "${inv.label}". Modify as needed.`,
+          (parseInt(inv.sort_order) || 0) + 1,
+        ],
+      );
+    }
+  }
+
   private async getBaselineState(startYear: number, months: number) {
     // Current balances from asset accounts
     const opCashRows = await this.tenant.query(`
@@ -403,11 +453,9 @@ export class BoardPlanningProjectionService {
           if (isOp) { opCashFlow += maturityTotal; opInvChange -= principal; }
           else { resCashFlow += maturityTotal; resInvChange -= principal; }
 
-          // Auto-renew: immediately reinvest
-          if (inv.auto_renew) {
-            if (isOp) { opCashFlow -= principal; opInvChange += principal; }
-            else { resCashFlow -= principal; resInvChange += principal; }
-          }
+          // Note: auto_renew investments now create separate renewal records
+          // (via ensureRenewalRecords), so the renewal purchase is handled by
+          // that record's purchase_date logic above — no inline reinvest needed.
         }
       }
     }

backend/src/modules/board-planning/board-planning.controller.ts

@@ -3,6 +3,7 @@ import { Response } from 'express';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { AllowViewer } from '../../common/decorators/allow-viewer.decorator';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { BoardPlanningService } from './board-planning.service';
 import { BoardPlanningProjectionService } from './board-planning-projection.service';
 import { BudgetPlanningService } from './budget-planning.service';
@@ -22,27 +23,32 @@ export class BoardPlanningController {
 
   @Get('scenarios')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   listScenarios(@Query('type') type?: string) {
     return this.service.listScenarios(type);
   }
 
   @Get('scenarios/:id')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   getScenario(@Param('id') id: string) {
     return this.service.getScenario(id);
   }
 
   @Post('scenarios')
+  @RequireCapability('planning.scenarios.edit')
   createScenario(@Body() dto: any, @Req() req: any) {
     return this.service.createScenario(dto, req.user.sub);
   }
 
   @Put('scenarios/:id')
+  @RequireCapability('planning.scenarios.edit')
   updateScenario(@Param('id') id: string, @Body() dto: any) {
     return this.service.updateScenario(id, dto);
   }
 
   @Delete('scenarios/:id')
+  @RequireCapability('planning.scenarios.edit')
   deleteScenario(@Param('id') id: string) {
     return this.service.deleteScenario(id);
   }
@@ -51,26 +57,31 @@ export class BoardPlanningController {
 
   @Get('scenarios/:scenarioId/investments')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   listInvestments(@Param('scenarioId') scenarioId: string) {
     return this.service.listInvestments(scenarioId);
   }
 
   @Post('scenarios/:scenarioId/investments')
+  @RequireCapability('planning.scenarios.edit')
   addInvestment(@Param('scenarioId') scenarioId: string, @Body() dto: any) {
     return this.service.addInvestment(scenarioId, dto);
   }
 
   @Post('scenarios/:scenarioId/investments/from-recommendation')
+  @RequireCapability('planning.scenarios.edit')
   addFromRecommendation(@Param('scenarioId') scenarioId: string, @Body() dto: any) {
     return this.service.addInvestmentFromRecommendation(scenarioId, dto);
   }
 
   @Put('investments/:id')
+  @RequireCapability('planning.scenarios.edit')
   updateInvestment(@Param('id') id: string, @Body() dto: any) {
     return this.service.updateInvestment(id, dto);
   }
 
   @Delete('investments/:id')
+  @RequireCapability('planning.scenarios.edit')
   removeInvestment(@Param('id') id: string) {
     return this.service.removeInvestment(id);
   }
@@ -79,21 +90,25 @@ export class BoardPlanningController {
 
   @Get('scenarios/:scenarioId/assessments')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   listAssessments(@Param('scenarioId') scenarioId: string) {
     return this.service.listAssessments(scenarioId);
   }
 
   @Post('scenarios/:scenarioId/assessments')
+  @RequireCapability('planning.scenarios.edit')
   addAssessment(@Param('scenarioId') scenarioId: string, @Body() dto: any) {
     return this.service.addAssessment(scenarioId, dto);
   }
 
   @Put('assessments/:id')
+  @RequireCapability('planning.scenarios.edit')
   updateAssessment(@Param('id') id: string, @Body() dto: any) {
     return this.service.updateAssessment(id, dto);
   }
 
   @Delete('assessments/:id')
+  @RequireCapability('planning.scenarios.edit')
   removeAssessment(@Param('id') id: string) {
     return this.service.removeAssessment(id);
   }
@@ -102,11 +117,13 @@ export class BoardPlanningController {
 
   @Get('scenarios/:id/projection')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   getProjection(@Param('id') id: string) {
     return this.projection.getProjection(id);
   }
 
   @Post('scenarios/:id/projection/refresh')
+  @RequireCapability('planning.scenarios.edit')
   refreshProjection(@Param('id') id: string) {
     return this.projection.computeProjection(id);
   }
@@ -115,6 +132,7 @@ export class BoardPlanningController {
 
   @Get('compare')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   compareScenarios(@Query('ids') ids: string) {
     const scenarioIds = ids.split(',').map((s) => s.trim()).filter(Boolean);
     return this.projection.compareScenarios(scenarioIds);
@@ -123,6 +141,7 @@ export class BoardPlanningController {
   // ── Execute Investment ──
 
   @Post('investments/:id/execute')
+  @RequireCapability('planning.scenarios.edit')
   executeInvestment(
     @Param('id') id: string,
     @Body() dto: { executionDate: string },
@@ -135,43 +154,51 @@ export class BoardPlanningController {
 
   @Get('budget-plans')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   listBudgetPlans() {
     return this.budgetPlanning.listPlans();
   }
 
   @Get('budget-plans/available-years')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   getAvailableYears() {
     return this.budgetPlanning.getAvailableYears();
   }
 
   @Get('budget-plans/:year')
   @AllowViewer()
+  @RequireCapability('planning.scenarios.view')
   getBudgetPlan(@Param('year') year: string) {
     return this.budgetPlanning.getPlan(parseInt(year, 10));
   }
 
   @Post('budget-plans')
+  @RequireCapability('planning.scenarios.edit')
   createBudgetPlan(@Body() dto: { fiscalYear: number; baseYear: number; inflationRate?: number }, @Req() req: any) {
     return this.budgetPlanning.createPlan(dto.fiscalYear, dto.baseYear, dto.inflationRate ?? 2.5, req.user.sub);
   }
 
   @Put('budget-plans/:year/lines')
+  @RequireCapability('planning.scenarios.edit')
   updateBudgetPlanLines(@Param('year') year: string, @Body() dto: { planId: string; lines: any[] }) {
     return this.budgetPlanning.updateLines(dto.planId, dto.lines);
   }
 
   @Put('budget-plans/:year/inflation')
+  @RequireCapability('planning.scenarios.edit')
   updateBudgetPlanInflation(@Param('year') year: string, @Body() dto: { inflationRate: number }) {
     return this.budgetPlanning.updateInflation(parseInt(year, 10), dto.inflationRate);
   }
 
   @Put('budget-plans/:year/status')
+  @RequireCapability('planning.scenarios.edit')
   advanceBudgetPlanStatus(@Param('year') year: string, @Body() dto: { status: string }, @Req() req: any) {
     return this.budgetPlanning.advanceStatus(parseInt(year, 10), dto.status, req.user.sub);
   }
 
   @Post('budget-plans/:year/import')
+  @RequireCapability('planning.scenarios.edit')
   importBudgetPlanLines(
     @Param('year') year: string,
     @Body() lines: any[],
@@ -181,6 +208,7 @@ export class BoardPlanningController {
   }
 
   @Get('budget-plans/:year/template')
+  @RequireCapability('planning.scenarios.view')
   async getBudgetPlanTemplate(
     @Param('year') year: string,
     @Res() res: Response,
@@ -194,6 +222,7 @@ export class BoardPlanningController {
   }
 
   @Delete('budget-plans/:year')
+  @RequireCapability('planning.scenarios.edit')
   deleteBudgetPlan(@Param('year') year: string) {
     return this.budgetPlanning.deletePlan(parseInt(year, 10));
   }

backend/src/modules/budgets/budgets.controller.ts

@@ -2,6 +2,7 @@ import { Controller, Get, Put, Post, Body, Param, Query, Res, UseGuards, ParseIn
 import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
 import { Response } from 'express';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { BudgetsService } from './budgets.service';
 import { UpsertBudgetDto } from './dto/upsert-budget.dto';
 
@@ -14,6 +15,7 @@ export class BudgetsController {
 
   @Post(':year/import')
   @ApiOperation({ summary: 'Import budget data from parsed CSV/XLSX lines' })
+  @RequireCapability('financials.budgets.edit')
   importBudget(
     @Param('year', ParseIntPipe) year: number,
     @Body() lines: any[],
@@ -23,6 +25,7 @@ export class BudgetsController {
 
   @Get(':year/template')
   @ApiOperation({ summary: 'Download budget CSV template for a fiscal year' })
+  @RequireCapability('financials.budgets.view')
   async getTemplate(
     @Param('year', ParseIntPipe) year: number,
     @Res() res: Response,
@@ -37,6 +40,7 @@ export class BudgetsController {
 
   @Get(':year/vs-actual')
   @ApiOperation({ summary: 'Budget vs actual comparison' })
+  @RequireCapability('financials.budgets.view')
   budgetVsActual(
     @Param('year', ParseIntPipe) year: number,
     @Query('month') month?: string,
@@ -46,12 +50,14 @@ export class BudgetsController {
 
   @Get(':year')
   @ApiOperation({ summary: 'Get budgets for a fiscal year' })
+  @RequireCapability('financials.budgets.view')
   findByYear(@Param('year', ParseIntPipe) year: number) {
     return this.budgetsService.findByYear(year);
   }
 
   @Put(':year')
   @ApiOperation({ summary: 'Upsert budgets for a fiscal year' })
+  @RequireCapability('financials.budgets.edit')
   upsert(
     @Param('year', ParseIntPipe) year: number,
     @Body() budgets: UpsertBudgetDto[],

backend/src/modules/capital-projects/capital-projects.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Put, Body, Param, UseGuards } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { CapitalProjectsService } from './capital-projects.service';
 
 @ApiTags('capital-projects')
@@ -11,14 +12,18 @@ export class CapitalProjectsController {
   constructor(private service: CapitalProjectsService) {}
 
   @Get()
+  @RequireCapability('planning.projects.view')
   findAll() { return this.service.findAll(); }
 
   @Get(':id')
+  @RequireCapability('planning.projects.view')
   findOne(@Param('id') id: string) { return this.service.findOne(id); }
 
   @Post()
+  @RequireCapability('planning.projects.edit')
   create(@Body() dto: any) { return this.service.create(dto); }
 
   @Put(':id')
+  @RequireCapability('planning.projects.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.service.update(id, dto); }
 }

backend/src/modules/email/email.service.ts

@@ -96,6 +96,65 @@ export class EmailService {
     await this.send(email, subject, html, 'invite_member', { orgName, inviteUrl });
   }
 
+  async sendTrialEndingEmail(email: string, businessName: string, daysRemaining: number, settingsUrl: string): Promise<void> {
+    const subject = `Your free trial ends in ${daysRemaining} days — ${businessName}`;
+    const html = this.buildTemplate({
+      preheader: `Your HOA LedgerIQ trial for ${businessName} is ending soon.`,
+      heading: `Your Trial Ends in ${daysRemaining} Days`,
+      body: `
+        <p>Your free trial for <strong>${this.esc(businessName)}</strong> on HOA LedgerIQ ends in <strong>${daysRemaining} days</strong>.</p>
+        <p>To continue using all features without interruption, add a payment method before your trial expires.</p>
+        <p>If you don't add a payment method, your account will become read-only and you won't be able to make changes to your data.</p>
+      `,
+      ctaText: 'Add Payment Method',
+      ctaUrl: settingsUrl,
+      footer: 'If you have any questions about plans or pricing, just reply to this email.',
+    });
+
+    await this.send(email, subject, html, 'trial_ending', { businessName, daysRemaining, settingsUrl });
+  }
+
+  async sendTrialExpiredEmail(email: string, businessName: string): Promise<void> {
+    const appUrl = this.configService.get<string>('APP_URL') || 'https://app.hoaledgeriq.com';
+    const subject = `Your free trial has ended — ${businessName}`;
+    const html = this.buildTemplate({
+      preheader: `Your HOA LedgerIQ trial for ${businessName} has ended.`,
+      heading: 'Your Trial Has Ended',
+      body: `
+        <p>The free trial for <strong>${this.esc(businessName)}</strong> on HOA LedgerIQ has ended.</p>
+        <p>Your data is safe and your account is preserved. Subscribe to a plan to regain full access to your HOA financial management tools.</p>
+      `,
+      ctaText: 'Choose a Plan',
+      ctaUrl: `${appUrl}/pricing`,
+      footer: 'Your data will be preserved. You can reactivate your account at any time by subscribing to a plan.',
+    });
+
+    await this.send(email, subject, html, 'trial_expired', { businessName });
+  }
+
+  async sendNewMemberWelcomeEmail(
+    email: string,
+    firstName: string,
+    orgName: string,
+  ): Promise<void> {
+    const appUrl = this.configService.get<string>('APP_URL') || 'https://app.hoaledgeriq.com';
+    const subject = `Welcome to ${orgName} on HOA LedgerIQ`;
+    const html = this.buildTemplate({
+      preheader: `Your account for ${orgName} on HOA LedgerIQ is ready.`,
+      heading: `Welcome, ${this.esc(firstName)}!`,
+      body: `
+        <p>You've been added as a member of <strong>${this.esc(orgName)}</strong> on HOA LedgerIQ.</p>
+        <p>Your account is ready to use. Log in with your email address and the temporary password provided by your administrator. You'll be able to change your password after logging in.</p>
+        <p>HOA LedgerIQ gives you access to your community's financial dashboard, budgets, reports, and more.</p>
+      `,
+      ctaText: 'Log In Now',
+      ctaUrl: `${appUrl}/login`,
+      footer: 'If you were not expecting this email, please contact your HOA administrator.',
+    });
+
+    await this.send(email, subject, html, 'new_member_welcome', { orgName, firstName });
+  }
+
   async sendPasswordResetEmail(email: string, resetUrl: string): Promise<void> {
     const subject = 'Reset your HOA LedgerIQ password';
     const html = this.buildTemplate({

backend/src/modules/health-scores/health-scores.module.ts

@@ -6,5 +6,6 @@ import { HealthScoresScheduler } from './health-scores.scheduler';
 @Module({
   controllers: [HealthScoresController],
   providers: [HealthScoresService, HealthScoresScheduler],
+  exports: [HealthScoresService],
 })
 export class HealthScoresModule {}

backend/src/modules/health-scores/health-scores.service.ts

@@ -180,7 +180,7 @@ export class HealthScoresService {
 
   // ── Data Readiness Checks ──
 
-  private async checkDataReadiness(qr: any, scoreType: string): Promise<string[]> {
+  async checkDataReadiness(qr: any, scoreType: string): Promise<string[]> {
     const missing: string[] = [];
 
     if (scoreType === 'operating') {
@@ -249,7 +249,7 @@ export class HealthScoresService {
 
   // ── Data Gathering ──
 
-  private async gatherOperatingData(qr: any) {
+  async gatherOperatingData(qr: any) {
     const year = new Date().getFullYear();
 
     const [accounts, budgets, assessments, cashFlow, recentTransactions, actualsMonths] = await Promise.all([
@@ -520,7 +520,7 @@ export class HealthScoresService {
     };
   }
 
-  private async gatherReserveData(qr: any) {
+  async gatherReserveData(qr: any) {
     const year = new Date().getFullYear();
     const currentMonth = new Date().getMonth(); // 0-indexed
     const monthNames = ['jan','feb','mar','apr','may','jun','jul','aug','sep','oct','nov','dec_amt'];
@@ -625,14 +625,16 @@ export class HealthScoresService {
       .filter((b: any) => b.account_type === 'expense')
       .reduce((s: number, b: any) => s + parseFloat(b.annual_total || '0'), 0);
 
-    // Components needing replacement within 5 years — use whichever source has data
-    const urgentComponents = useComponentsTable
-      ? reserveComponents.filter(
-          (c: any) => c.remaining_life_years !== null && parseFloat(c.remaining_life_years) <= 5,
-        )
-      : reserveProjects.filter(
-          (p: any) => p.remaining_life_years !== null && parseFloat(p.remaining_life_years) <= 5,
-        );
+    // Projects due within 5 years — based on planned date (target_year/target_month),
+    // NOT remaining_life_years. The planned date is the board's decision on when to act;
+    // remaining life is documentation-only reference info.
+    const now = new Date();
+    const fiveYearsFromNow = new Date(now.getFullYear() + 5, now.getMonth(), 1);
+    const urgentProjects = reserveProjects.filter((p: any) => {
+      if (!p.target_year) return false;
+      const targetDate = new Date(parseInt(p.target_year), (parseInt(p.target_month) || 6) - 1, 1);
+      return targetDate <= fiveYearsFromNow;
+    });
 
     // ── Build 12-month forward reserve cash flow projection ──
 
@@ -773,7 +775,7 @@ export class HealthScoresService {
       totalProjectCost,
       annualReserveContribution,
       annualReserveExpenses,
-      urgentComponents,
+      urgentProjects,
       monthlySpecialAssessmentIncome,
       year,
       forecast,
@@ -785,7 +787,7 @@ export class HealthScoresService {
 
   // ── AI Prompt Construction ──
 
-  private buildOperatingPrompt(data: any): Array<{ role: string; content: string }> {
+  buildOperatingPrompt(data: any): Array<{ role: string; content: string }> {
     const today = new Date().toISOString().split('T')[0];
 
     const systemPrompt = `You are an HOA financial health analyst. You evaluate the operating fund health of homeowners associations on a scale of 0-100.
@@ -925,7 +927,7 @@ Projected Year-End Cash: $${data.projectedYearEndCash.toFixed(0)}`;
     ];
   }
 
-  private buildReservePrompt(data: any): Array<{ role: string; content: string }> {
+  buildReservePrompt(data: any): Array<{ role: string; content: string }> {
     const today = new Date().toISOString().split('T')[0];
 
     const systemPrompt = `You are an HOA reserve fund analyst. You evaluate reserve fund health on a scale of 0-100, assessing whether the HOA is adequately prepared for future capital expenditures.
@@ -940,12 +942,13 @@ SCORING GUIDELINES:
 
 KEY FACTORS TO EVALUATE:
 1. Percent funded (total reserve assets vs total replacement costs)
-2. Annual contribution adequacy (is annual contribution enough to keep pace with aging components?)
-3. Component urgency (components due within 5 years and their funding status)
-4. Capital project readiness (are planned projects adequately funded?)
+2. Annual contribution adequacy (is annual contribution enough to keep pace with planned projects?)
+3. Project urgency — based ONLY on the "Planned Date" field. The Planned Date is the board's decision on when a project will be executed. Do NOT use "Useful Life" or "Remaining Life" to determine urgency — those are reference information only. A project is only urgent if its Planned Date falls within the next 1-3 years.
+4. Capital project readiness (are planned projects adequately funded by their planned dates?)
 5. Investment strategy (are reserves earning returns through CDs, money markets, etc.?)
-6. Diversity of reserve components (is the full building covered?)
+6. Diversity of reserve components (is the full scope of community infrastructure tracked?)
 7. CRITICAL — Projected cash flow: Use the 12-MONTH RESERVE CASH FLOW FORECAST to assess future liquidity. The forecast shows month-by-month projected income (from special assessments collected from homeowners AND budgeted reserve income), expenses, capital project costs, and investment maturities returning cash. Check whether the reserve fund will have sufficient liquidity when capital projects are due. If special assessment income arrives before project costs, the position may be adequate even if current cash seems low.
+8. IMPORTANT — Projects with no Planned Date or with "Not scheduled" should be noted but NOT treated as urgent or imminent. Only assess urgency for projects with actual planned dates.
 
 RESPONSE FORMAT:
 Respond with ONLY valid JSON (no markdown, no code fences):
@@ -974,7 +977,8 @@ Provide 3-5 factors and 1-3 actionable recommendations. Be specific with dollar
           `- ${i.name} | ${i.investment_type} @ ${i.institution} | $${parseFloat(i.current_value || i.principal || '0').toFixed(2)} | Rate: ${parseFloat(i.interest_rate || '0').toFixed(2)}% | Maturity: ${i.maturity_date ? new Date(i.maturity_date).toLocaleDateString() : 'N/A'}`,
         ).join('\n');
 
-    // Build component lines from reserve_components if available, otherwise from reserve-funded projects
+    // Build component lines from reserve_components if available, otherwise from reserve-funded projects.
+    // Use planned date (target_year/target_month) as the authoritative timeline, not remaining_life_years.
     const componentSource = data.reserveComponents.length > 0 ? data.reserveComponents : data.reserveProjects;
     const componentLines = componentSource.length === 0
       ? 'No reserve components or reserve projects tracked.'
@@ -982,7 +986,8 @@ Provide 3-5 factors and 1-3 actionable recommendations. Be specific with dollar
           const cost = parseFloat(c.replacement_cost || c.estimated_cost || '0');
           const funded = parseFloat(c.current_fund_balance || '0');
           const pct = cost > 0 ? ((funded / cost) * 100).toFixed(0) : '0';
-          return `- ${c.name} [${c.category || 'N/A'}] | Life: ${c.useful_life_years || '?'}yr, Remaining: ${c.remaining_life_years || '?'}yr | Cost: $${cost.toFixed(0)} | Funded: $${funded.toFixed(0)} (${pct}%) | Condition: ${c.condition_rating || '?'}/10 | Annual Contribution: $${parseFloat(c.annual_contribution || '0').toFixed(0)}`;
+          const plannedDate = c.target_year ? `${c.target_year}/${c.target_month || '?'}` : 'Not scheduled';
+          return `- ${c.name} [${c.category || 'N/A'}] | Planned Date: ${plannedDate} | Useful Life: ${c.useful_life_years || '?'}yr (reference only) | Cost: $${cost.toFixed(0)} | Funded: $${funded.toFixed(0)} (${pct}%) | Condition: ${c.condition_rating || '?'}/10 | Annual Contribution: $${parseFloat(c.annual_contribution || '0').toFixed(0)}`;
         }).join('\n');
 
     const projectLines = data.projects.length === 0
@@ -995,13 +1000,14 @@ Provide 3-5 factors and 1-3 actionable recommendations. Be specific with dollar
       .map((b: any) => `- ${b.name} (${b.account_number}) [${b.account_type}]: $${parseFloat(b.annual_total || '0').toFixed(2)}/yr`)
       .join('\n') || 'No reserve budget line items.';
 
-    const urgentLines = data.urgentComponents.length === 0
-      ? 'None — no components due within 5 years.'
-      : data.urgentComponents.map((c: any) => {
-          const cost = parseFloat(c.replacement_cost || c.estimated_cost || '0');
-          const funded = parseFloat(c.current_fund_balance || '0');
+    const urgentLines = data.urgentProjects.length === 0
+      ? 'None — no reserve projects planned within 5 years.'
+      : data.urgentProjects.map((p: any) => {
+          const cost = parseFloat(p.estimated_cost || '0');
+          const funded = parseFloat(p.current_fund_balance || '0');
           const gap = cost - funded;
-          return `- ${c.name}: ${c.remaining_life_years} years remaining, $${gap.toFixed(0)} funding gap`;
+          const targetDate = `${p.target_year}/${p.target_month || '?'}`;
+          return `- ${p.name}: planned for ${targetDate}, Cost: $${cost.toFixed(0)}, $${gap.toFixed(0)} funding gap`;
         }).join('\n');
 
     const userPrompt = `Evaluate this HOA's reserve fund health.
@@ -1027,10 +1033,10 @@ ${accountLines}
 === RESERVE INVESTMENTS ===
 ${investmentLines}
 
-=== RESERVE COMPONENTS (ordered by urgency) ===
+=== RESERVE COMPONENTS (ordered by planned date) ===
 ${componentLines}
 
-=== COMPONENTS DUE WITHIN 5 YEARS (URGENT) ===
+=== PROJECTS PLANNED WITHIN 5 YEARS (by planned date) ===
 ${urgentLines}
 
 === CAPITAL PROJECTS ===

backend/src/modules/ideas/dto/create-idea.dto.ts

@@ -0,0 +1,12 @@
+import { IsString, IsNotEmpty, IsOptional, MaxLength } from 'class-validator';
+
+export class CreateIdeaDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  title: string;
+
+  @IsString()
+  @IsOptional()
+  description?: string;
+}

backend/src/modules/ideas/entities/idea.entity.ts

@@ -0,0 +1,49 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
+import { Organization } from '../../organizations/entities/organization.entity';
+import { User } from '../../users/entities/user.entity';
+
+@Entity({ schema: 'shared', name: 'ideas' })
+export class Idea {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ name: 'org_id' })
+  orgId: string;
+
+  @Column({ name: 'user_id' })
+  userId: string;
+
+  @Column({ length: 255 })
+  title: string;
+
+  @Column({ type: 'text', nullable: true })
+  description: string;
+
+  @Column({ length: 20, default: 'new' })
+  status: string;
+
+  @Column({ name: 'admin_note', type: 'text', nullable: true })
+  adminNote: string;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ name: 'updated_at', type: 'timestamptz' })
+  updatedAt: Date;
+
+  @ManyToOne(() => Organization)
+  @JoinColumn({ name: 'org_id' })
+  organization: Organization;
+
+  @ManyToOne(() => User)
+  @JoinColumn({ name: 'user_id' })
+  user: User;
+}

backend/src/modules/ideas/ideas.controller.ts

@@ -0,0 +1,27 @@
+import { Controller, Get, Post, Body, Req, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { IdeasService } from './ideas.service';
+import { CreateIdeaDto } from './dto/create-idea.dto';
+
+@ApiTags('ideas')
+@Controller('ideas')
+@ApiBearerAuth()
+@UseGuards(JwtAuthGuard)
+export class IdeasController {
+  constructor(private ideasService: IdeasService) {}
+
+  @Post()
+  async create(@Req() req: any, @Body() dto: CreateIdeaDto) {
+    const orgId = req.user.orgId;
+    const userId = req.user.userId || req.user.sub;
+    const idea = await this.ideasService.create(orgId, userId, dto);
+    return { success: true, idea };
+  }
+
+  @Get()
+  async findByOrg(@Req() req: any) {
+    const orgId = req.user.orgId;
+    return this.ideasService.findByOrg(orgId);
+  }
+}

backend/src/modules/ideas/ideas.module.ts

@@ -0,0 +1,14 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { Idea } from './entities/idea.entity';
+import { Organization } from '../organizations/entities/organization.entity';
+import { IdeasController } from './ideas.controller';
+import { IdeasService } from './ideas.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([Idea, Organization])],
+  controllers: [IdeasController],
+  providers: [IdeasService],
+  exports: [IdeasService],
+})
+export class IdeasModule {}

backend/src/modules/ideas/ideas.service.ts

@@ -0,0 +1,89 @@
+import { Injectable, ForbiddenException, NotFoundException, BadRequestException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { Idea } from './entities/idea.entity';
+import { Organization } from '../organizations/entities/organization.entity';
+import { CreateIdeaDto } from './dto/create-idea.dto';
+
+@Injectable()
+export class IdeasService {
+  constructor(
+    @InjectRepository(Idea)
+    private ideasRepository: Repository<Idea>,
+    @InjectRepository(Organization)
+    private orgRepository: Repository<Organization>,
+  ) {}
+
+  async create(orgId: string, userId: string, dto: CreateIdeaDto): Promise<Idea> {
+    const org = await this.orgRepository.findOne({ where: { id: orgId } });
+    if (!org) {
+      throw new NotFoundException('Organization not found');
+    }
+    if (org.settings?.ideationEnabled !== true) {
+      throw new ForbiddenException('Ideation is not enabled for this organization');
+    }
+
+    const idea = this.ideasRepository.create({
+      orgId,
+      userId,
+      title: dto.title,
+      description: dto.description,
+    });
+    return this.ideasRepository.save(idea);
+  }
+
+  async findByOrg(orgId: string): Promise<Idea[]> {
+    return this.ideasRepository.find({
+      where: { orgId },
+      order: { createdAt: 'DESC' },
+    });
+  }
+
+  async findAll(): Promise<any[]> {
+    return this.ideasRepository
+      .createQueryBuilder('idea')
+      .leftJoin('idea.organization', 'org')
+      .leftJoin('idea.user', 'user')
+      .select([
+        'idea.id AS id',
+        'idea.title AS title',
+        'idea.description AS description',
+        'idea.status AS status',
+        'idea.createdAt AS "createdAt"',
+        'idea.adminNote AS "adminNote"',
+        'org.id AS "orgId"',
+        'org.name AS "orgName"',
+        'user.id AS "userId"',
+        'user.email AS "userEmail"',
+        'user.firstName AS "userFirstName"',
+        'user.lastName AS "userLastName"',
+      ])
+      .orderBy('idea.createdAt', 'DESC')
+      .getRawMany();
+  }
+
+  async updateStatus(id: string, status: string): Promise<Idea> {
+    const validStatuses = ['new', 'reviewed', 'accepted', 'rejected'];
+    if (!validStatuses.includes(status)) {
+      throw new BadRequestException(`Invalid status. Must be one of: ${validStatuses.join(', ')}`);
+    }
+
+    const idea = await this.ideasRepository.findOne({ where: { id } });
+    if (!idea) {
+      throw new NotFoundException('Idea not found');
+    }
+
+    idea.status = status;
+    return this.ideasRepository.save(idea);
+  }
+
+  async updateNote(id: string, adminNote: string): Promise<Idea> {
+    const idea = await this.ideasRepository.findOne({ where: { id } });
+    if (!idea) {
+      throw new NotFoundException('Idea not found');
+    }
+
+    idea.adminNote = adminNote;
+    return this.ideasRepository.save(idea);
+  }
+}

backend/src/modules/investment-planning/investment-planning.controller.ts

@@ -2,6 +2,7 @@ import { Controller, Get, Post, UseGuards, Req } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { AllowViewer } from '../../common/decorators/allow-viewer.decorator';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { InvestmentPlanningService } from './investment-planning.service';
 
 @ApiTags('investment-planning')
@@ -13,24 +14,28 @@ export class InvestmentPlanningController {
 
   @Get('snapshot')
   @ApiOperation({ summary: 'Get financial snapshot for investment planning' })
+  @RequireCapability('planning.investments.view')
   getSnapshot() {
     return this.service.getFinancialSnapshot();
   }
 
   @Get('cd-rates')
   @ApiOperation({ summary: 'Get latest CD rates from market data (backward compat)' })
+  @RequireCapability('planning.investments.view')
   getCdRates() {
     return this.service.getCdRates();
   }
 
   @Get('market-rates')
   @ApiOperation({ summary: 'Get all market rates grouped by type (CD, Money Market, High Yield Savings)' })
+  @RequireCapability('planning.investments.view')
   getMarketRates() {
     return this.service.getMarketRates();
   }
 
   @Get('saved-recommendation')
   @ApiOperation({ summary: 'Get the latest saved AI recommendation for this tenant' })
+  @RequireCapability('planning.investments.view')
   getSavedRecommendation() {
     return this.service.getSavedRecommendation();
   }
@@ -38,6 +43,7 @@ export class InvestmentPlanningController {
   @Post('recommendations')
   @ApiOperation({ summary: 'Trigger AI-powered investment recommendations (async — returns immediately)' })
   @AllowViewer()
+  @RequireCapability('planning.investments.edit')
   triggerRecommendations(@Req() req: any) {
     return this.service.triggerAIRecommendations(req.user?.sub, req.user?.orgId);
   }

backend/src/modules/investment-planning/investment-planning.module.ts

@@ -5,5 +5,6 @@ import { InvestmentPlanningService } from './investment-planning.service';
 @Module({
   controllers: [InvestmentPlanningController],
   providers: [InvestmentPlanningService],
+  exports: [InvestmentPlanningService],
 })
 export class InvestmentPlanningModule {}

backend/src/modules/investment-planning/investment-planning.service.ts

@@ -877,7 +877,7 @@ export class InvestmentPlanningService {
 
   // ── Private: AI Prompt Construction ──
 
-  private buildPromptMessages(
+  buildPromptMessages(
     snapshot: any,
     allRates: { cd: MarketRate[]; money_market: MarketRate[]; high_yield_savings: MarketRate[] },
     monthlyForecast: any,
@@ -1059,6 +1059,285 @@ Based on this complete financial picture INCLUDING the 12-month cash flow foreca
     ];
   }
 
+  // ── Schema-Based Prompt Building (for shadow AI benchmarking) ──
+
+  /**
+   * Build investment recommendation prompt messages for a specific tenant schema.
+   * Bypasses request-scoped TenantService by using DataSource directly.
+   */
+  async buildPromptForSchema(schemaName: string): Promise<Array<{ role: string; content: string }>> {
+    const qr = this.dataSource.createQueryRunner();
+    try {
+      await qr.connect();
+      await qr.query(`SET search_path TO "${schemaName}"`);
+
+      const year = new Date().getFullYear();
+      const currentMonth = new Date().getMonth() + 1;
+      const monthNames = ['jan','feb','mar','apr','may','jun','jul','aug','sep','oct','nov','dec_amt'];
+      const monthLabels = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+
+      // ── Gather financial snapshot data ──
+      const [accountBalances, investmentAccounts, budgets, projects] = await Promise.all([
+        qr.query(`
+          SELECT a.id, a.account_number, a.name, a.account_type, a.fund_type, a.interest_rate,
+            CASE
+              WHEN a.account_type IN ('asset', 'expense')
+                THEN COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0)
+              ELSE COALESCE(SUM(jel.credit), 0) - COALESCE(SUM(jel.debit), 0)
+            END as balance
+          FROM accounts a
+          LEFT JOIN journal_entry_lines jel ON jel.account_id = a.id
+          LEFT JOIN journal_entries je ON je.id = jel.journal_entry_id
+            AND je.is_posted = true AND je.is_void = false
+          WHERE a.is_active = true AND a.account_type IN ('asset', 'liability', 'equity')
+          GROUP BY a.id, a.account_number, a.name, a.account_type, a.fund_type, a.interest_rate
+          ORDER BY a.account_number
+        `),
+        qr.query(`
+          SELECT id, name, institution, investment_type, fund_type,
+            principal, interest_rate, maturity_date, purchase_date, current_value
+          FROM investment_accounts WHERE is_active = true
+          ORDER BY maturity_date NULLS LAST
+        `),
+        qr.query(
+          `SELECT b.fund_type, a.account_type, a.name, a.account_number,
+            (b.jan + b.feb + b.mar + b.apr + b.may + b.jun +
+             b.jul + b.aug + b.sep + b.oct + b.nov + b.dec_amt) as annual_total
+           FROM budgets b JOIN accounts a ON a.id = b.account_id
+           WHERE b.fiscal_year = $1 ORDER BY a.account_type, a.account_number`,
+          [year],
+        ),
+        qr.query(`
+          SELECT name, estimated_cost, target_year, target_month, fund_source,
+            status, priority, current_fund_balance, funded_percentage
+          FROM projects WHERE is_active = true AND status IN ('planned', 'approved', 'in_progress')
+          ORDER BY target_year, target_month NULLS LAST, priority
+        `),
+      ]);
+
+      // Cash flow context
+      const [opCashResult, resCashResult, assessmentIncome] = await Promise.all([
+        qr.query(`
+          SELECT COALESCE(SUM(sub.bal), 0) as total FROM (
+            SELECT COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0) as bal
+            FROM accounts a
+            JOIN journal_entry_lines jel ON jel.account_id = a.id
+            JOIN journal_entries je ON je.id = jel.journal_entry_id AND je.is_posted = true AND je.is_void = false
+            WHERE a.account_type = 'asset' AND a.fund_type = 'operating' AND a.is_active = true
+            GROUP BY a.id
+          ) sub
+        `),
+        qr.query(`
+          SELECT COALESCE(SUM(sub.bal), 0) as total FROM (
+            SELECT COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0) as bal
+            FROM accounts a
+            JOIN journal_entry_lines jel ON jel.account_id = a.id
+            JOIN journal_entries je ON je.id = jel.journal_entry_id AND je.is_posted = true AND je.is_void = false
+            WHERE a.account_type = 'asset' AND a.fund_type = 'reserve' AND a.is_active = true
+            GROUP BY a.id
+          ) sub
+        `),
+        qr.query(`
+          SELECT COALESCE(SUM(ag.regular_assessment *
+            (SELECT COUNT(*) FROM units u WHERE u.assessment_group_id = ag.id AND u.status = 'active')), 0) as monthly_assessment_income
+          FROM assessment_groups ag WHERE ag.is_active = true
+        `),
+      ]);
+
+      const operatingCash = accountBalances
+        .filter((a: any) => a.fund_type === 'operating' && a.account_type === 'asset')
+        .reduce((sum: number, a: any) => sum + parseFloat(a.balance || '0'), 0);
+      const reserveCash = accountBalances
+        .filter((a: any) => a.fund_type === 'reserve' && a.account_type === 'asset')
+        .reduce((sum: number, a: any) => sum + parseFloat(a.balance || '0'), 0);
+      const operatingInvestments = investmentAccounts
+        .filter((i: any) => i.fund_type === 'operating')
+        .reduce((sum: number, i: any) => sum + parseFloat(i.current_value || i.principal || '0'), 0);
+      const reserveInvestments = investmentAccounts
+        .filter((i: any) => i.fund_type === 'reserve')
+        .reduce((sum: number, i: any) => sum + parseFloat(i.current_value || i.principal || '0'), 0);
+
+      const snapshot = {
+        summary: {
+          operating_cash: operatingCash,
+          reserve_cash: reserveCash,
+          operating_investments: operatingInvestments,
+          reserve_investments: reserveInvestments,
+          total_operating: operatingCash + operatingInvestments,
+          total_reserve: reserveCash + reserveInvestments,
+          total_all: operatingCash + reserveCash + operatingInvestments + reserveInvestments,
+        },
+        account_balances: accountBalances,
+        investment_accounts: investmentAccounts,
+        budgets,
+        projects,
+        cash_flow_context: {
+          current_operating_cash: parseFloat(opCashResult[0]?.total || '0'),
+          current_reserve_cash: parseFloat(resCashResult[0]?.total || '0'),
+          budget_summary: await qr.query(
+            `SELECT b.fund_type, a.account_type,
+              SUM(b.jan + b.feb + b.mar + b.apr + b.may + b.jun +
+                  b.jul + b.aug + b.sep + b.oct + b.nov + b.dec_amt) as annual_total
+             FROM budgets b JOIN accounts a ON a.id = b.account_id
+             WHERE b.fiscal_year = $1 GROUP BY b.fund_type, a.account_type`,
+            [year],
+          ),
+          monthly_assessment_income: parseFloat(assessmentIncome[0]?.monthly_assessment_income || '0'),
+        },
+      };
+
+      // ── Build monthly forecast ──
+      const [opCashRows2, resCashRows2, opInvRows, resInvRows] = await Promise.all([
+        qr.query(`SELECT COALESCE(SUM(sub.bal), 0) as total FROM (
+          SELECT COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0) as bal
+          FROM accounts a JOIN journal_entry_lines jel ON jel.account_id = a.id
+          JOIN journal_entries je ON je.id = jel.journal_entry_id AND je.is_posted = true AND je.is_void = false
+          WHERE a.account_type = 'asset' AND a.fund_type = 'operating' AND a.is_active = true GROUP BY a.id
+        ) sub`),
+        qr.query(`SELECT COALESCE(SUM(sub.bal), 0) as total FROM (
+          SELECT COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0) as bal
+          FROM accounts a JOIN journal_entry_lines jel ON jel.account_id = a.id
+          JOIN journal_entries je ON je.id = jel.journal_entry_id AND je.is_posted = true AND je.is_void = false
+          WHERE a.account_type = 'asset' AND a.fund_type = 'reserve' AND a.is_active = true GROUP BY a.id
+        ) sub`),
+        qr.query(`SELECT COALESCE(SUM(current_value), 0) as total FROM investment_accounts WHERE fund_type = 'operating' AND is_active = true`),
+        qr.query(`SELECT COALESCE(SUM(current_value), 0) as total FROM investment_accounts WHERE fund_type = 'reserve' AND is_active = true`),
+      ]);
+
+      let runOpCash = parseFloat(opCashRows2[0]?.total || '0');
+      let runResCash = parseFloat(resCashRows2[0]?.total || '0');
+      let runOpInv = parseFloat(opInvRows[0]?.total || '0');
+      let runResInv = parseFloat(resInvRows[0]?.total || '0');
+
+      const assessmentGroups = await qr.query(`
+        SELECT ag.frequency, ag.regular_assessment, ag.special_assessment,
+          (SELECT COUNT(*) FROM units u WHERE u.assessment_group_id = ag.id AND u.status = 'active') as unit_count
+        FROM assessment_groups ag WHERE ag.is_active = true
+      `);
+
+      const getAssessmentIncome = (month: number): { operating: number; reserve: number } => {
+        let operating = 0, reserve = 0;
+        for (const g of assessmentGroups) {
+          const units = parseInt(g.unit_count) || 0;
+          const regular = parseFloat(g.regular_assessment) || 0;
+          const special = parseFloat(g.special_assessment) || 0;
+          const freq = g.frequency || 'monthly';
+          let applies = false;
+          if (freq === 'monthly') applies = true;
+          else if (freq === 'quarterly') applies = [1,4,7,10].includes(month);
+          else if (freq === 'annual') applies = month === 1;
+          if (applies) { operating += regular * units; reserve += special * units; }
+        }
+        return { operating, reserve };
+      };
+
+      const budgetsByYearMonth: Record<string, { opIncome: number; opExpense: number; resIncome: number; resExpense: number }> = {};
+      for (const yr of [year, year + 1]) {
+        const budgetRows = await qr.query(
+          `SELECT b.fund_type, a.account_type,
+            b.jan, b.feb, b.mar, b.apr, b.may, b.jun, b.jul, b.aug, b.sep, b.oct, b.nov, b.dec_amt
+          FROM budgets b JOIN accounts a ON a.id = b.account_id WHERE b.fiscal_year = $1`, [yr],
+        );
+        for (let m = 0; m < 12; m++) {
+          const key = `${yr}-${m + 1}`;
+          if (!budgetsByYearMonth[key]) budgetsByYearMonth[key] = { opIncome: 0, opExpense: 0, resIncome: 0, resExpense: 0 };
+          for (const row of budgetRows) {
+            const amt = parseFloat(row[monthNames[m]]) || 0;
+            if (amt === 0) continue;
+            const isOp = row.fund_type === 'operating';
+            if (row.account_type === 'income') { if (isOp) budgetsByYearMonth[key].opIncome += amt; else budgetsByYearMonth[key].resIncome += amt; }
+            else if (row.account_type === 'expense') { if (isOp) budgetsByYearMonth[key].opExpense += amt; else budgetsByYearMonth[key].resExpense += amt; }
+          }
+        }
+      }
+
+      const maturities = await qr.query(`
+        SELECT fund_type, current_value, maturity_date, interest_rate, purchase_date
+        FROM investment_accounts WHERE is_active = true AND maturity_date IS NOT NULL AND maturity_date > CURRENT_DATE
+      `);
+      const maturityIndex: Record<string, { operating: number; reserve: number }> = {};
+      for (const inv of maturities) {
+        const d = new Date(inv.maturity_date);
+        const key = `${d.getFullYear()}-${d.getMonth() + 1}`;
+        if (!maturityIndex[key]) maturityIndex[key] = { operating: 0, reserve: 0 };
+        const val = parseFloat(inv.current_value) || 0;
+        const rate = parseFloat(inv.interest_rate) || 0;
+        const purchaseDate = inv.purchase_date ? new Date(inv.purchase_date) : new Date();
+        const matDate = new Date(inv.maturity_date);
+        const daysHeld = Math.max((matDate.getTime() - purchaseDate.getTime()) / 86400000, 1);
+        const interestEarned = val * (rate / 100) * (daysHeld / 365);
+        const maturityTotal = val + interestEarned;
+        if (inv.fund_type === 'operating') maturityIndex[key].operating += maturityTotal;
+        else maturityIndex[key].reserve += maturityTotal;
+      }
+
+      const projectExpenses = await qr.query(`
+        SELECT estimated_cost, target_year, target_month, fund_source
+        FROM projects WHERE is_active = true AND status IN ('planned', 'in_progress')
+          AND target_year IS NOT NULL AND estimated_cost > 0
+      `);
+      const projectIndex: Record<string, { operating: number; reserve: number }> = {};
+      for (const p of projectExpenses) {
+        const yr2 = parseInt(p.target_year);
+        const mo = parseInt(p.target_month) || 6;
+        const key = `${yr2}-${mo}`;
+        if (!projectIndex[key]) projectIndex[key] = { operating: 0, reserve: 0 };
+        const cost = parseFloat(p.estimated_cost) || 0;
+        if (p.fund_source === 'operating') projectIndex[key].operating += cost;
+        else projectIndex[key].reserve += cost;
+      }
+
+      const datapoints: any[] = [];
+      for (let i = 0; i < 12; i++) {
+        const fYear = year + Math.floor((currentMonth - 1 + i) / 12);
+        const fMonth = ((currentMonth - 1 + i) % 12) + 1;
+        const key = `${fYear}-${fMonth}`;
+        const label = `${monthLabels[fMonth - 1]} ${fYear}`;
+        const assessments = getAssessmentIncome(fMonth);
+        const budget = budgetsByYearMonth[key] || { opIncome: 0, opExpense: 0, resIncome: 0, resExpense: 0 };
+        const maturity = maturityIndex[key] || { operating: 0, reserve: 0 };
+        const project = projectIndex[key] || { operating: 0, reserve: 0 };
+        const opIncomeMonth = budget.opIncome > 0 ? budget.opIncome : assessments.operating;
+        const resIncomeMonth = budget.resIncome > 0 ? budget.resIncome : assessments.reserve;
+        runOpCash += opIncomeMonth - budget.opExpense - project.operating + maturity.operating;
+        runResCash += resIncomeMonth - budget.resExpense - project.reserve + maturity.reserve;
+        if (maturity.operating > 0) runOpInv = Math.max(0, runOpInv - (maturity.operating * 0.96));
+        if (maturity.reserve > 0) runResInv = Math.max(0, runResInv - (maturity.reserve * 0.96));
+        datapoints.push({
+          month: label,
+          operating_cash: Math.round(runOpCash * 100) / 100,
+          operating_investments: Math.round(runOpInv * 100) / 100,
+          reserve_cash: Math.round(runResCash * 100) / 100,
+          reserve_investments: Math.round(runResInv * 100) / 100,
+          op_income: Math.round(opIncomeMonth * 100) / 100,
+          op_expense: Math.round(budget.opExpense * 100) / 100,
+          res_income: Math.round(resIncomeMonth * 100) / 100,
+          res_expense: Math.round(budget.resExpense * 100) / 100,
+          project_cost_op: Math.round(project.operating * 100) / 100,
+          project_cost_res: Math.round(project.reserve * 100) / 100,
+          maturity_op: Math.round(maturity.operating * 100) / 100,
+          maturity_res: Math.round(maturity.reserve * 100) / 100,
+        });
+      }
+
+      const assessmentSchedule = assessmentGroups.map((g: any) => ({
+        frequency: g.frequency || 'monthly',
+        regular_per_unit: parseFloat(g.regular_assessment) || 0,
+        special_per_unit: parseFloat(g.special_assessment) || 0,
+        units: parseInt(g.unit_count) || 0,
+        total_regular: (parseFloat(g.regular_assessment) || 0) * (parseInt(g.unit_count) || 0),
+        total_special: (parseFloat(g.special_assessment) || 0) * (parseInt(g.unit_count) || 0),
+      }));
+
+      const monthlyForecast = { datapoints, assessment_schedule: assessmentSchedule };
+      const allRates = await this.getMarketRates();
+
+      return this.buildPromptMessages(snapshot, allRates, monthlyForecast);
+    } finally {
+      await qr.release();
+    }
+  }
+
   // ── Private: AI API Call ──
 
   private async callAI(messages: Array<{ role: string; content: string }>): Promise<AIResponse> {

backend/src/modules/investments/investments.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Put, Body, Param, UseGuards } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { InvestmentsService } from './investments.service';
 
 @ApiTags('investments')
@@ -11,14 +12,18 @@ export class InvestmentsController {
   constructor(private service: InvestmentsService) {}
 
   @Get()
+  @RequireCapability('planning.investments.view')
   findAll() { return this.service.findAll(); }
 
   @Get(':id')
+  @RequireCapability('planning.investments.view')
   findOne(@Param('id') id: string) { return this.service.findOne(id); }
 
   @Post()
+  @RequireCapability('planning.investments.edit')
   create(@Body() dto: any) { return this.service.create(dto); }
 
   @Put(':id')
+  @RequireCapability('planning.investments.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.service.update(id, dto); }
 }

backend/src/modules/invoices/invoices.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Body, Param, UseGuards, Request } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { InvoicesService } from './invoices.service';
 
 @ApiTags('invoices')
@@ -11,22 +12,27 @@ export class InvoicesController {
   constructor(private invoicesService: InvoicesService) {}
 
   @Get()
+  @RequireCapability('transactions.view')
   findAll() { return this.invoicesService.findAll(); }
 
   @Get(':id')
+  @RequireCapability('transactions.view')
   findOne(@Param('id') id: string) { return this.invoicesService.findOne(id); }
 
   @Post('generate-preview')
+  @RequireCapability('transactions.edit')
   generatePreview(@Body() dto: { month: number; year: number }) {
     return this.invoicesService.generatePreview(dto);
   }
 
   @Post('generate-bulk')
+  @RequireCapability('transactions.edit')
   generateBulk(@Body() dto: { month: number; year: number }, @Request() req: any) {
     return this.invoicesService.generateBulk(dto, req.user.sub);
   }
 
   @Post('apply-late-fees')
+  @RequireCapability('transactions.edit')
   applyLateFees(@Body() dto: { grace_period_days: number; late_fee_amount: number }, @Request() req: any) {
     return this.invoicesService.applyLateFees(dto, req.user.sub);
   }

backend/src/modules/journal-entries/journal-entries.controller.ts

@@ -3,6 +3,7 @@ import {
 } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { JournalEntriesService } from './journal-entries.service';
 import { CreateJournalEntryDto } from './dto/create-journal-entry.dto';
 import { VoidJournalEntryDto } from './dto/void-journal-entry.dto';
@@ -16,6 +17,7 @@ export class JournalEntriesController {
 
   @Get()
   @ApiOperation({ summary: 'List journal entries' })
+  @RequireCapability('transactions.view')
   findAll(
     @Query('from') from?: string,
     @Query('to') to?: string,
@@ -27,24 +29,28 @@ export class JournalEntriesController {
 
   @Get(':id')
   @ApiOperation({ summary: 'Get journal entry by ID' })
+  @RequireCapability('transactions.view')
   findOne(@Param('id') id: string) {
     return this.jeService.findOne(id);
   }
 
   @Post()
   @ApiOperation({ summary: 'Create a journal entry' })
+  @RequireCapability('transactions.edit')
   create(@Body() dto: CreateJournalEntryDto, @Request() req: any) {
     return this.jeService.create(dto, req.user.sub);
   }
 
   @Post(':id/post')
   @ApiOperation({ summary: 'Post (finalize) a journal entry' })
+  @RequireCapability('transactions.edit')
   post(@Param('id') id: string, @Request() req: any) {
     return this.jeService.post(id, req.user.sub);
   }
 
   @Post(':id/void')
   @ApiOperation({ summary: 'Void a journal entry' })
+  @RequireCapability('transactions.edit')
   void(@Param('id') id: string, @Body() dto: VoidJournalEntryDto, @Request() req: any) {
     return this.jeService.void(id, req.user.sub, dto.reason);
   }

backend/src/modules/monthly-actuals/monthly-actuals.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Param, Body, UseGuards, Request } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { MonthlyActualsService } from './monthly-actuals.service';
 
 @ApiTags('monthly-actuals')
@@ -12,12 +13,14 @@ export class MonthlyActualsController {
 
   @Get(':year/:month')
   @ApiOperation({ summary: 'Get monthly actuals grid for a specific month' })
+  @RequireCapability('financials.actuals.view')
   async getGrid(@Param('year') year: string, @Param('month') month: string) {
     return this.monthlyActualsService.getActualsGrid(parseInt(year), parseInt(month));
   }
 
   @Post(':year/:month')
   @ApiOperation({ summary: 'Save monthly actuals (creates reconciled journal entry)' })
+  @RequireCapability('financials.actuals.edit')
   async save(
     @Param('year') year: string,
     @Param('month') month: string,

backend/src/modules/organizations/organizations.controller.ts

@@ -3,6 +3,8 @@ import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
 import { OrganizationsService } from './organizations.service';
 import { CreateOrganizationDto } from './dto/create-organization.dto';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
+import { resolveCapabilitiesArray, ALL_CAPABILITIES } from '../../common/permissions';
 
 @ApiTags('organizations')
 @Controller('organizations')
@@ -23,54 +25,87 @@ export class OrganizationsController {
     return this.orgService.findByUser(req.user.sub);
   }
 
+  @Get('my-capabilities')
+  @ApiOperation({ summary: 'Get resolved capabilities for current user in current org' })
+  async getMyCapabilities(@Request() req: any) {
+    const org = await this.orgService.findById(req.user.orgId);
+    const settings = org?.settings || {};
+    const capabilities = resolveCapabilitiesArray(req.user.role, settings.permissionOverrides);
+    return { role: req.user.role, capabilities };
+  }
+
   @Patch('settings')
   @ApiOperation({ summary: 'Update settings for the current organization' })
+  @RequireCapability('settings.org.edit')
   async updateSettings(@Request() req: any, @Body() body: Record<string, any>) {
-    this.requireTenantAdmin(req);
+    // Validate permissionOverrides if present
+    if (body.permissionOverrides) {
+      this.validatePermissionOverrides(body.permissionOverrides);
+    }
     return this.orgService.updateSettings(req.user.orgId, body);
   }
 
   // ── Org Member Management ──
 
-  private requireTenantAdmin(req: any) {
-    const role = req.user.role;
-    if (!['president', 'admin', 'treasurer'].includes(role) && !req.user.isSuperadmin) {
-      throw new ForbiddenException('Only organization administrators can manage members');
-    }
-  }
-
   @Get('members')
   @ApiOperation({ summary: 'List members of current organization' })
+  @RequireCapability('settings.members.view')
   async getMembers(@Request() req: any) {
-    this.requireTenantAdmin(req);
     return this.orgService.getMembers(req.user.orgId);
   }
 
   @Post('members')
   @ApiOperation({ summary: 'Add a member to the current organization' })
+  @RequireCapability('settings.members.manage')
   async addMember(
     @Request() req: any,
     @Body() body: { email: string; firstName: string; lastName: string; password: string; role: string },
   ) {
-    this.requireTenantAdmin(req);
     return this.orgService.addMember(req.user.orgId, body);
   }
 
   @Put('members/:id/role')
   @ApiOperation({ summary: 'Update a member role' })
+  @RequireCapability('settings.members.manage')
   async updateMemberRole(
     @Request() req: any,
     @Param('id') id: string,
     @Body() body: { role: string },
   ) {
-    this.requireTenantAdmin(req);
     return this.orgService.updateMemberRole(req.user.orgId, id, body.role);
   }
 
   @Delete('members/:id')
   @ApiOperation({ summary: 'Remove a member from the organization' })
+  @RequireCapability('settings.members.manage')
   async removeMember(@Request() req: any, @Param('id') id: string) {
-    this.requireTenantAdmin(req);
     return this.orgService.removeMember(req.user.orgId, id, req.user.sub);
   }
+
+  private validatePermissionOverrides(overrides: any) {
+    if (typeof overrides !== 'object' || overrides === null) {
+      throw new ForbiddenException('permissionOverrides must be an object');
+    }
+    const validRoles = ['president', 'vice_president', 'treasurer', 'secretary', 'member_at_large', 'manager', 'homeowner', 'admin', 'viewer'];
+    for (const role of Object.keys(overrides)) {
+      if (!validRoles.includes(role)) {
+        throw new ForbiddenException(`Invalid role in permissionOverrides: ${role}`);
+      }
+      const entry = overrides[role];
+      if (entry.grant) {
+        for (const cap of entry.grant) {
+          if (!ALL_CAPABILITIES.has(cap)) {
+            throw new ForbiddenException(`Unknown capability in grant: ${cap}`);
+          }
+        }
+      }
+      if (entry.revoke) {
+        for (const cap of entry.revoke) {
+          if (!ALL_CAPABILITIES.has(cap)) {
+            throw new ForbiddenException(`Unknown capability in revoke: ${cap}`);
+          }
+        }
+      }
+    }
+  }
 }

backend/src/modules/organizations/organizations.service.ts

@@ -1,20 +1,24 @@
-import { Injectable, ConflictException, BadRequestException, NotFoundException } from '@nestjs/common';
+import { Injectable, ConflictException, BadRequestException, NotFoundException, Logger } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 import { Organization } from './entities/organization.entity';
 import { UserOrganization } from './entities/user-organization.entity';
 import { TenantSchemaService } from '../../database/tenant-schema.service';
 import { CreateOrganizationDto } from './dto/create-organization.dto';
+import { EmailService } from '../email/email.service';
 import * as bcrypt from 'bcryptjs';
 
 @Injectable()
 export class OrganizationsService {
+  private readonly logger = new Logger(OrganizationsService.name);
+
   constructor(
     @InjectRepository(Organization)
     private orgRepository: Repository<Organization>,
     @InjectRepository(UserOrganization)
     private userOrgRepository: Repository<UserOrganization>,
     private tenantSchemaService: TenantSchemaService,
+    private emailService: EmailService,
   ) {}
 
   async create(dto: CreateOrganizationDto, userId: string) {
@@ -124,12 +128,29 @@ export class OrganizationsService {
     return rows;
   }
 
+  private static readonly MEMBER_LIMIT_PLANS = ['starter', 'standard', 'professional'];
+  private static readonly MAX_MEMBERS = 5;
+
   async addMember(
     orgId: string,
     data: { email: string; firstName: string; lastName: string; password: string; role: string },
   ) {
     const dataSource = this.orgRepository.manager.connection;
 
+    // Enforce member limit for starter and professional plans
+    const org = await this.orgRepository.findOne({ where: { id: orgId } });
+    const planLevel = org?.planLevel || 'starter';
+    if (OrganizationsService.MEMBER_LIMIT_PLANS.includes(planLevel)) {
+      const activeMemberCount = await this.userOrgRepository.count({
+        where: { organizationId: orgId, isActive: true },
+      });
+      if (activeMemberCount >= OrganizationsService.MAX_MEMBERS) {
+        throw new BadRequestException(
+          `Your ${planLevel === 'starter' ? 'Starter' : 'Professional'} plan is limited to ${OrganizationsService.MAX_MEMBERS} user accounts. Please upgrade to Enterprise for unlimited members.`,
+        );
+      }
+    }
+
     // Check if user already exists
     let userRows = await dataSource.query(
       `SELECT id FROM shared.users WHERE email = $1`,
@@ -179,7 +200,23 @@ export class OrganizationsService {
       organizationId: orgId,
       role: data.role,
     });
-    return this.userOrgRepository.save(membership);
+    const saved = await this.userOrgRepository.save(membership);
+
+    // Send welcome email to the new member
+    try {
+      const org = await this.orgRepository.findOne({ where: { id: orgId } });
+      const orgName = org?.name || 'your organization';
+      await this.emailService.sendNewMemberWelcomeEmail(
+        data.email,
+        data.firstName,
+        orgName,
+      );
+    } catch (err) {
+      this.logger.warn(`Failed to send welcome email to ${data.email}: ${err}`);
+      // Don't fail the member addition if the email fails
+    }
+
+    return saved;
   }
 
   async updateMemberRole(orgId: string, membershipId: string, role: string) {

backend/src/modules/payments/payments.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Put, Delete, Body, Param, UseGuards, Request } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { PaymentsService } from './payments.service';
 
 @ApiTags('payments')
@@ -11,19 +12,24 @@ export class PaymentsController {
   constructor(private paymentsService: PaymentsService) {}
 
   @Get()
+  @RequireCapability('transactions.view')
   findAll() { return this.paymentsService.findAll(); }
 
   @Get(':id')
+  @RequireCapability('transactions.view')
   findOne(@Param('id') id: string) { return this.paymentsService.findOne(id); }
 
   @Post()
+  @RequireCapability('transactions.edit')
   create(@Body() dto: any, @Request() req: any) { return this.paymentsService.create(dto, req.user.sub); }
 
   @Put(':id')
+  @RequireCapability('transactions.edit')
   update(@Param('id') id: string, @Body() dto: any, @Request() req: any) {
     return this.paymentsService.update(id, dto, req.user.sub);
   }
 
   @Delete(':id')
+  @RequireCapability('transactions.edit')
   delete(@Param('id') id: string) { return this.paymentsService.delete(id); }
 }

backend/src/modules/projects/projects.controller.ts

@@ -2,6 +2,7 @@ import { Controller, Get, Post, Put, Body, Param, Res, UseGuards } from '@nestjs
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { Response } from 'express';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { ProjectsService } from './projects.service';
 
 @ApiTags('projects')
@@ -12,9 +13,11 @@ export class ProjectsController {
   constructor(private service: ProjectsService) {}
 
   @Get()
+  @RequireCapability('planning.projects.view')
   findAll() { return this.service.findAll(); }
 
   @Get('export')
+  @RequireCapability('planning.projects.view')
   async exportCSV(@Res() res: Response) {
     const csv = await this.service.exportCSV();
     res.set({ 'Content-Type': 'text/csv', 'Content-Disposition': 'attachment; filename="projects.csv"' });
@@ -22,21 +25,27 @@ export class ProjectsController {
   }
 
   @Get('planning')
+  @RequireCapability('planning.projects.view')
   findForPlanning() { return this.service.findForPlanning(); }
 
   @Get(':id')
+  @RequireCapability('planning.projects.view')
   findOne(@Param('id') id: string) { return this.service.findOne(id); }
 
   @Post('import')
+  @RequireCapability('planning.projects.edit')
   importCSV(@Body() rows: any[]) { return this.service.importCSV(rows); }
 
   @Post()
+  @RequireCapability('planning.projects.edit')
   create(@Body() dto: any) { return this.service.create(dto); }
 
   @Put(':id')
+  @RequireCapability('planning.projects.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.service.update(id, dto); }
 
   @Put(':id/planned-date')
+  @RequireCapability('planning.projects.edit')
   updatePlannedDate(@Param('id') id: string, @Body() dto: { planned_date: string }) {
     return this.service.updatePlannedDate(id, dto.planned_date);
   }

backend/src/modules/reports/reports.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Query, UseGuards } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { ReportsService } from './reports.service';
 
 @ApiTags('reports')
@@ -11,11 +12,13 @@ export class ReportsController {
   constructor(private reportsService: ReportsService) {}
 
   @Get('balance-sheet')
+  @RequireCapability('reports.view')
   getBalanceSheet(@Query('as_of') asOf?: string) {
     return this.reportsService.getBalanceSheet(asOf || new Date().toISOString().split('T')[0]);
   }
 
   @Get('income-statement')
+  @RequireCapability('reports.view')
   getIncomeStatement(@Query('from') from?: string, @Query('to') to?: string) {
     const now = new Date();
     const defaultFrom = `${now.getFullYear()}-01-01`;
@@ -24,6 +27,7 @@ export class ReportsController {
   }
 
   @Get('cash-flow-sankey')
+  @RequireCapability('reports.view')
   getCashFlowSankey(
     @Query('year') year?: string,
     @Query('source') source?: string,
@@ -37,6 +41,7 @@ export class ReportsController {
   }
 
   @Get('cash-flow')
+  @RequireCapability('reports.view')
   getCashFlowStatement(
     @Query('from') from?: string,
     @Query('to') to?: string,
@@ -51,21 +56,31 @@ export class ReportsController {
   }
 
   @Get('aging')
+  @RequireCapability('reports.view')
   getAgingReport() {
     return this.reportsService.getAgingReport();
   }
 
   @Get('year-end')
+  @RequireCapability('reports.view')
   getYearEndSummary(@Query('year') year?: string) {
     return this.reportsService.getYearEndSummary(parseInt(year || '') || new Date().getFullYear());
   }
 
   @Get('dashboard')
+  @RequireCapability('reports.view')
   getDashboardKPIs() {
     return this.reportsService.getDashboardKPIs();
   }
 
+  @Get('upcoming-investment-activities')
+  @RequireCapability('reports.view')
+  getUpcomingInvestmentActivities() {
+    return this.reportsService.getUpcomingInvestmentActivities();
+  }
+
   @Get('cash-flow-forecast')
+  @RequireCapability('reports.view')
   getCashFlowForecast(
     @Query('startYear') startYear?: string,
     @Query('months') months?: string,
@@ -75,7 +90,16 @@ export class ReportsController {
     return this.reportsService.getCashFlowForecast(yr, mo);
   }
 
+  @Get('capital-planning')
+  @RequireCapability('reports.view')
+  getCapitalPlanningReport(@Query('startYear') startYear?: string) {
+    return this.reportsService.getCapitalPlanningReport(
+      parseInt(startYear || '') || undefined,
+    );
+  }
+
   @Get('quarterly')
+  @RequireCapability('reports.view')
   getQuarterlyFinancial(
     @Query('year') year?: string,
     @Query('quarter') quarter?: string,

backend/src/modules/reports/reports.service.ts

@@ -780,6 +780,78 @@ export class ReportsService {
     };
   }
 
+  async getUpcomingInvestmentActivities() {
+    const now = new Date();
+    const in45Days = new Date(now);
+    in45Days.setDate(in45Days.getDate() + 45);
+    const in60Days = new Date(now);
+    in60Days.setDate(in60Days.getDate() + 60);
+
+    // 1. Investments maturing within 45 days
+    const maturingInvestments = await this.tenant.query(`
+      SELECT id, name, institution, investment_type, fund_type, current_value, principal,
+             interest_rate, maturity_date, purchase_date
+      FROM investment_accounts
+      WHERE is_active = true
+        AND maturity_date IS NOT NULL
+        AND maturity_date BETWEEN CURRENT_DATE AND $1::date
+      ORDER BY maturity_date ASC
+    `, [in45Days.toISOString().split('T')[0]]);
+
+    // Compute interest earned and days remaining for each
+    const maturing = maturingInvestments.map((inv: any) => {
+      const principal = parseFloat(inv.principal) || parseFloat(inv.current_value) || 0;
+      const rate = parseFloat(inv.interest_rate) || 0;
+      const purchaseDate = inv.purchase_date ? new Date(inv.purchase_date) : now;
+      const maturityDate = new Date(inv.maturity_date);
+      const daysHeld = Math.max((maturityDate.getTime() - purchaseDate.getTime()) / 86400000, 1);
+      const interestEarned = principal * (rate / 100) * (daysHeld / 365);
+      const daysRemaining = Math.max(Math.ceil((maturityDate.getTime() - now.getTime()) / 86400000), 0);
+      return {
+        ...inv,
+        interest_earned: interestEarned.toFixed(2),
+        maturity_value: (principal + interestEarned).toFixed(2),
+        days_remaining: daysRemaining,
+        activity_type: 'maturity',
+      };
+    });
+
+    // 2. Approved scenario investments due to execute within 60 days
+    let scenarioItems: any[] = [];
+    try {
+      scenarioItems = await this.tenant.query(`
+        SELECT si.id, si.label, si.investment_type, si.fund_type, si.principal,
+               si.interest_rate, si.purchase_date, si.maturity_date, si.institution,
+               bs.name as scenario_name, bs.status as scenario_status
+        FROM scenario_investments si
+        JOIN board_scenarios bs ON bs.id = si.scenario_id
+        WHERE bs.status = 'approved'
+          AND si.executed_investment_id IS NULL
+          AND si.purchase_date IS NOT NULL
+          AND si.purchase_date BETWEEN CURRENT_DATE AND $1::date
+        ORDER BY si.purchase_date ASC
+      `, [in60Days.toISOString().split('T')[0]]);
+    } catch {
+      // scenario tables may not exist
+    }
+
+    const upcoming = scenarioItems.map((si: any) => {
+      const purchaseDate = new Date(si.purchase_date);
+      const daysUntil = Math.max(Math.ceil((purchaseDate.getTime() - now.getTime()) / 86400000), 0);
+      return {
+        ...si,
+        days_until: daysUntil,
+        activity_type: 'planned_purchase',
+      };
+    });
+
+    return {
+      maturing_investments: maturing,
+      upcoming_scenario_investments: upcoming,
+      total_activities: maturing.length + upcoming.length,
+    };
+  }
+
   /**
    * Cash Flow Forecast: monthly datapoints with actuals (historical) and projections (future).
    * Each month has: operating_cash, operating_investments, reserve_cash, reserve_investments.
@@ -1021,11 +1093,24 @@ export class ReportsService {
     let runOpInv = opInv;
     let runResInv = resInv;
 
+    // Determine which months have actual journal entries
+    // A month is "actual" only if it's not in the future AND has real journal entry data
+    const monthsWithActuals = new Set<string>();
+    for (const key of Object.keys(histIndex)) {
+      // histIndex keys are "year-month-fund_type", extract year-month
+      const parts = key.split('-');
+      const ym = `${parts[0]}-${parts[1]}`;
+      monthsWithActuals.add(ym);
+    }
+
     for (let i = 0; i < months; i++) {
       const year = startYear + Math.floor(i / 12);
       const month = (i % 12) + 1;
       const key = `${year}-${month}`;
-      const isHistorical = year < currentYear || (year === currentYear && month <= currentMonth);
+      // A month is historical (actual) only if it's in the past AND has journal entries
+      const isPastMonth = year < currentYear || (year === currentYear && month < currentMonth);
+      const hasActuals = monthsWithActuals.has(key);
+      const isHistorical = isPastMonth && hasActuals;
       const label = `${monthLabels[month - 1]} ${year}`;
 
       if (isHistorical) {
@@ -1251,4 +1336,120 @@ export class ReportsService {
       over_budget_items: overBudgetItems,
     };
   }
+
+  async getCapitalPlanningReport(startYear?: number) {
+    const baseYear = startYear || new Date().getFullYear();
+    const years = [baseYear, baseYear + 1, baseYear + 2, baseYear + 3, baseYear + 4];
+
+    // Get all active projects
+    const projects = await this.tenant.query(
+      `SELECT id, name, description, category, estimated_cost, target_year, target_month,
+              useful_life_years, last_replacement_date, next_replacement_date, fund_source,
+              status, priority, condition_rating
+       FROM projects
+       WHERE is_active = true
+       ORDER BY category NULLS LAST, priority, name`,
+    );
+
+    // Also try capital_projects table
+    let capitalProjects: any[] = [];
+    try {
+      capitalProjects = await this.tenant.query(
+        `SELECT id, name, description, estimated_cost, target_year, target_month,
+                fund_source, status, priority, notes
+         FROM capital_projects
+         WHERE status NOT IN ('cancelled')
+         ORDER BY priority, name`,
+      );
+    } catch {
+      // Table may not exist
+    }
+
+    // Merge and group by category
+    const allProjects = [
+      ...projects.map((p: any) => ({
+        id: p.id,
+        name: p.name,
+        description: p.description,
+        category: p.category || 'Uncategorized',
+        estimated_cost: parseFloat(p.estimated_cost) || 0,
+        target_year: parseInt(p.target_year) || null,
+        useful_life_years: parseInt(p.useful_life_years) || null,
+        last_replacement_date: p.last_replacement_date,
+        fund_source: p.fund_source || 'reserve',
+        status: p.status,
+        priority: parseInt(p.priority) || 3,
+        condition_rating: parseInt(p.condition_rating) || null,
+      })),
+      ...capitalProjects
+        .filter((cp: any) => !projects.some((p: any) => p.name === cp.name && p.target_year === cp.target_year))
+        .map((cp: any) => ({
+          id: cp.id,
+          name: cp.name,
+          description: cp.description,
+          category: 'Capital Projects',
+          estimated_cost: parseFloat(cp.estimated_cost) || 0,
+          target_year: parseInt(cp.target_year) || null,
+          useful_life_years: null,
+          last_replacement_date: null,
+          fund_source: cp.fund_source || 'reserve',
+          status: cp.status,
+          priority: parseInt(cp.priority) || 3,
+          condition_rating: null,
+        })),
+    ];
+
+    // Group by category
+    const categories: Record<string, any[]> = {};
+    for (const project of allProjects) {
+      const cat = project.category;
+      if (!categories[cat]) categories[cat] = [];
+      categories[cat].push(project);
+    }
+
+    // Build year columns for each project
+    const categoryData = Object.entries(categories).map(([category, items]) => ({
+      category,
+      projects: items.map((p) => {
+        const yearAmounts: Record<number, number> = {};
+        let beyond = 0;
+        if (p.target_year) {
+          if (p.target_year >= years[0] && p.target_year <= years[4]) {
+            yearAmounts[p.target_year] = p.estimated_cost;
+          } else if (p.target_year > years[4]) {
+            beyond = p.estimated_cost;
+          }
+        }
+        return {
+          ...p,
+          year_amounts: yearAmounts,
+          beyond,
+        };
+      }),
+    }));
+
+    // Compute totals per year
+    const yearTotals: Record<number, number> = {};
+    let beyondTotal = 0;
+    for (const y of years) yearTotals[y] = 0;
+    for (const cat of categoryData) {
+      for (const p of cat.projects) {
+        for (const y of years) {
+          yearTotals[y] += p.year_amounts[y] || 0;
+        }
+        beyondTotal += p.beyond;
+      }
+    }
+
+    return {
+      title: `${years[4] - years[0] + 1}-YEAR CAPITAL PROJECT FORECAST`,
+      start_year: years[0],
+      years,
+      categories: categoryData,
+      year_totals: yearTotals,
+      beyond_total: beyondTotal,
+      grand_total: Object.values(yearTotals).reduce((a, b) => a + b, 0) + beyondTotal,
+      generated_at: new Date().toISOString(),
+    };
+  }
 }

backend/src/modules/reserve-components/reserve-components.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Post, Put, Body, Param, UseGuards } from '@nestjs/common';
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { ReserveComponentsService } from './reserve-components.service';
 
 @ApiTags('reserve-components')
@@ -11,14 +12,18 @@ export class ReserveComponentsController {
   constructor(private service: ReserveComponentsService) {}
 
   @Get()
+  @RequireCapability('planning.projects.view')
   findAll() { return this.service.findAll(); }
 
   @Get(':id')
+  @RequireCapability('planning.projects.view')
   findOne(@Param('id') id: string) { return this.service.findOne(id); }
 
   @Post()
+  @RequireCapability('planning.projects.edit')
   create(@Body() dto: any) { return this.service.create(dto); }
 
   @Put(':id')
+  @RequireCapability('planning.projects.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.service.update(id, dto); }
 }

backend/src/modules/shadow-ai/entities/shadow-ai-model.entity.ts

@@ -0,0 +1,37 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+@Entity({ schema: 'shared', name: 'shadow_ai_models' })
+export class ShadowAiModel {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'varchar', length: 10, unique: true })
+  slot: string;
+
+  @Column({ type: 'varchar', length: 100 })
+  name: string;
+
+  @Column({ name: 'api_url', type: 'varchar', length: 500 })
+  apiUrl: string;
+
+  @Column({ name: 'api_key', type: 'varchar', length: 500 })
+  apiKey: string;
+
+  @Column({ name: 'model_name', type: 'varchar', length: 200 })
+  modelName: string;
+
+  @Column({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ name: 'updated_at', type: 'timestamptz' })
+  updatedAt: Date;
+}

backend/src/modules/shadow-ai/entities/shadow-run-result.entity.ts

@@ -0,0 +1,52 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
+import { ShadowRun } from './shadow-run.entity';
+
+@Entity({ schema: 'shared', name: 'shadow_run_results' })
+export class ShadowRunResult {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ name: 'run_id', type: 'uuid' })
+  runId: string;
+
+  @Column({ name: 'model_role', type: 'varchar', length: 20 })
+  modelRole: string;
+
+  @Column({ name: 'model_name', type: 'varchar', length: 200 })
+  modelName: string;
+
+  @Column({ name: 'api_url', type: 'varchar', length: 500 })
+  apiUrl: string;
+
+  @Column({ name: 'raw_response', type: 'text', nullable: true })
+  rawResponse: string;
+
+  @Column({ name: 'parsed_response', type: 'jsonb', nullable: true })
+  parsedResponse: any;
+
+  @Column({ name: 'response_time_ms', type: 'integer', nullable: true })
+  responseTimeMs: number;
+
+  @Column({ name: 'token_usage', type: 'jsonb', nullable: true })
+  tokenUsage: any;
+
+  @Column({ type: 'varchar', length: 20, default: 'pending' })
+  status: string;
+
+  @Column({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage: string;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  createdAt: Date;
+
+  @ManyToOne(() => ShadowRun, (run) => run.results, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'run_id' })
+  run: ShadowRun;
+}

backend/src/modules/shadow-ai/entities/shadow-run.entity.ts

@@ -0,0 +1,44 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  OneToMany,
+} from 'typeorm';
+import { ShadowRunResult } from './shadow-run-result.entity';
+
+@Entity({ schema: 'shared', name: 'shadow_runs' })
+export class ShadowRun {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ name: 'tenant_id', type: 'uuid' })
+  tenantId: string;
+
+  @Column({ type: 'varchar', length: 30 })
+  feature: string;
+
+  @Column({ type: 'varchar', length: 20, default: 'running' })
+  status: string;
+
+  @Column({ name: 'triggered_by', type: 'uuid', nullable: true })
+  triggeredBy: string;
+
+  @Column({ name: 'prompt_messages', type: 'jsonb' })
+  promptMessages: any;
+
+  @Column({ name: 'started_at', type: 'timestamptz', default: () => 'NOW()' })
+  startedAt: Date;
+
+  @Column({ name: 'completed_at', type: 'timestamptz', nullable: true })
+  completedAt: Date;
+
+  @CreateDateColumn({ name: 'created_at', type: 'timestamptz' })
+  createdAt: Date;
+
+  @OneToMany(() => ShadowRunResult, (result) => result.run, { eager: true })
+  results: ShadowRunResult[];
+
+  // Virtual field populated via JOIN
+  tenantName?: string;
+}

backend/src/modules/shadow-ai/shadow-ai.controller.ts

@@ -0,0 +1,118 @@
+import {
+  Controller,
+  Get,
+  Put,
+  Post,
+  Delete,
+  Body,
+  Param,
+  Query,
+  UseGuards,
+  Req,
+  ForbiddenException,
+  BadRequestException,
+  NotFoundException,
+} from '@nestjs/common';
+import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { UsersService } from '../users/users.service';
+import { ShadowAiService } from './shadow-ai.service';
+
+@ApiTags('admin/shadow-ai')
+@Controller('admin/shadow-ai')
+@ApiBearerAuth()
+@UseGuards(JwtAuthGuard)
+export class ShadowAiController {
+  constructor(
+    private shadowAiService: ShadowAiService,
+    private usersService: UsersService,
+  ) {}
+
+  private async requireSuperadmin(req: any) {
+    const user = await this.usersService.findById(req.user.userId || req.user.sub);
+    if (!user?.isSuperadmin) {
+      throw new ForbiddenException('Superadmin access required');
+    }
+    return user;
+  }
+
+  // ── Model Configuration ──
+
+  @Get('models')
+  async getModels(@Req() req: any) {
+    await this.requireSuperadmin(req);
+    return this.shadowAiService.getModels();
+  }
+
+  @Put('models/:slot')
+  async upsertModel(
+    @Req() req: any,
+    @Param('slot') slot: string,
+    @Body() body: { name: string; apiUrl: string; apiKey: string; modelName: string; isActive?: boolean },
+  ) {
+    await this.requireSuperadmin(req);
+    if (!['A', 'B'].includes(slot)) {
+      throw new BadRequestException('Slot must be A or B');
+    }
+    if (!body.name || !body.apiUrl || !body.apiKey || !body.modelName) {
+      throw new BadRequestException('name, apiUrl, apiKey, and modelName are required');
+    }
+    return this.shadowAiService.upsertModel(slot, body);
+  }
+
+  @Delete('models/:slot')
+  async deleteModel(@Req() req: any, @Param('slot') slot: string) {
+    await this.requireSuperadmin(req);
+    if (!['A', 'B'].includes(slot)) {
+      throw new BadRequestException('Slot must be A or B');
+    }
+    return this.shadowAiService.deleteModel(slot);
+  }
+
+  // ── Shadow Runs ──
+
+  @Post('runs')
+  async triggerRun(
+    @Req() req: any,
+    @Body() body: { tenantId: string; feature: string },
+  ) {
+    const user = await this.requireSuperadmin(req);
+    const validFeatures = ['operating_health', 'reserve_health', 'investment_recommendations'];
+    if (!validFeatures.includes(body.feature)) {
+      throw new BadRequestException(`Feature must be one of: ${validFeatures.join(', ')}`);
+    }
+    if (!body.tenantId) {
+      throw new BadRequestException('tenantId is required');
+    }
+    return this.shadowAiService.triggerRun(
+      body.tenantId,
+      body.feature as any,
+      user.id,
+    );
+  }
+
+  @Get('runs')
+  async getRunHistory(
+    @Req() req: any,
+    @Query('page') page?: string,
+    @Query('limit') limit?: string,
+    @Query('tenantId') tenantId?: string,
+    @Query('feature') feature?: string,
+  ) {
+    await this.requireSuperadmin(req);
+    return this.shadowAiService.getRunHistory({
+      page: page ? parseInt(page) : undefined,
+      limit: limit ? parseInt(limit) : undefined,
+      tenantId,
+      feature,
+    });
+  }
+
+  @Get('runs/:id')
+  async getRunDetail(@Req() req: any, @Param('id') id: string) {
+    await this.requireSuperadmin(req);
+    const detail = await this.shadowAiService.getRunDetail(id);
+    if (!detail) throw new NotFoundException('Shadow run not found');
+    return detail;
+  }
+}

backend/src/modules/shadow-ai/shadow-ai.module.ts

@@ -0,0 +1,26 @@
+import { Module, OnModuleInit } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ShadowAiController } from './shadow-ai.controller';
+import { ShadowAiService } from './shadow-ai.service';
+import { ShadowAiModel } from './entities/shadow-ai-model.entity';
+import { ShadowRun } from './entities/shadow-run.entity';
+import { ShadowRunResult } from './entities/shadow-run-result.entity';
+import { HealthScoresModule } from '../health-scores/health-scores.module';
+import { UsersModule } from '../users/users.module';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([ShadowAiModel, ShadowRun, ShadowRunResult]),
+    HealthScoresModule,
+    UsersModule,
+  ],
+  controllers: [ShadowAiController],
+  providers: [ShadowAiService],
+})
+export class ShadowAiModule implements OnModuleInit {
+  constructor(private shadowAiService: ShadowAiService) {}
+
+  async onModuleInit() {
+    await this.shadowAiService.ensureTables();
+  }
+}

backend/src/modules/shadow-ai/shadow-ai.service.ts

@@ -0,0 +1,723 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { DataSource } from 'typeorm';
+import { HealthScoresService } from '../health-scores/health-scores.service';
+import { callOpenAICompatible } from '../../common/utils/ai-caller';
+
+type Feature = 'operating_health' | 'reserve_health' | 'investment_recommendations';
+
+interface ModelConfig {
+  role: string;
+  name: string;
+  apiUrl: string;
+  apiKey: string;
+  modelName: string;
+}
+
+@Injectable()
+export class ShadowAiService {
+  private readonly logger = new Logger(ShadowAiService.name);
+
+  constructor(
+    private dataSource: DataSource,
+    private configService: ConfigService,
+    private healthScoresService: HealthScoresService,
+  ) {}
+
+  // ── Model Configuration CRUD ──
+
+  async getModels() {
+    const rows = await this.dataSource.query(
+      `SELECT id, slot, name, api_url, api_key, model_name, is_active, created_at, updated_at
+       FROM shared.shadow_ai_models ORDER BY slot`,
+    );
+    return rows.map((r: any) => ({
+      ...r,
+      api_key: r.api_key ? `****${r.api_key.slice(-4)}` : null,
+    }));
+  }
+
+  async upsertModel(slot: string, dto: { name: string; apiUrl: string; apiKey: string; modelName: string; isActive?: boolean }) {
+    const isActive = dto.isActive !== undefined ? dto.isActive : true;
+
+    // Check if model exists for this slot
+    const existing = await this.dataSource.query(
+      `SELECT id, api_key FROM shared.shadow_ai_models WHERE slot = $1`,
+      [slot],
+    );
+
+    if (existing.length > 0) {
+      // If apiKey is masked (starts with ****), keep the existing key
+      const apiKey = dto.apiKey.startsWith('****') ? existing[0].api_key : dto.apiKey;
+      await this.dataSource.query(
+        `UPDATE shared.shadow_ai_models
+         SET name = $1, api_url = $2, api_key = $3, model_name = $4, is_active = $5, updated_at = NOW()
+         WHERE slot = $6`,
+        [dto.name, dto.apiUrl, apiKey, dto.modelName, isActive, slot],
+      );
+    } else {
+      await this.dataSource.query(
+        `INSERT INTO shared.shadow_ai_models (slot, name, api_url, api_key, model_name, is_active)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [slot, dto.name, dto.apiUrl, dto.apiKey, dto.modelName, isActive],
+      );
+    }
+
+    return { slot, status: 'saved' };
+  }
+
+  async deleteModel(slot: string) {
+    await this.dataSource.query(
+      `DELETE FROM shared.shadow_ai_models WHERE slot = $1`,
+      [slot],
+    );
+    return { slot, status: 'deleted' };
+  }
+
+  // ── Shadow Run Execution ──
+
+  async triggerRun(tenantId: string, feature: Feature, userId: string) {
+    // Look up tenant schema
+    const orgs = await this.dataSource.query(
+      `SELECT schema_name, name FROM shared.organizations WHERE id = $1`,
+      [tenantId],
+    );
+    if (!orgs.length) throw new Error('Tenant not found');
+    const schemaName = orgs[0].schema_name;
+
+    // Build prompt messages for the feature
+    const messages = await this.buildPromptMessages(schemaName, feature);
+
+    // Create shadow run record
+    const runRows = await this.dataSource.query(
+      `INSERT INTO shared.shadow_runs (tenant_id, feature, status, triggered_by, prompt_messages, started_at)
+       VALUES ($1, $2, 'running', $3, $4, NOW())
+       RETURNING id`,
+      [tenantId, feature, userId, JSON.stringify(messages)],
+    );
+    const runId = runRows[0].id;
+
+    // Get model configs
+    const modelConfigs = await this.getModelConfigs();
+
+    // Create pending result rows
+    for (const config of modelConfigs) {
+      await this.dataSource.query(
+        `INSERT INTO shared.shadow_run_results (run_id, model_role, model_name, api_url, status)
+         VALUES ($1, $2, $3, $4, 'pending')`,
+        [runId, config.role, config.modelName, config.apiUrl],
+      );
+    }
+
+    // Fire-and-forget: run all models in parallel
+    this.executeModels(runId, messages, modelConfigs, feature).catch((err) => {
+      this.logger.error(`Shadow run ${runId} failed: ${err.message}`);
+    });
+
+    return { runId, status: 'running' };
+  }
+
+  // ── Run History ──
+
+  async getRunHistory(query: { page?: number; limit?: number; tenantId?: string; feature?: string }) {
+    const page = query.page || 1;
+    const limit = Math.min(query.limit || 20, 100);
+    const offset = (page - 1) * limit;
+
+    let where = '';
+    const params: any[] = [];
+    let paramIdx = 1;
+
+    if (query.tenantId) {
+      where += ` AND sr.tenant_id = $${paramIdx++}`;
+      params.push(query.tenantId);
+    }
+    if (query.feature) {
+      where += ` AND sr.feature = $${paramIdx++}`;
+      params.push(query.feature);
+    }
+
+    const [rows, countRows] = await Promise.all([
+      this.dataSource.query(
+        `SELECT sr.id, sr.tenant_id, sr.feature, sr.status, sr.started_at, sr.completed_at, sr.created_at,
+                o.name as tenant_name,
+                (SELECT COUNT(*) FROM shared.shadow_run_results rr WHERE rr.run_id = sr.id) as result_count,
+                (SELECT COUNT(*) FROM shared.shadow_run_results rr WHERE rr.run_id = sr.id AND rr.status = 'success') as success_count
+         FROM shared.shadow_runs sr
+         LEFT JOIN shared.organizations o ON o.id = sr.tenant_id
+         WHERE 1=1 ${where}
+         ORDER BY sr.created_at DESC
+         LIMIT $${paramIdx++} OFFSET $${paramIdx++}`,
+        [...params, limit, offset],
+      ),
+      this.dataSource.query(
+        `SELECT COUNT(*) as total FROM shared.shadow_runs sr WHERE 1=1 ${where}`,
+        params,
+      ),
+    ]);
+
+    return {
+      runs: rows,
+      total: parseInt(countRows[0]?.total || '0'),
+      page,
+      limit,
+    };
+  }
+
+  async getRunDetail(runId: string) {
+    const [runs, results] = await Promise.all([
+      this.dataSource.query(
+        `SELECT sr.*, o.name as tenant_name
+         FROM shared.shadow_runs sr
+         LEFT JOIN shared.organizations o ON o.id = sr.tenant_id
+         WHERE sr.id = $1`,
+        [runId],
+      ),
+      this.dataSource.query(
+        `SELECT * FROM shared.shadow_run_results
+         WHERE run_id = $1
+         ORDER BY CASE model_role
+           WHEN 'production' THEN 1
+           WHEN 'alternate_a' THEN 2
+           WHEN 'alternate_b' THEN 3
+         END`,
+        [runId],
+      ),
+    ]);
+
+    if (!runs.length) return null;
+
+    return {
+      ...runs[0],
+      results,
+    };
+  }
+
+  // ── Private Helpers ──
+
+  private async buildPromptMessages(
+    schemaName: string,
+    feature: Feature,
+  ): Promise<Array<{ role: string; content: string }>> {
+    if (feature === 'operating_health' || feature === 'reserve_health') {
+      const qr = this.dataSource.createQueryRunner();
+      try {
+        await qr.connect();
+        await qr.query(`SET search_path TO "${schemaName}"`);
+
+        const scoreType = feature === 'operating_health' ? 'operating' : 'reserve';
+        const data = scoreType === 'operating'
+          ? await this.healthScoresService.gatherOperatingData(qr)
+          : await this.healthScoresService.gatherReserveData(qr);
+
+        return scoreType === 'operating'
+          ? this.healthScoresService.buildOperatingPrompt(data)
+          : this.healthScoresService.buildReservePrompt(data);
+      } finally {
+        await qr.release();
+      }
+    }
+
+    // investment_recommendations — build prompt directly via DataSource
+    return this.buildInvestmentPromptForSchema(schemaName);
+  }
+
+  /**
+   * Build investment recommendation prompts for a given tenant schema.
+   * Self-contained: uses DataSource directly, no request-scoped dependencies.
+   */
+  private async buildInvestmentPromptForSchema(schemaName: string): Promise<Array<{ role: string; content: string }>> {
+    const qr = this.dataSource.createQueryRunner();
+    try {
+      await qr.connect();
+      await qr.query(`SET search_path TO "${schemaName}"`);
+
+      const year = new Date().getFullYear();
+      const currentMonth = new Date().getMonth() + 1;
+      const monthNames = ['jan','feb','mar','apr','may','jun','jul','aug','sep','oct','nov','dec_amt'];
+      const monthLabels = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+
+      // ── Financial snapshot ──
+      const [accountBalances, investmentAccounts, budgets, projects] = await Promise.all([
+        qr.query(`
+          SELECT a.id, a.account_number, a.name, a.account_type, a.fund_type, a.interest_rate,
+            CASE WHEN a.account_type IN ('asset', 'expense')
+              THEN COALESCE(SUM(jel.debit), 0) - COALESCE(SUM(jel.credit), 0)
+              ELSE COALESCE(SUM(jel.credit), 0) - COALESCE(SUM(jel.debit), 0)
+            END as balance
+          FROM accounts a
+          LEFT JOIN journal_entry_lines jel ON jel.account_id = a.id
+          LEFT JOIN journal_entries je ON je.id = jel.journal_entry_id AND je.is_posted = true AND je.is_void = false
+          WHERE a.is_active = true AND a.account_type IN ('asset', 'liability', 'equity')
+          GROUP BY a.id, a.account_number, a.name, a.account_type, a.fund_type, a.interest_rate ORDER BY a.account_number
+        `),
+        qr.query(`SELECT id, name, institution, investment_type, fund_type, principal, interest_rate, maturity_date, purchase_date, current_value
+          FROM investment_accounts WHERE is_active = true ORDER BY maturity_date NULLS LAST`),
+        qr.query(`SELECT b.fund_type, a.account_type, a.name, a.account_number,
+          (b.jan+b.feb+b.mar+b.apr+b.may+b.jun+b.jul+b.aug+b.sep+b.oct+b.nov+b.dec_amt) as annual_total
+          FROM budgets b JOIN accounts a ON a.id = b.account_id WHERE b.fiscal_year = $1 ORDER BY a.account_type, a.account_number`, [year]),
+        qr.query(`SELECT name, estimated_cost, target_year, target_month, fund_source, status, priority, current_fund_balance, funded_percentage
+          FROM projects WHERE is_active = true AND status IN ('planned','approved','in_progress') ORDER BY target_year, target_month NULLS LAST, priority`),
+      ]);
+
+      const [opCashResult, resCashResult, budgetSummary, assessmentIncome] = await Promise.all([
+        qr.query(`SELECT COALESCE(SUM(sub.bal),0) as total FROM (SELECT COALESCE(SUM(jel.debit),0)-COALESCE(SUM(jel.credit),0) as bal FROM accounts a JOIN journal_entry_lines jel ON jel.account_id=a.id JOIN journal_entries je ON je.id=jel.journal_entry_id AND je.is_posted=true AND je.is_void=false WHERE a.account_type='asset' AND a.fund_type='operating' AND a.is_active=true GROUP BY a.id) sub`),
+        qr.query(`SELECT COALESCE(SUM(sub.bal),0) as total FROM (SELECT COALESCE(SUM(jel.debit),0)-COALESCE(SUM(jel.credit),0) as bal FROM accounts a JOIN journal_entry_lines jel ON jel.account_id=a.id JOIN journal_entries je ON je.id=jel.journal_entry_id AND je.is_posted=true AND je.is_void=false WHERE a.account_type='asset' AND a.fund_type='reserve' AND a.is_active=true GROUP BY a.id) sub`),
+        qr.query(`SELECT b.fund_type, a.account_type, SUM(b.jan+b.feb+b.mar+b.apr+b.may+b.jun+b.jul+b.aug+b.sep+b.oct+b.nov+b.dec_amt) as annual_total FROM budgets b JOIN accounts a ON a.id=b.account_id WHERE b.fiscal_year=$1 GROUP BY b.fund_type, a.account_type`, [year]),
+        qr.query(`SELECT COALESCE(SUM(ag.regular_assessment*(SELECT COUNT(*) FROM units u WHERE u.assessment_group_id=ag.id AND u.status='active')),0) as monthly_assessment_income FROM assessment_groups ag WHERE ag.is_active=true`),
+      ]);
+
+      const operatingCash = accountBalances.filter((a: any) => a.fund_type === 'operating' && a.account_type === 'asset').reduce((s: number, a: any) => s + parseFloat(a.balance || '0'), 0);
+      const reserveCash = accountBalances.filter((a: any) => a.fund_type === 'reserve' && a.account_type === 'asset').reduce((s: number, a: any) => s + parseFloat(a.balance || '0'), 0);
+      const operatingInvestments = investmentAccounts.filter((i: any) => i.fund_type === 'operating').reduce((s: number, i: any) => s + parseFloat(i.current_value || i.principal || '0'), 0);
+      const reserveInvestments = investmentAccounts.filter((i: any) => i.fund_type === 'reserve').reduce((s: number, i: any) => s + parseFloat(i.current_value || i.principal || '0'), 0);
+
+      const snapshot = {
+        summary: { operating_cash: operatingCash, reserve_cash: reserveCash, operating_investments: operatingInvestments, reserve_investments: reserveInvestments,
+          total_operating: operatingCash + operatingInvestments, total_reserve: reserveCash + reserveInvestments, total_all: operatingCash + reserveCash + operatingInvestments + reserveInvestments },
+        account_balances: accountBalances, investment_accounts: investmentAccounts, budgets, projects,
+        cash_flow_context: {
+          current_operating_cash: parseFloat(opCashResult[0]?.total || '0'), current_reserve_cash: parseFloat(resCashResult[0]?.total || '0'),
+          budget_summary: budgetSummary, monthly_assessment_income: parseFloat(assessmentIncome[0]?.monthly_assessment_income || '0'),
+        },
+      };
+
+      // ── 12-month forecast ──
+      const [opInvRows, resInvRows] = await Promise.all([
+        qr.query(`SELECT COALESCE(SUM(current_value),0) as total FROM investment_accounts WHERE fund_type='operating' AND is_active=true`),
+        qr.query(`SELECT COALESCE(SUM(current_value),0) as total FROM investment_accounts WHERE fund_type='reserve' AND is_active=true`),
+      ]);
+      let runOpCash = parseFloat(opCashResult[0]?.total || '0'), runResCash = parseFloat(resCashResult[0]?.total || '0');
+      let runOpInv = parseFloat(opInvRows[0]?.total || '0'), runResInv = parseFloat(resInvRows[0]?.total || '0');
+
+      const assessmentGroups = await qr.query(`SELECT ag.frequency, ag.regular_assessment, ag.special_assessment,
+        (SELECT COUNT(*) FROM units u WHERE u.assessment_group_id=ag.id AND u.status='active') as unit_count FROM assessment_groups ag WHERE ag.is_active=true`);
+      const getAssessmentInc = (month: number) => {
+        let op = 0, res = 0;
+        for (const g of assessmentGroups) {
+          const units = parseInt(g.unit_count) || 0, reg = parseFloat(g.regular_assessment) || 0, spec = parseFloat(g.special_assessment) || 0;
+          const freq = g.frequency || 'monthly';
+          let applies = freq === 'monthly' || (freq === 'quarterly' && [1,4,7,10].includes(month)) || (freq === 'annual' && month === 1);
+          if (applies) { op += reg * units; res += spec * units; }
+        }
+        return { operating: op, reserve: res };
+      };
+
+      const budgetsByYM: Record<string, { opIncome: number; opExpense: number; resIncome: number; resExpense: number }> = {};
+      for (const yr of [year, year + 1]) {
+        const bRows = await qr.query(`SELECT b.fund_type, a.account_type, b.jan,b.feb,b.mar,b.apr,b.may,b.jun,b.jul,b.aug,b.sep,b.oct,b.nov,b.dec_amt FROM budgets b JOIN accounts a ON a.id=b.account_id WHERE b.fiscal_year=$1`, [yr]);
+        for (let m = 0; m < 12; m++) {
+          const k = `${yr}-${m+1}`;
+          if (!budgetsByYM[k]) budgetsByYM[k] = { opIncome: 0, opExpense: 0, resIncome: 0, resExpense: 0 };
+          for (const r of bRows) {
+            const amt = parseFloat(r[monthNames[m]]) || 0;
+            if (!amt) continue;
+            const isOp = r.fund_type === 'operating';
+            if (r.account_type === 'income') { if (isOp) budgetsByYM[k].opIncome += amt; else budgetsByYM[k].resIncome += amt; }
+            else if (r.account_type === 'expense') { if (isOp) budgetsByYM[k].opExpense += amt; else budgetsByYM[k].resExpense += amt; }
+          }
+        }
+      }
+
+      const maturities = await qr.query(`SELECT fund_type, current_value, maturity_date, interest_rate, purchase_date FROM investment_accounts WHERE is_active=true AND maturity_date IS NOT NULL AND maturity_date>CURRENT_DATE`);
+      const matIdx: Record<string, { operating: number; reserve: number }> = {};
+      for (const inv of maturities) {
+        const d = new Date(inv.maturity_date), k = `${d.getFullYear()}-${d.getMonth()+1}`;
+        if (!matIdx[k]) matIdx[k] = { operating: 0, reserve: 0 };
+        const val = parseFloat(inv.current_value) || 0, rate = parseFloat(inv.interest_rate) || 0;
+        const pDate = inv.purchase_date ? new Date(inv.purchase_date) : new Date();
+        const days = Math.max((d.getTime() - pDate.getTime()) / 86400000, 1);
+        const total = val + val * (rate/100) * (days/365);
+        if (inv.fund_type === 'operating') matIdx[k].operating += total; else matIdx[k].reserve += total;
+      }
+
+      const projExp = await qr.query(`SELECT estimated_cost, target_year, target_month, fund_source FROM projects WHERE is_active=true AND status IN ('planned','in_progress') AND target_year IS NOT NULL AND estimated_cost>0`);
+      const projIdx: Record<string, { operating: number; reserve: number }> = {};
+      for (const p of projExp) {
+        const k = `${parseInt(p.target_year)}-${parseInt(p.target_month)||6}`;
+        if (!projIdx[k]) projIdx[k] = { operating: 0, reserve: 0 };
+        const c = parseFloat(p.estimated_cost) || 0;
+        if (p.fund_source === 'operating') projIdx[k].operating += c; else projIdx[k].reserve += c;
+      }
+
+      const datapoints: any[] = [];
+      for (let i = 0; i < 12; i++) {
+        const fY = year + Math.floor((currentMonth-1+i)/12), fM = ((currentMonth-1+i)%12)+1;
+        const k = `${fY}-${fM}`, label = `${monthLabels[fM-1]} ${fY}`;
+        const asmt = getAssessmentInc(fM), bud = budgetsByYM[k] || { opIncome: 0, opExpense: 0, resIncome: 0, resExpense: 0 };
+        const mat = matIdx[k] || { operating: 0, reserve: 0 }, proj = projIdx[k] || { operating: 0, reserve: 0 };
+        const opInc = bud.opIncome > 0 ? bud.opIncome : asmt.operating, resInc = bud.resIncome > 0 ? bud.resIncome : asmt.reserve;
+        runOpCash += opInc - bud.opExpense - proj.operating + mat.operating;
+        runResCash += resInc - bud.resExpense - proj.reserve + mat.reserve;
+        if (mat.operating > 0) runOpInv = Math.max(0, runOpInv - mat.operating * 0.96);
+        if (mat.reserve > 0) runResInv = Math.max(0, runResInv - mat.reserve * 0.96);
+        datapoints.push({ month: label, operating_cash: Math.round(runOpCash*100)/100, operating_investments: Math.round(runOpInv*100)/100,
+          reserve_cash: Math.round(runResCash*100)/100, reserve_investments: Math.round(runResInv*100)/100,
+          op_income: Math.round(opInc*100)/100, op_expense: Math.round(bud.opExpense*100)/100,
+          res_income: Math.round(resInc*100)/100, res_expense: Math.round(bud.resExpense*100)/100,
+          project_cost_op: Math.round(proj.operating*100)/100, project_cost_res: Math.round(proj.reserve*100)/100,
+          maturity_op: Math.round(mat.operating*100)/100, maturity_res: Math.round(mat.reserve*100)/100 });
+      }
+
+      const asmtSchedule = assessmentGroups.map((g: any) => ({
+        frequency: g.frequency || 'monthly', regular_per_unit: parseFloat(g.regular_assessment) || 0,
+        special_per_unit: parseFloat(g.special_assessment) || 0, units: parseInt(g.unit_count) || 0,
+        total_regular: (parseFloat(g.regular_assessment) || 0) * (parseInt(g.unit_count) || 0),
+        total_special: (parseFloat(g.special_assessment) || 0) * (parseInt(g.unit_count) || 0),
+      }));
+
+      // ── Market rates from shared schema ──
+      const fetchLatest = async (rateType: string) =>
+        qr.query(`SELECT bank_name, apy, min_deposit, term, term_months, rate_type, fetched_at
+          FROM shared.cd_rates WHERE rate_type=$1 AND fetched_at=(SELECT MAX(fetched_at) FROM shared.cd_rates WHERE rate_type=$1)
+          ORDER BY apy DESC LIMIT 25`, [rateType]);
+      const [cdRates, mmRates, hysRates] = await Promise.all([fetchLatest('cd'), fetchLatest('money_market'), fetchLatest('high_yield_savings')]);
+      const allRates = { cd: cdRates, money_market: mmRates, high_yield_savings: hysRates };
+
+      // ── Build prompt (replicates InvestmentPlanningService.buildPromptMessages) ──
+      const { summary, investment_accounts: invAccts, cash_flow_context: cfc } = snapshot;
+      const today = new Date().toISOString().split('T')[0];
+
+      const systemPrompt = `You are a financial advisor specializing in HOA (Homeowners Association) reserve fund management and conservative investment strategy. You provide fiduciary-grade investment recommendations.
+
+CRITICAL RULES:
+1. HOAs are legally required to maintain adequate reserves. NEVER recommend depleting reserve funds below safe levels.
+2. HOA investments must be conservative ONLY: CDs, money market accounts, treasury bills, and high-yield savings. NO stocks, bonds, mutual funds, or speculative instruments.
+3. Liquidity is paramount: always ensure enough cash to cover at least 3 months of operating expenses AND any capital project expenses due within the next 12 months.
+4. CD laddering is the preferred strategy for reserve funds — it balances yield with regular liquidity access.
+5. Operating funds should remain highly liquid (money market or high-yield savings only).
+6. Respect the separation between operating funds and reserve funds. Never suggest commingling.
+7. Base your recommendations ONLY on the available market rates (CDs, Money Market, High Yield Savings) provided. Do not reference rates or banks not in the provided data.
+8. CRITICAL: Use the 12-MONTH CASH FLOW FORECAST to understand future liquidity. The forecast includes projected income (regular assessments AND special assessments collected from homeowners), budgeted expenses, investment maturities, and capital project costs. Do NOT flag liquidity shortfalls if the forecast shows sufficient income arriving before the expense is due.
+9. When recommending money market or high yield savings accounts, focus on their liquidity advantages for operating funds. When recommending CDs, focus on their higher yields for longer-term reserve fund placement.
+10. Compare current account rates against available market rates. If better rates are available, suggest specific moves with the potential additional interest income that could be earned.
+
+RESPONSE FORMAT:
+Respond with ONLY valid JSON (no markdown, no code fences) matching this exact schema:
+{
+  "recommendations": [
+    {
+      "type": "cd_ladder" | "new_investment" | "reallocation" | "maturity_action" | "liquidity_warning" | "general",
+      "priority": "high" | "medium" | "low",
+      "title": "Short action title (under 60 chars)",
+      "summary": "One sentence summary of the recommendation",
+      "details": "Detailed explanation with specific dollar amounts and timeframes",
+      "fund_type": "operating" | "reserve" | "both",
+      "suggested_amount": 50000.00,
+      "suggested_term": "12 months",
+      "suggested_rate": 4.50,
+      "bank_name": "Bank name from market rates (if applicable)",
+      "rationale": "Financial reasoning for why this makes sense",
+      "components": [
+        {
+          "label": "Component label (e.g. '6-Month CD at Marcus')",
+          "amount": 6600.00,
+          "term_months": 6,
+          "rate": 4.05,
+          "bank_name": "Marcus",
+          "investment_type": "cd"
+        }
+      ]
+    }
+  ],
+  "overall_assessment": "2-3 sentence overview of the HOA's current investment position and opportunities",
+  "risk_notes": ["Array of risk items or concerns to flag for the board"]
+}
+
+IMPORTANT ABOUT COMPONENTS:
+- For cd_ladder recommendations, you MUST include a "components" array with each individual CD as a separate component. Each component should have its own label, amount, term_months, rate, and bank_name. The suggested_amount should be the total of all component amounts.
+- For other multi-part strategies (e.g. splitting funds across multiple accounts), also include a "components" array.
+- For simple single-investment recommendations, omit the "components" field entirely.
+
+IMPORTANT: Provide 3-7 actionable recommendations. Prioritize high-priority items (liquidity risks, maturing investments) before optimization opportunities. Include specific dollar amounts wherever possible. When there are opportunities for better rates on existing positions, quantify the additional annual interest that could be earned.`;
+
+      const investmentsList = invAccts.length === 0 ? 'No current investments.'
+        : invAccts.map((i: any) => `- ${i.name} | Type: ${i.investment_type} | Fund: ${i.fund_type} | Principal: $${parseFloat(i.principal).toFixed(2)} | Rate: ${parseFloat(i.interest_rate||'0').toFixed(2)}% | Maturity: ${i.maturity_date ? new Date(i.maturity_date).toLocaleDateString() : 'N/A'}`).join('\n');
+      const budgetLines = budgets.length === 0 ? 'No budget data available.'
+        : budgets.map((b: any) => `- ${b.name} (${b.account_number}) | ${b.account_type}/${b.fund_type}: $${parseFloat(b.annual_total).toFixed(2)}/yr`).join('\n');
+      const projectLines = projects.length === 0 ? 'No upcoming capital projects.'
+        : projects.map((p: any) => `- ${p.name} | Cost: $${parseFloat(p.estimated_cost).toFixed(2)} | Target: ${p.target_year||'?'}/${p.target_month||'?'} | Fund: ${p.fund_source} | Status: ${p.status} | Funded: ${parseFloat(p.funded_percentage||'0').toFixed(1)}%`).join('\n');
+      const budgetSummaryLines = (cfc.budget_summary || []).length === 0 ? 'No budget summary available.'
+        : cfc.budget_summary.map((b: any) => `- ${b.fund_type} ${b.account_type}: $${parseFloat(b.annual_total).toFixed(2)}/yr (~$${(parseFloat(b.annual_total)/12).toFixed(2)}/mo)`).join('\n');
+
+      const formatRates = (rates: any[], label: string) => rates.length === 0
+        ? `No ${label} rate data available. Rate fetcher may not have been run yet.`
+        : rates.map((r: any) => `- ${r.bank_name} | APY: ${parseFloat(String(r.apy)).toFixed(2)}%${r.term !== 'N/A' ? ` | Term: ${r.term}` : ''} | Min Deposit: ${r.min_deposit ? '$'+parseFloat(String(r.min_deposit)).toLocaleString() : 'N/A'}`).join('\n');
+
+      const asmtLines = asmtSchedule.length === 0 ? 'No assessment schedule available.'
+        : asmtSchedule.map((a: any) => `- ${a.frequency} collection | ${a.units} units | Regular: $${a.regular_per_unit.toFixed(2)}/unit ($${a.total_regular.toFixed(2)} total) → Operating | Special: $${a.special_per_unit.toFixed(2)}/unit ($${a.total_special.toFixed(2)} total) → Reserve`).join('\n');
+
+      const forecastLines = datapoints.map((dp: any) => {
+        const d: string[] = [];
+        if (dp.op_income > 0) d.push(`OpInc:$${dp.op_income.toFixed(0)}`);
+        if (dp.op_expense > 0) d.push(`OpExp:$${dp.op_expense.toFixed(0)}`);
+        if (dp.res_income > 0) d.push(`ResInc:$${dp.res_income.toFixed(0)}`);
+        if (dp.res_expense > 0) d.push(`ResExp:$${dp.res_expense.toFixed(0)}`);
+        if (dp.project_cost_res > 0) d.push(`ResProjCost:$${dp.project_cost_res.toFixed(0)}`);
+        if (dp.project_cost_op > 0) d.push(`OpProjCost:$${dp.project_cost_op.toFixed(0)}`);
+        if (dp.maturity_op > 0) d.push(`OpMaturity:$${dp.maturity_op.toFixed(0)}`);
+        if (dp.maturity_res > 0) d.push(`ResMaturity:$${dp.maturity_res.toFixed(0)}`);
+        return `- ${dp.month} | OpCash: $${dp.operating_cash.toFixed(0)} | ResCash: $${dp.reserve_cash.toFixed(0)} | OpInv: $${dp.operating_investments.toFixed(0)} | ResInv: $${dp.reserve_investments.toFixed(0)} | Drivers: ${d.join(', ') || 'none'}`;
+      }).join('\n');
+
+      const userPrompt = `Analyze this HOA's financial position and provide investment recommendations.
+
+TODAY'S DATE: ${today}
+
+=== CURRENT CASH POSITIONS ===
+Operating Cash (bank accounts): $${summary.operating_cash.toFixed(2)}
+Reserve Cash (bank accounts): $${summary.reserve_cash.toFixed(2)}
+Operating Investments: $${summary.operating_investments.toFixed(2)}
+Reserve Investments: $${summary.reserve_investments.toFixed(2)}
+Total Operating Fund: $${summary.total_operating.toFixed(2)}
+Total Reserve Fund: $${summary.total_reserve.toFixed(2)}
+Grand Total: $${summary.total_all.toFixed(2)}
+
+=== CURRENT INVESTMENTS ===
+${investmentsList}
+
+=== ASSESSMENT INCOME SCHEDULE ===
+${asmtLines}
+Note: "Regular" assessments fund Operating. "Special" assessments fund Reserve. Both are collected from homeowners per the frequency above.
+
+=== ANNUAL BUDGET (${new Date().getFullYear()}) ===
+${budgetLines}
+
+=== BUDGET SUMMARY (Annual Totals by Category) ===
+${budgetSummaryLines}
+
+=== MONTHLY ASSESSMENT INCOME ===
+Recurring monthly regular assessment income: $${cfc.monthly_assessment_income.toFixed(2)}/month (operating fund)
+
+=== UPCOMING CAPITAL PROJECTS ===
+${projectLines}
+
+=== 12-MONTH CASH FLOW FORECAST (Projected) ===
+This forecast shows month-by-month projected balances factoring in ALL income (regular assessments, special assessments, budgeted income), ALL expenses (budgeted expenses, capital project costs), and investment maturities.
+${forecastLines}
+
+=== AVAILABLE MARKET RATES ===
+
+--- CD Rates ---
+${formatRates(allRates.cd, 'CD')}
+
+--- Money Market Rates ---
+${formatRates(allRates.money_market, 'Money Market')}
+
+--- High Yield Savings Rates ---
+${formatRates(allRates.high_yield_savings, 'High Yield Savings')}
+
+Based on this complete financial picture INCLUDING the 12-month cash flow forecast, provide your investment recommendations. Consider:
+1. Is there excess cash that could earn better returns in CDs, money market accounts, or high-yield savings?
+2. Are any current investments maturing soon that need reinvestment planning?
+3. Is the liquidity position adequate for upcoming expenses and projects? USE THE FORECAST to check — if income (including special assessments) arrives before expenses are due, the position may be adequate even if current cash seems low.
+4. Would a CD ladder strategy improve the yield while maintaining access to funds?
+5. Are operating and reserve funds properly separated in the investment strategy?
+6. Could any current money market or savings accounts earn better rates at a different bank? Quantify the potential additional annual interest.
+7. For operating funds that need to stay liquid, are money market or high-yield savings accounts being used optimally?`;
+
+      return [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+      ];
+    } finally {
+      await qr.release();
+    }
+  }
+
+  private async getModelConfigs(): Promise<ModelConfig[]> {
+    const configs: ModelConfig[] = [];
+
+    // Production model from env vars
+    const prodApiUrl = this.configService.get<string>('AI_API_URL') || 'https://integrate.api.nvidia.com/v1';
+    const prodApiKey = this.configService.get<string>('AI_API_KEY');
+    const prodModel = this.configService.get<string>('AI_MODEL') || 'qwen/qwen3.5-397b-a17b';
+
+    if (prodApiKey) {
+      configs.push({
+        role: 'production',
+        name: 'Production',
+        apiUrl: prodApiUrl,
+        apiKey: prodApiKey,
+        modelName: prodModel,
+      });
+    }
+
+    // Alternate models from DB
+    const alternates = await this.dataSource.query(
+      `SELECT slot, name, api_url, api_key, model_name
+       FROM shared.shadow_ai_models
+       WHERE is_active = true
+       ORDER BY slot`,
+    );
+
+    for (const alt of alternates) {
+      configs.push({
+        role: alt.slot === 'A' ? 'alternate_a' : 'alternate_b',
+        name: alt.name,
+        apiUrl: alt.api_url,
+        apiKey: alt.api_key,
+        modelName: alt.model_name,
+      });
+    }
+
+    return configs;
+  }
+
+  private getFeatureParams(feature: Feature): { temperature: number; maxTokens: number } {
+    if (feature === 'investment_recommendations') {
+      return { temperature: 0.3, maxTokens: 4096 };
+    }
+    return { temperature: 0.1, maxTokens: 2048 };
+  }
+
+  private async executeModels(
+    runId: string,
+    messages: Array<{ role: string; content: string }>,
+    configs: ModelConfig[],
+    feature: Feature,
+  ) {
+    const { temperature, maxTokens } = this.getFeatureParams(feature);
+
+    const promises = configs.map(async (config) => {
+      // Mark as running
+      await this.dataSource.query(
+        `UPDATE shared.shadow_run_results SET status = 'running' WHERE run_id = $1 AND model_role = $2`,
+        [runId, config.role],
+      );
+
+      try {
+        const result = await callOpenAICompatible({
+          apiUrl: config.apiUrl,
+          apiKey: config.apiKey,
+          model: config.modelName,
+          messages,
+          temperature,
+          maxTokens,
+        });
+
+        // Try to parse the response as JSON
+        let parsedResponse: any = null;
+        try {
+          parsedResponse = JSON.parse(result.content);
+        } catch {
+          // Store raw content if not valid JSON
+          parsedResponse = { raw_text: result.content };
+        }
+
+        await this.dataSource.query(
+          `UPDATE shared.shadow_run_results
+           SET status = 'success', raw_response = $1, parsed_response = $2,
+               response_time_ms = $3, token_usage = $4
+           WHERE run_id = $5 AND model_role = $6`,
+          [
+            result.rawResponse,
+            JSON.stringify(parsedResponse),
+            result.responseTimeMs,
+            result.usage ? JSON.stringify(result.usage) : null,
+            runId,
+            config.role,
+          ],
+        );
+
+        this.logger.log(`Shadow run ${runId} - ${config.role} (${config.modelName}) completed in ${result.responseTimeMs}ms`);
+      } catch (error: any) {
+        this.logger.error(`Shadow run ${runId} - ${config.role} (${config.modelName}) failed: ${error.message}`);
+        await this.dataSource.query(
+          `UPDATE shared.shadow_run_results
+           SET status = 'error', error_message = $1
+           WHERE run_id = $2 AND model_role = $3`,
+          [error.message, runId, config.role],
+        );
+      }
+    });
+
+    await Promise.allSettled(promises);
+
+    // Determine overall run status
+    const results = await this.dataSource.query(
+      `SELECT status FROM shared.shadow_run_results WHERE run_id = $1`,
+      [runId],
+    );
+    const allSuccess = results.every((r: any) => r.status === 'success');
+    const allError = results.every((r: any) => r.status === 'error');
+    const status = allSuccess ? 'completed' : allError ? 'failed' : 'partial';
+
+    await this.dataSource.query(
+      `UPDATE shared.shadow_runs SET status = $1, completed_at = NOW() WHERE id = $2`,
+      [status, runId],
+    );
+
+    this.logger.log(`Shadow run ${runId} finished with status: ${status}`);
+  }
+
+  // ── Table Creation (for initial setup) ──
+
+  async ensureTables() {
+    const qr = this.dataSource.createQueryRunner();
+    try {
+      await qr.connect();
+
+      await qr.query(`
+        CREATE TABLE IF NOT EXISTS shared.shadow_ai_models (
+          id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+          slot VARCHAR(10) NOT NULL UNIQUE CHECK (slot IN ('A', 'B')),
+          name VARCHAR(100) NOT NULL,
+          api_url VARCHAR(500) NOT NULL,
+          api_key VARCHAR(500) NOT NULL,
+          model_name VARCHAR(200) NOT NULL,
+          is_active BOOLEAN DEFAULT TRUE,
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW()
+        )
+      `);
+
+      await qr.query(`
+        CREATE TABLE IF NOT EXISTS shared.shadow_runs (
+          id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+          tenant_id UUID NOT NULL,
+          feature VARCHAR(30) NOT NULL CHECK (feature IN ('operating_health', 'reserve_health', 'investment_recommendations')),
+          status VARCHAR(20) NOT NULL DEFAULT 'running' CHECK (status IN ('running', 'completed', 'partial', 'failed')),
+          triggered_by UUID,
+          prompt_messages JSONB NOT NULL,
+          started_at TIMESTAMPTZ DEFAULT NOW(),
+          completed_at TIMESTAMPTZ,
+          created_at TIMESTAMPTZ DEFAULT NOW()
+        )
+      `);
+
+      await qr.query(`
+        CREATE INDEX IF NOT EXISTS idx_shadow_runs_tenant ON shared.shadow_runs(tenant_id)
+      `);
+      await qr.query(`
+        CREATE INDEX IF NOT EXISTS idx_shadow_runs_created ON shared.shadow_runs(created_at DESC)
+      `);
+
+      await qr.query(`
+        CREATE TABLE IF NOT EXISTS shared.shadow_run_results (
+          id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+          run_id UUID NOT NULL REFERENCES shared.shadow_runs(id) ON DELETE CASCADE,
+          model_role VARCHAR(20) NOT NULL CHECK (model_role IN ('production', 'alternate_a', 'alternate_b')),
+          model_name VARCHAR(200) NOT NULL,
+          api_url VARCHAR(500) NOT NULL,
+          raw_response TEXT,
+          parsed_response JSONB,
+          response_time_ms INTEGER,
+          token_usage JSONB,
+          status VARCHAR(20) NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'running', 'success', 'error')),
+          error_message TEXT,
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          UNIQUE(run_id, model_role)
+        )
+      `);
+
+      await qr.query(`
+        CREATE INDEX IF NOT EXISTS idx_shadow_results_run ON shared.shadow_run_results(run_id)
+      `);
+
+      this.logger.log('Shadow AI tables ensured');
+    } finally {
+      await qr.release();
+    }
+  }
+}

backend/src/modules/units/units.controller.ts

@@ -2,6 +2,7 @@ import { Controller, Get, Post, Put, Delete, Body, Param, Res, UseGuards } from
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { Response } from 'express';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { UnitsService } from './units.service';
 
 @ApiTags('units')
@@ -12,9 +13,11 @@ export class UnitsController {
   constructor(private unitsService: UnitsService) {}
 
   @Get()
+  @RequireCapability('assessments.units.view')
   findAll() { return this.unitsService.findAll(); }
 
   @Get('export')
+  @RequireCapability('assessments.units.view')
   async exportCSV(@Res() res: Response) {
     const csv = await this.unitsService.exportCSV();
     res.set({ 'Content-Type': 'text/csv', 'Content-Disposition': 'attachment; filename="units.csv"' });
@@ -22,17 +25,22 @@ export class UnitsController {
   }
 
   @Get(':id')
+  @RequireCapability('assessments.units.view')
   findOne(@Param('id') id: string) { return this.unitsService.findOne(id); }
 
   @Post('import')
+  @RequireCapability('assessments.units.edit')
   importCSV(@Body() rows: any[]) { return this.unitsService.importCSV(rows); }
 
   @Post()
+  @RequireCapability('assessments.units.edit')
   create(@Body() dto: any) { return this.unitsService.create(dto); }
 
   @Put(':id')
+  @RequireCapability('assessments.units.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.unitsService.update(id, dto); }
 
   @Delete(':id')
+  @RequireCapability('assessments.units.edit')
   delete(@Param('id') id: string) { return this.unitsService.delete(id); }
 }

backend/src/modules/vendors/vendors.controller.ts

@@ -2,6 +2,7 @@ import { Controller, Get, Post, Put, Body, Param, Query, Res, UseGuards } from '
 import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { Response } from 'express';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RequireCapability } from '../../common/decorators/capability.decorator';
 import { VendorsService } from './vendors.service';
 
 @ApiTags('vendors')
@@ -12,9 +13,11 @@ export class VendorsController {
   constructor(private vendorsService: VendorsService) {}
 
   @Get()
+  @RequireCapability('reference.vendors.view')
   findAll() { return this.vendorsService.findAll(); }
 
   @Get('export')
+  @RequireCapability('reference.vendors.view')
   async exportCSV(@Res() res: Response) {
     const csv = await this.vendorsService.exportCSV();
     res.set({ 'Content-Type': 'text/csv', 'Content-Disposition': 'attachment; filename="vendors.csv"' });
@@ -22,19 +25,24 @@ export class VendorsController {
   }
 
   @Get('1099-data')
+  @RequireCapability('reference.vendors.view')
   get1099Data(@Query('year') year: string) {
     return this.vendorsService.get1099Data(parseInt(year) || new Date().getFullYear());
   }
 
   @Get(':id')
+  @RequireCapability('reference.vendors.view')
   findOne(@Param('id') id: string) { return this.vendorsService.findOne(id); }
 
   @Post('import')
+  @RequireCapability('reference.vendors.edit')
   importCSV(@Body() rows: any[]) { return this.vendorsService.importCSV(rows); }
 
   @Post()
+  @RequireCapability('reference.vendors.edit')
   create(@Body() dto: any) { return this.vendorsService.create(dto); }
 
   @Put(':id')
+  @RequireCapability('reference.vendors.edit')
   update(@Param('id') id: string, @Body() dto: any) { return this.vendorsService.update(id, dto); }
 }

db/init/00-init.sql

@@ -58,7 +58,7 @@ CREATE TABLE shared.user_organizations (
     id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
     user_id UUID NOT NULL REFERENCES shared.users(id) ON DELETE CASCADE,
     organization_id UUID NOT NULL REFERENCES shared.organizations(id) ON DELETE CASCADE,
-    role VARCHAR(50) NOT NULL CHECK (role IN ('president', 'treasurer', 'secretary', 'member_at_large', 'manager', 'homeowner', 'admin', 'viewer')),
+    role VARCHAR(50) NOT NULL CHECK (role IN ('president', 'vice_president', 'treasurer', 'secretary', 'member_at_large', 'manager', 'homeowner', 'admin', 'viewer')),
     is_active BOOLEAN DEFAULT TRUE,
     joined_at TIMESTAMPTZ DEFAULT NOW(),
     UNIQUE(user_id, organization_id)

db/migrations/017-billing-enhancements.sql

@@ -0,0 +1,27 @@
+-- Migration 017: Billing Enhancements
+-- Adds support for annual billing, free trials, ACH/invoice billing,
+-- and past_due grace period status.
+
+-- ============================================================================
+-- 1. Add billing_interval column (month or year)
+-- ============================================================================
+ALTER TABLE shared.organizations ADD COLUMN IF NOT EXISTS billing_interval VARCHAR(20) DEFAULT 'month';
+
+-- ============================================================================
+-- 2. Add collection_method column (charge_automatically or send_invoice)
+-- ============================================================================
+ALTER TABLE shared.organizations ADD COLUMN IF NOT EXISTS collection_method VARCHAR(20) DEFAULT 'charge_automatically';
+
+-- ============================================================================
+-- 3. Update status CHECK to include 'past_due'
+-- ============================================================================
+ALTER TABLE shared.organizations DROP CONSTRAINT IF EXISTS organizations_status_check;
+ALTER TABLE shared.organizations ADD CONSTRAINT organizations_status_check
+  CHECK (status IN ('active', 'suspended', 'trial', 'archived', 'past_due'));
+
+-- ============================================================================
+-- 4. Ensure plan_level CHECK includes SaaS tiers (idempotent with 015)
+-- ============================================================================
+ALTER TABLE shared.organizations DROP CONSTRAINT IF EXISTS organizations_plan_level_check;
+ALTER TABLE shared.organizations ADD CONSTRAINT organizations_plan_level_check
+  CHECK (plan_level IN ('standard', 'premium', 'enterprise', 'starter', 'professional'));

db/migrations/018-ideas.sql

@@ -0,0 +1,15 @@
+-- Ideation feature: shared ideas table for cross-tenant idea submissions
+CREATE TABLE IF NOT EXISTS shared.ideas (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  org_id UUID NOT NULL REFERENCES shared.organizations(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES shared.users(id) ON DELETE CASCADE,
+  title VARCHAR(255) NOT NULL,
+  description TEXT,
+  status VARCHAR(20) NOT NULL DEFAULT 'new',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_ideas_org_id ON shared.ideas(org_id);
+CREATE INDEX IF NOT EXISTS idx_ideas_status ON shared.ideas(status);
+CREATE INDEX IF NOT EXISTS idx_ideas_created_at ON shared.ideas(created_at DESC);

db/migrations/019-ideas-admin-note.sql

@@ -0,0 +1,2 @@
+-- Add private admin note column to ideas table
+ALTER TABLE shared.ideas ADD COLUMN IF NOT EXISTS admin_note TEXT;

db/migrations/020-add-vice-president-role.sql

@@ -0,0 +1,9 @@
+-- Migration 020: Add vice_president role to user_organizations
+-- This adds the vice_president role to the CHECK constraint on the role column.
+
+ALTER TABLE shared.user_organizations
+  DROP CONSTRAINT IF EXISTS user_organizations_role_check;
+
+ALTER TABLE shared.user_organizations
+  ADD CONSTRAINT user_organizations_role_check
+  CHECK (role IN ('president', 'vice_president', 'treasurer', 'secretary', 'member_at_large', 'manager', 'homeowner', 'admin', 'viewer'));

docker-compose.prod.yml

@@ -45,6 +45,13 @@ services:
       - STRIPE_STARTER_PRICE_ID=${STRIPE_STARTER_PRICE_ID:-}
       - STRIPE_PROFESSIONAL_PRICE_ID=${STRIPE_PROFESSIONAL_PRICE_ID:-}
       - STRIPE_ENTERPRISE_PRICE_ID=${STRIPE_ENTERPRISE_PRICE_ID:-}
+      - STRIPE_STARTER_MONTHLY_PRICE_ID=${STRIPE_STARTER_MONTHLY_PRICE_ID:-}
+      - STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID=${STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID:-}
+      - STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=${STRIPE_ENTERPRISE_MONTHLY_PRICE_ID:-}
+      - STRIPE_STARTER_ANNUAL_PRICE_ID=${STRIPE_STARTER_ANNUAL_PRICE_ID:-}
+      - STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID=${STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID:-}
+      - STRIPE_ENTERPRISE_ANNUAL_PRICE_ID=${STRIPE_ENTERPRISE_ANNUAL_PRICE_ID:-}
+      - REQUIRE_PAYMENT_METHOD_FOR_TRIAL=${REQUIRE_PAYMENT_METHOD_FOR_TRIAL:-false}
       - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID:-}
       - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET:-}
       - GOOGLE_CALLBACK_URL=${GOOGLE_CALLBACK_URL:-https://app.hoaledgeriq.com/api/auth/google/callback}

docker-compose.yml

@@ -34,6 +34,13 @@ services:
       - STRIPE_STARTER_PRICE_ID=${STRIPE_STARTER_PRICE_ID:-}
       - STRIPE_PROFESSIONAL_PRICE_ID=${STRIPE_PROFESSIONAL_PRICE_ID:-}
       - STRIPE_ENTERPRISE_PRICE_ID=${STRIPE_ENTERPRISE_PRICE_ID:-}
+      - STRIPE_STARTER_MONTHLY_PRICE_ID=${STRIPE_STARTER_MONTHLY_PRICE_ID:-}
+      - STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID=${STRIPE_PROFESSIONAL_MONTHLY_PRICE_ID:-}
+      - STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=${STRIPE_ENTERPRISE_MONTHLY_PRICE_ID:-}
+      - STRIPE_STARTER_ANNUAL_PRICE_ID=${STRIPE_STARTER_ANNUAL_PRICE_ID:-}
+      - STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID=${STRIPE_PROFESSIONAL_ANNUAL_PRICE_ID:-}
+      - STRIPE_ENTERPRISE_ANNUAL_PRICE_ID=${STRIPE_ENTERPRISE_ANNUAL_PRICE_ID:-}
+      - REQUIRE_PAYMENT_METHOD_FOR_TRIAL=${REQUIRE_PAYMENT_METHOD_FOR_TRIAL:-false}
       - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID:-}
       - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET:-}
       - GOOGLE_CALLBACK_URL=${GOOGLE_CALLBACK_URL:-http://localhost/api/auth/google/callback}

docs/gitea-runner-setup.md

@@ -0,0 +1,230 @@
+# Gitea Actions Runner Setup — HOALedgerIQ Production Server
+
+This guide walks through setting up a self-hosted Gitea Actions runner on the production server so the deployment workflow (`.gitea/workflows/deploy.yml`) can execute automatically.
+
+The runner uses **host execution mode** — jobs run directly on the server (not inside Docker containers) so the deploy script has access to Docker, the git repo, and the local filesystem.
+
+---
+
+## Prerequisites
+
+- Ubuntu Linux production server
+- Gitea instance (e.g., `https://git.sensetostyle.com`)
+- Docker and Docker Compose installed on the server
+- The HOALedgerIQ repo cloned at `/opt/hoa-ledgeriq`
+
+---
+
+## Step 1: Enable Actions in Gitea
+
+Ensure Actions are enabled in your Gitea configuration (`/etc/gitea/app.ini`):
+
+```ini
+[actions]
+ENABLED = true
+```
+
+Restart Gitea after making changes:
+
+```bash
+sudo systemctl restart gitea
+```
+
+---
+
+## Step 2: Get a Registration Token
+
+1. Log into your Gitea instance
+2. Navigate to **Site Administration** → **Actions** → **Runners**
+3. Copy the **Registration Token**
+
+> **Tip:** For tighter security, you can get a repo-scoped token instead:
+> Repo → **Settings** → **Actions** → **Runners** → copy the token shown there.
+> This limits the runner to only execute workflows from that specific repository.
+
+---
+
+## Step 3: Install the Act Runner Binary
+
+```bash
+# Download the latest act_runner for x86_64 Linux
+wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64
+
+# Make executable and install to system path
+chmod +x act_runner-linux-amd64
+sudo mv act_runner-linux-amd64 /usr/local/bin/act_runner
+
+# Verify installation
+act_runner --version
+```
+
+> For ARM64 servers, use `act_runner-linux-arm64` instead.
+
+---
+
+## Step 4: Generate and Edit the Configuration
+
+```bash
+sudo mkdir -p /etc/act_runner
+act_runner generate-config > /tmp/config.yaml
+```
+
+Edit `/tmp/config.yaml` and set the **labels to use host execution mode**:
+
+```yaml
+runner:
+  labels:
+    - "ubuntu-latest:host"
+    - "ubuntu-22.04:host"
+```
+
+The `:host` suffix tells the runner to execute jobs directly on the server rather than spinning up Docker containers. This is required because the deploy script needs access to:
+
+- The Docker socket (to run `docker compose`)
+- The git repository at `/opt/hoa-ledgeriq`
+- The backup scripts and database
+
+Move the config into place and lock down permissions:
+
+```bash
+sudo mv /tmp/config.yaml /etc/act_runner/config.yaml
+sudo chmod 600 /etc/act_runner/config.yaml
+```
+
+---
+
+## Step 5: Register the Runner
+
+```bash
+act_runner register \
+  --no-interactive \
+  --instance "https://git.sensetostyle.com" \
+  --token "YOUR_REGISTRATION_TOKEN_HERE" \
+  --name "hoaledgeriq-prod" \
+  --labels "ubuntu-latest:host,ubuntu-22.04:host" \
+  --config /etc/act_runner/config.yaml
+```
+
+This creates a `.runner` file in the current directory containing the registration state.
+
+> **Interactive alternative:** Run `act_runner register --config /etc/act_runner/config.yaml` and follow the prompts.
+
+---
+
+## Step 6: Set Up as a Systemd Service
+
+Create the service file at `/etc/systemd/system/act_runner.service`:
+
+```ini
+[Unit]
+Description=Gitea Actions Runner (HOALedgerIQ Prod)
+Documentation=https://docs.gitea.com/usage/actions/act-runner
+After=docker.service network-online.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/hoa-ledgeriq
+ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+> **Security note on `User=root`:** The deploy script needs to run `docker compose`, `git reset --hard`, etc. If you have a dedicated deploy user in the `docker` group with write access to `/opt/hoa-ledgeriq`, use that instead. Running as root is the simplest option but grants maximum privileges.
+
+Enable and start the service:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable act_runner
+sudo systemctl start act_runner
+```
+
+---
+
+## Step 7: Verify the Runner Is Online
+
+Check the service is running:
+
+```bash
+sudo systemctl status act_runner
+```
+
+View logs:
+
+```bash
+sudo journalctl -u act_runner -f
+```
+
+Then confirm in Gitea:
+
+1. Go to **Site Administration** → **Actions** → **Runners**
+2. You should see **"hoaledgeriq-prod"** listed with status **Online**
+
+---
+
+## Step 8: Test the Workflow
+
+1. Go to your repo on Gitea → **Actions** tab
+2. Select the **"Deploy to Production"** workflow
+3. Click **Run Workflow**
+4. If this is the first deployment against an existing database, check the **"Mark existing migrations as applied"** box
+5. Monitor the run in the Actions tab
+
+---
+
+## Troubleshooting
+
+### Runner shows as Offline
+
+```bash
+# Check service status and logs
+sudo systemctl status act_runner
+sudo journalctl -u act_runner -n 50
+
+# Verify the instance URL is reachable from the server
+wget -qO- https://git.sensetostyle.com/api/v1/version
+```
+
+### Workflow stuck on "Waiting for runner"
+
+- Verify the runner labels match what the workflow expects. The workflow uses `runs-on: ubuntu-latest` which must match the `ubuntu-latest:host` label.
+- Check the runner is registered at the correct scope (instance-wide, org-level, or repo-level).
+
+### Permission denied errors during deploy
+
+- Ensure the systemd service `User` has Docker access (`usermod -aG docker <user>`)
+- Ensure the user has write access to `/opt/hoa-ledgeriq`
+
+### Re-registering after token expiry
+
+```bash
+sudo systemctl stop act_runner
+# Get a new token from Gitea admin panel, then:
+act_runner register \
+  --no-interactive \
+  --instance "https://git.sensetostyle.com" \
+  --token "NEW_TOKEN_HERE" \
+  --name "hoaledgeriq-prod" \
+  --labels "ubuntu-latest:host,ubuntu-22.04:host" \
+  --config /etc/act_runner/config.yaml
+sudo systemctl start act_runner
+```
+
+---
+
+## Security Best Practices
+
+| Concern | Recommendation |
+|---------|----------------|
+| Runner user | Use a dedicated user with `docker` group access rather than `root` when possible |
+| Registration token | Rotate periodically in the Gitea admin panel |
+| Config file | Keep `/etc/act_runner/config.yaml` at mode `600` (owner-read only) |
+| Runner scope | Register at the **repo level** instead of instance-wide so only this repo can trigger deployments |
+| Workflow triggers | The deploy workflow uses `workflow_dispatch` (manual only) — no automatic triggers on push |
+| Network | Ensure Gitea is accessed over HTTPS with valid SSL certificates |

docs/shadow-ai-benchmarking-plan.md

@@ -0,0 +1,275 @@
+# Shadow AI Benchmarking Feature
+
+## Context
+
+The platform uses a single AI model (Qwen 3.5 via NVIDIA NIM) for three features: Operating Health Score, Reserve Health Score, and Investment Recommendations. The platform owner needs a way to evaluate alternate models (different providers, different versions) against the production model using real tenant data — without impacting users. This enables informed model migration decisions by comparing outputs side-by-side.
+
+## Architecture Overview
+
+- **New admin page** at `/admin/shadow-ai` with model configuration, run trigger, and history
+- **New backend module** `shadow-ai` with controller, service, and 3 entities
+- **3 new DB tables** in the `shared` schema for model configs, runs, and results
+- **Shared AI caller utility** to avoid duplicating HTTP logic
+- **Minimal changes** to existing services: make prompt-building methods public and export modules
+
+---
+
+## Phase 1: Shared AI Caller Utility
+
+### New file: `backend/src/common/utils/ai-caller.ts`
+
+Extract the HTTP POST logic (currently duplicated in both `callAI()` methods) into a reusable function:
+
+```typescript
+export async function callOpenAICompatible(params: {
+  apiUrl: string;
+  apiKey: string;
+  model: string;
+  messages: Array<{ role: string; content: string }>;
+  temperature: number;
+  maxTokens: number;
+  timeoutMs?: number; // default 600000
+}): Promise<{
+  content: string;        // cleaned JSON string (fences + <think> stripped)
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+  responseTimeMs: number;
+}>
+```
+
+Handles: HTTPS POST to `{apiUrl}/chat/completions`, timeout, markdown fence stripping, `<think>` block removal, timing.
+
+## Phase 2: Expose Existing Prompt Builders
+
+### `backend/src/modules/health-scores/health-scores.service.ts`
+- Change `private` → `public` on:
+  - `gatherOperatingData(qr)` (line 252)
+  - `gatherReserveData(qr)` (line 523)
+  - `buildOperatingPrompt(data)` (line 790)
+  - `buildReservePrompt(data)` (line 930)
+  - `checkDataReadiness(qr, scoreType)` (used to validate data exists)
+
+### `backend/src/modules/health-scores/health-scores.module.ts`
+- Add `exports: [HealthScoresService]`
+
+### `backend/src/modules/investment-planning/investment-planning.service.ts`
+- Add new public method `buildPromptForSchema(schemaName: string)` that:
+  1. Creates a query runner, sets `search_path` to the tenant schema
+  2. Runs the same data-gathering queries (financial snapshot, market rates, monthly forecast) using the query runner directly (bypassing request-scoped `TenantService`)
+  3. Calls the existing `buildPromptMessages()` with gathered data
+  4. Returns `Array<{ role: string; content: string }>`
+- Change `buildPromptMessages()` from `private` → `public` (line 880)
+
+### `backend/src/modules/investment-planning/investment-planning.module.ts`
+- Add `exports: [InvestmentPlanningService]`
+
+## Phase 3: Database Tables & Entities
+
+### 3 new tables in `shared` schema
+
+**`shared.shadow_ai_models`** — Alternate model configurations (slots A and B)
+| Column | Type | Notes |
+|--------|------|-------|
+| id | UUID PK | |
+| slot | VARCHAR(10) | CHECK IN ('A', 'B'), UNIQUE |
+| name | VARCHAR(100) | Display label |
+| api_url | VARCHAR(500) | OpenAI-compatible endpoint |
+| api_key | VARCHAR(500) | Bearer token |
+| model_name | VARCHAR(200) | Model identifier |
+| is_active | BOOLEAN | Default true |
+| created_at | TIMESTAMPTZ | |
+| updated_at | TIMESTAMPTZ | |
+
+**`shared.shadow_runs`** — One row per comparison execution
+| Column | Type | Notes |
+|--------|------|-------|
+| id | UUID PK | |
+| tenant_id | UUID FK | → shared.organizations |
+| feature | VARCHAR(30) | CHECK IN ('operating_health', 'reserve_health', 'investment_recommendations') |
+| status | VARCHAR(20) | CHECK IN ('running', 'completed', 'partial', 'failed') |
+| triggered_by | UUID FK | → shared.users |
+| prompt_messages | JSONB | Exact messages sent to all models (proof of identical input) |
+| started_at | TIMESTAMPTZ | |
+| completed_at | TIMESTAMPTZ | |
+| created_at | TIMESTAMPTZ | |
+
+**`shared.shadow_run_results`** — One row per model per run (up to 3 per run)
+| Column | Type | Notes |
+|--------|------|-------|
+| id | UUID PK | |
+| run_id | UUID FK | → shadow_runs ON DELETE CASCADE |
+| model_role | VARCHAR(20) | CHECK IN ('production', 'alternate_a', 'alternate_b'), UNIQUE(run_id, model_role) |
+| model_name | VARCHAR(200) | Snapshot of model used |
+| api_url | VARCHAR(500) | Snapshot of endpoint used |
+| raw_response | TEXT | Unprocessed AI response |
+| parsed_response | JSONB | Validated structured output |
+| response_time_ms | INTEGER | |
+| token_usage | JSONB | { prompt_tokens, completion_tokens, total_tokens } |
+| status | VARCHAR(20) | CHECK IN ('pending', 'running', 'success', 'error') |
+| error_message | TEXT | |
+| created_at | TIMESTAMPTZ | |
+
+### Entity files
+- `backend/src/modules/shadow-ai/entities/shadow-ai-model.entity.ts`
+- `backend/src/modules/shadow-ai/entities/shadow-run.entity.ts`
+- `backend/src/modules/shadow-ai/entities/shadow-run-result.entity.ts`
+
+All use `@Entity({ schema: 'shared', name: '...' })` pattern.
+
+## Phase 4: Shadow AI Backend Module
+
+### New directory: `backend/src/modules/shadow-ai/`
+
+### `shadow-ai.service.ts`
+
+**Model CRUD:**
+- `getModels()` — Return both slots, mask API keys (show last 4 chars)
+- `upsertModel(slot, dto)` — INSERT/UPDATE config for slot A or B
+- `deleteModel(slot)` — Remove model config
+
+**Run Execution:**
+- `triggerRun(tenantId, feature, userId)`:
+  1. Look up tenant `schema_name` from `shared.organizations`
+  2. Build prompt messages by calling the appropriate exposed method:
+     - `operating_health`: Create query runner → set search_path → `healthScoresService.gatherOperatingData(qr)` → `healthScoresService.buildOperatingPrompt(data)`
+     - `reserve_health`: Same pattern with reserve methods
+     - `investment_recommendations`: `investmentPlanningService.buildPromptForSchema(schemaName)`
+  3. Insert `shadow_runs` row with `prompt_messages` stored as JSONB
+  4. Get production config from env vars, alternate configs from DB
+  5. Insert 1-3 `shadow_run_results` rows as 'pending' (production + active alternates)
+  6. Return `{ runId }` immediately
+  7. Fire-and-forget: call all models in parallel using `callOpenAICompatible()`
+     - Per feature: operating/reserve use temp 0.1, max_tokens 2048; investment uses temp 0.3, max_tokens 4096
+  8. Update each result row as it completes (success/error, parsed response, timing)
+  9. Update run status when all complete
+
+**History:**
+- `getRunHistory(page, limit, tenantFilter?, featureFilter?)` — Paginated list with tenant name JOIN
+- `getRunDetail(runId)` — Full run + all results
+
+### `shadow-ai.controller.ts`
+
+All endpoints use `@UseGuards(JwtAuthGuard)` + `requireSuperadmin(req)` pattern from `admin.controller.ts`.
+
+| Method | Path | Body/Params |
+|--------|------|-------------|
+| GET | `/admin/shadow-ai/models` | — |
+| PUT | `/admin/shadow-ai/models/:slot` | `{ name, apiUrl, apiKey, modelName, isActive }` |
+| DELETE | `/admin/shadow-ai/models/:slot` | — |
+| POST | `/admin/shadow-ai/runs` | `{ tenantId, feature }` |
+| GET | `/admin/shadow-ai/runs` | `?page&limit&tenantId&feature` |
+| GET | `/admin/shadow-ai/runs/:id` | — |
+
+### `shadow-ai.module.ts`
+
+```typescript
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([ShadowAiModel, ShadowRun, ShadowRunResult]),
+    HealthScoresModule,
+    InvestmentPlanningModule,
+    UsersModule,
+  ],
+  controllers: [ShadowAiController],
+  providers: [ShadowAiService],
+})
+```
+
+### Register in `backend/src/app.module.ts`
+- Add `import { ShadowAiModule }` and include in the `imports` array
+
+## Phase 5: Frontend — Admin Shadow AI Page
+
+### New file: `frontend/src/pages/admin/AdminShadowAiPage.tsx`
+
+**Layout**: Mantine `Tabs` with 3 tabs
+
+#### Tab 1: "Model Configuration"
+- Three `Card` components in a `SimpleGrid cols={3}`:
+  - **Production** (read-only): Shows model name, API URL from a dedicated endpoint or hardcoded label "From environment config"
+  - **Alternate A**: Form with `TextInput` (name, API URL, model name), `PasswordInput` (API key), `Switch` (active), Save/Delete buttons
+  - **Alternate B**: Same form
+- Fetches via `GET /api/admin/shadow-ai/models`
+- Saves via `PUT /api/admin/shadow-ai/models/A` or `/B`
+
+#### Tab 2: "Run Comparison"
+- `Select` dropdown for tenant (reuse `GET /api/admin/organizations` already used by AdminPage)
+- `Select` for feature type (Operating Health / Reserve Health / Investment Recommendations)
+- `Button` "Run Shadow Comparison"
+- On trigger: `POST /api/admin/shadow-ai/runs` → get `runId`
+- Poll `GET /api/admin/shadow-ai/runs/:id` every 3s via `refetchInterval` until status !== 'running'
+- Show per-model progress indicators during run
+- Once complete, render results using shared comparison component (below)
+
+#### Tab 3: "History"
+- `Table` with columns: Date, Tenant, Feature, Status (Badge), Duration
+- Filter controls: tenant Select, feature Select
+- Click row → expand detail or modal showing full comparison
+- Pagination
+
+#### Shared Component: Side-by-Side Results Display
+- `SimpleGrid cols={3}` (or fewer columns if only some models were configured)
+- Each column:
+  - Header: model name + response time `Badge`
+  - **For health scores**: Score with `RingProgress`, label `Badge`, summary text, factors list (color-coded by impact), recommendations list (color-coded by priority)
+  - **For investment**: Overall assessment text, recommendation cards with type/priority badges, risk notes
+  - Collapsible raw JSON via `Accordion`
+- **Diff highlighting**: Where parsed values differ across models, apply subtle background highlight (e.g., `yellow.0` in Mantine theme). Simple recursive comparison of JSON keys/values.
+
+### Route addition: `frontend/src/App.tsx`
+Within the `/admin` route group (after `<Route index element={<AdminPage />} />`):
+```tsx
+<Route path="shadow-ai" element={<AdminShadowAiPage />} />
+```
+
+### Sidebar nav: `frontend/src/components/layout/Sidebar.tsx`
+In the `isAdminOnly` section (after the "Admin Panel" NavLink, around line 134):
+```tsx
+<NavLink
+  label="AI Benchmarking"
+  leftSection={<IconScale size={18} />}
+  active={location.pathname === '/admin/shadow-ai'}
+  onClick={() => go('/admin/shadow-ai')}
+  color="violet"
+/>
+```
+
+## Implementation Order
+
+1. **`ai-caller.ts`** — Shared utility (no dependencies)
+2. **Health scores + investment planning** — Make methods public, add exports, add `buildPromptForSchema`
+3. **Entities** — 3 TypeORM entity files
+4. **Service + Controller + Module** — Shadow AI backend
+5. **Register module** in `app.module.ts`
+6. **Frontend page** — `AdminShadowAiPage.tsx`
+7. **Route + Sidebar** — Wire up navigation
+
+## Verification
+
+1. **Backend**: Start server, confirm no TypeORM errors for new entities
+2. **Model config**: Use admin UI to save/load/delete alternate model configs
+3. **Run comparison**: Select a tenant, trigger a run, verify all 3 models are called with identical prompts
+4. **Results display**: Confirm side-by-side output renders correctly for all 3 feature types
+5. **History**: Verify past runs are persisted and browsable
+6. **Auth**: Confirm non-superadmin users get 403 on all shadow-ai endpoints
+7. **Production safety**: Verify no changes to production AI behavior — shadow runs are completely isolated
+
+## Key Files to Modify
+
+- `backend/src/modules/health-scores/health-scores.service.ts` — Make 5 methods public
+- `backend/src/modules/health-scores/health-scores.module.ts` — Add exports
+- `backend/src/modules/investment-planning/investment-planning.service.ts` — Add `buildPromptForSchema()`, make `buildPromptMessages()` public
+- `backend/src/modules/investment-planning/investment-planning.module.ts` — Add exports
+- `backend/src/app.module.ts` — Register ShadowAiModule
+- `frontend/src/App.tsx` — Add route
+- `frontend/src/components/layout/Sidebar.tsx` — Add nav item
+
+## New Files
+
+- `backend/src/common/utils/ai-caller.ts`
+- `backend/src/modules/shadow-ai/shadow-ai.module.ts`
+- `backend/src/modules/shadow-ai/shadow-ai.service.ts`
+- `backend/src/modules/shadow-ai/shadow-ai.controller.ts`
+- `backend/src/modules/shadow-ai/entities/shadow-ai-model.entity.ts`
+- `backend/src/modules/shadow-ai/entities/shadow-run.entity.ts`
+- `backend/src/modules/shadow-ai/entities/shadow-run-result.entity.ts`
+- `frontend/src/pages/admin/AdminShadowAiPage.tsx`

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hoa-ledgeriq-frontend",
-  "version": "2026.3.17",
+  "version": "2026.3.19",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoa-ledgeriq-frontend",
-      "version": "2026.3.17",
+      "version": "2026.3.19",
       "dependencies": {
         "@mantine/core": "^7.15.3",
         "@mantine/dates": "^7.15.3",

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoa-ledgeriq-frontend",
-  "version": "2026.3.17",
+  "version": "2026.3.24",
   "private": true,
   "type": "module",
   "scripts": {

frontend/src/App.tsx

@@ -24,10 +24,13 @@ import { CashFlowPage } from './pages/reports/CashFlowPage';
 import { AgingReportPage } from './pages/reports/AgingReportPage';
 import { YearEndPage } from './pages/reports/YearEndPage';
 import { QuarterlyReportPage } from './pages/reports/QuarterlyReportPage';
+import { CapitalPlanningPage } from './pages/reports/CapitalPlanningPage';
 import { SettingsPage } from './pages/settings/SettingsPage';
 import { UserPreferencesPage } from './pages/preferences/UserPreferencesPage';
 import { OrgMembersPage } from './pages/org-members/OrgMembersPage';
 import { AdminPage } from './pages/admin/AdminPage';
+import { AdminIdeasPage } from './pages/admin/AdminIdeasPage';
+import { AdminShadowAiPage } from './pages/admin/AdminShadowAiPage';
 import { AssessmentGroupsPage } from './pages/assessment-groups/AssessmentGroupsPage';
 import { CashFlowForecastPage } from './pages/cash-flow/CashFlowForecastPage';
 import { MonthlyActualsPage } from './pages/monthly-actuals/MonthlyActualsPage';
@@ -39,6 +42,7 @@ import { AssessmentScenarioDetailPage } from './pages/board-planning/AssessmentS
 import { ScenarioComparisonPage } from './pages/board-planning/ScenarioComparisonPage';
 import { BudgetPlanningPage } from './pages/board-planning/BudgetPlanningPage';
 import { PricingPage } from './pages/pricing/PricingPage';
+import { PermissionSettingsPage } from './pages/settings/PermissionSettingsPage';
 import { OnboardingPage } from './pages/onboarding/OnboardingPage';
 import { OnboardingPendingPage } from './pages/onboarding/OnboardingPendingPage';
 
@@ -132,6 +136,8 @@ export function App() {
         }
       >
         <Route index element={<AdminPage />} />
+        <Route path="ideas" element={<AdminIdeasPage />} />
+        <Route path="shadow-ai" element={<AdminShadowAiPage />} />
       </Route>
 
       {/* Main app routes (require auth + org) */}
@@ -167,6 +173,7 @@ export function App() {
         <Route path="reports/sankey" element={<SankeyPage />} />
         <Route path="reports/year-end" element={<YearEndPage />} />
         <Route path="reports/quarterly" element={<QuarterlyReportPage />} />
+        <Route path="reports/capital-planning" element={<CapitalPlanningPage />} />
         <Route path="board-planning/budgets" element={<BudgetPlanningPage />} />
         <Route path="board-planning/investments" element={<InvestmentScenariosPage />} />
         <Route path="board-planning/investments/:id" element={<InvestmentScenarioDetailPage />} />
@@ -176,6 +183,7 @@ export function App() {
         <Route path="settings" element={<SettingsPage />} />
         <Route path="preferences" element={<UserPreferencesPage />} />
         <Route path="org-members" element={<OrgMembersPage />} />
+        <Route path="settings/permissions" element={<PermissionSettingsPage />} />
       </Route>
     </Routes>
   );

frontend/src/components/ideas/IdeaModal.tsx

@@ -0,0 +1,69 @@
+import { useState } from 'react';
+import { Modal, TextInput, Textarea, Button, Stack } from '@mantine/core';
+import { notifications } from '@mantine/notifications';
+import { useMutation } from '@tanstack/react-query';
+import api from '../../services/api';
+
+interface IdeaModalProps {
+  opened: boolean;
+  onClose: () => void;
+}
+
+export function IdeaModal({ opened, onClose }: IdeaModalProps) {
+  const [title, setTitle] = useState('');
+  const [description, setDescription] = useState('');
+
+  const submitIdea = useMutation({
+    mutationFn: async () => {
+      const { data } = await api.post('/ideas', { title, description });
+      return data;
+    },
+    onSuccess: () => {
+      notifications.show({ message: 'Idea submitted — thank you!', color: 'green' });
+      setTitle('');
+      setDescription('');
+      onClose();
+    },
+    onError: (err: any) => {
+      notifications.show({
+        message: err.response?.data?.message || 'Failed to submit idea',
+        color: 'red',
+      });
+    },
+  });
+
+  const handleClose = () => {
+    setTitle('');
+    setDescription('');
+    onClose();
+  };
+
+  return (
+    <Modal opened={opened} onClose={handleClose} title="Submit an Idea" size="md">
+      <Stack>
+        <TextInput
+          label="Title"
+          placeholder="Brief summary of your idea"
+          required
+          value={title}
+          onChange={(e) => setTitle(e.currentTarget.value)}
+          maxLength={255}
+        />
+        <Textarea
+          label="Description"
+          placeholder="Describe your idea in more detail (optional)"
+          minRows={4}
+          value={description}
+          onChange={(e) => setDescription(e.currentTarget.value)}
+        />
+        <Button
+          onClick={() => submitIdea.mutate()}
+          loading={submitIdea.isPending}
+          disabled={!title.trim()}
+        >
+          Submit Idea
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}

frontend/src/components/layout/AppLayout.tsx

@@ -11,6 +11,7 @@ import {
   IconEyeOff,
   IconSun,
   IconMoon,
+  IconBulb,
 } from '@tabler/icons-react';
 import { Outlet, useNavigate, useLocation } from 'react-router-dom';
 import { useAuthStore } from '../../stores/authStore';
@@ -18,6 +19,7 @@ import { usePreferencesStore } from '../../stores/preferencesStore';
 import { Sidebar } from './Sidebar';
 import { AppTour } from '../onboarding/AppTour';
 import { OnboardingWizard } from '../onboarding/OnboardingWizard';
+import { IdeaModal } from '../ideas/IdeaModal';
 import logoSrc from '../../assets/logo.png';
 
 export function AppLayout() {
@@ -28,6 +30,10 @@ export function AppLayout() {
   const location = useLocation();
   const isImpersonating = !!impersonationOriginal;
 
+  // ── Ideation State ──
+  const [ideaModalOpened, { open: openIdeaModal, close: closeIdeaModal }] = useDisclosure(false);
+  const ideationEnabled = currentOrg?.settings?.ideationEnabled === true;
+
   // ── Onboarding State ──
   const [showTour, setShowTour] = useState(false);
   const [showWizard, setShowWizard] = useState(false);
@@ -71,8 +77,9 @@ export function AppLayout() {
     navigate('/admin');
   };
 
-  // Tenant admins (president role) can manage org members
-  const isTenantAdmin = currentOrg?.role === 'president' || currentOrg?.role === 'admin';
+  // Capability-based check: can this user manage members?
+  const capabilities = currentOrg?.capabilities || [];
+  const isTenantAdmin = user?.isSuperadmin || capabilities.includes('settings.members.manage');
 
   return (
     <AppShell
@@ -121,6 +128,13 @@ export function AppLayout() {
             {currentOrg && (
               <Text size="sm" c="dimmed">{currentOrg.name}</Text>
             )}
+            {ideationEnabled && (
+              <Tooltip label="Submit an idea">
+                <ActionIcon variant="default" size="lg" onClick={openIdeaModal} aria-label="Submit idea">
+                  <IconBulb size={18} />
+                </ActionIcon>
+              </Tooltip>
+            )}
             <Tooltip label={colorScheme === 'dark' ? 'Light mode' : 'Dark mode'}>
               <ActionIcon
                 variant="default"
@@ -209,6 +223,9 @@ export function AppLayout() {
       {/* ── Onboarding Components ── */}
       <AppTour run={showTour} onComplete={handleTourComplete} />
       <OnboardingWizard opened={showWizard} onComplete={handleWizardComplete} />
+
+      {/* ── Ideation Modal ── */}
+      <IdeaModal opened={ideaModalOpened} onClose={closeIdeaModal} />
     </AppShell>
   );
 }

frontend/src/components/layout/Sidebar.tsx

@@ -20,61 +20,66 @@ import {
   IconCalculator,
   IconGitCompare,
   IconScale,
+  IconBulb,
 } from '@tabler/icons-react';
 import { useAuthStore } from '../../stores/authStore';
+import { CAPABILITIES } from '../../permissions/capabilities';
+
+const C = CAPABILITIES;
 
 const navSections = [
   {
     items: [
-      { label: 'Dashboard', icon: IconDashboard, path: '/dashboard' },
+      { label: 'Dashboard', icon: IconDashboard, path: '/dashboard', capability: C.DASHBOARD_VIEW },
     ],
   },
   {
     label: 'Financials',
     items: [
-      { label: 'Accounts', icon: IconListDetails, path: '/accounts', tourId: 'nav-accounts' },
-      { label: 'Cash Flow', icon: IconChartAreaLine, path: '/cash-flow' },
-      { label: 'Monthly Actuals', icon: IconClipboardCheck, path: '/monthly-actuals' },
-      { label: 'Budgets', icon: IconReportAnalytics, path: '/budgets/2026', tourId: 'nav-budgets' },
+      { label: 'Accounts', icon: IconListDetails, path: '/accounts', tourId: 'nav-accounts', capability: C.FINANCIALS_ACCOUNTS_VIEW },
+      { label: 'Cash Flow', icon: IconChartAreaLine, path: '/cash-flow', capability: C.FINANCIALS_CASHFLOW_VIEW },
+      { label: 'Monthly Actuals', icon: IconClipboardCheck, path: '/monthly-actuals', capability: C.FINANCIALS_ACTUALS_VIEW },
+      { label: 'Budgets', icon: IconReportAnalytics, path: '/budgets/2026', tourId: 'nav-budgets', capability: C.FINANCIALS_BUDGETS_VIEW },
     ],
   },
   {
     label: 'Assessments',
     items: [
-      { label: 'Units / Homeowners', icon: IconHome, path: '/units' },
-      { label: 'Assessment Groups', icon: IconCategory, path: '/assessment-groups', tourId: 'nav-assessment-groups' },
+      { label: 'Units / Homeowners', icon: IconHome, path: '/units', capability: C.ASSESSMENTS_UNITS_VIEW },
+      { label: 'Assessment Groups', icon: IconCategory, path: '/assessment-groups', tourId: 'nav-assessment-groups', capability: C.ASSESSMENTS_GROUPS_VIEW },
     ],
   },
   {
     label: 'Board Planning',
     items: [
-      { label: 'Budget Planning', icon: IconReportAnalytics, path: '/board-planning/budgets' },
+      { label: 'Budget Planning', icon: IconReportAnalytics, path: '/board-planning/budgets', capability: C.PLANNING_BUDGETS_VIEW },
       {
-        label: 'Projects', icon: IconShieldCheck, path: '/projects',
+        label: 'Projects', icon: IconShieldCheck, path: '/projects', capability: C.PLANNING_PROJECTS_VIEW,
         children: [
           { label: 'Capital Planning', path: '/capital-projects' },
         ],
       },
       {
-        label: 'Assessment Scenarios', icon: IconCalculator, path: '/board-planning/assessments',
+        label: 'Assessment Scenarios', icon: IconCalculator, path: '/board-planning/assessments', capability: C.PLANNING_SCENARIOS_VIEW,
       },
-      { label: 'Investment Planning', icon: IconSparkles, path: '/investment-planning', tourId: 'nav-investment-planning' },
-      { label: 'Investment Scenarios', icon: IconScale, path: '/board-planning/investments' },
-      { label: 'Compare Scenarios', icon: IconGitCompare, path: '/board-planning/compare' },
+      { label: 'Investment Planning', icon: IconSparkles, path: '/investment-planning', tourId: 'nav-investment-planning', capability: C.PLANNING_INVESTMENTS_VIEW },
+      { label: 'Investment Scenarios', icon: IconScale, path: '/board-planning/investments', capability: C.PLANNING_SCENARIOS_VIEW },
+      { label: 'Compare Scenarios', icon: IconGitCompare, path: '/board-planning/compare', capability: C.PLANNING_SCENARIOS_VIEW },
     ],
   },
   {
     label: 'Board Reference',
     items: [
-      { label: 'Vendors', icon: IconUsers, path: '/vendors' },
+      { label: 'Vendors', icon: IconUsers, path: '/vendors', capability: C.REFERENCE_VENDORS_VIEW },
     ],
   },
   {
     label: 'Transactions',
     items: [
-      { label: 'Transactions', icon: IconReceipt, path: '/transactions', tourId: 'nav-transactions' },
-      { label: 'Invoices', icon: IconFileInvoice, path: '/invoices' },
-      { label: 'Payments', icon: IconCash, path: '/payments' },
+      { label: 'Transactions', icon: IconReceipt, path: '/transactions', tourId: 'nav-transactions', capability: C.TRANSACTIONS_VIEW },
+      // Invoices and Payments hidden — see PARKING-LOT.md for future re-enablement
+      // { label: 'Invoices', icon: IconFileInvoice, path: '/invoices' },
+      // { label: 'Payments', icon: IconCash, path: '/payments' },
     ],
   },
   {
@@ -84,6 +89,7 @@ const navSections = [
         label: 'Reports',
         icon: IconChartSankey,
         tourId: 'nav-reports',
+        capability: C.REPORTS_VIEW,
         children: [
           { label: 'Balance Sheet', path: '/reports/balance-sheet' },
           { label: 'Income Statement', path: '/reports/income-statement' },
@@ -93,6 +99,7 @@ const navSections = [
           { label: 'Sankey Diagram', path: '/reports/sankey' },
           { label: 'Year-End', path: '/reports/year-end' },
           { label: 'Quarterly Financial', path: '/reports/quarterly' },
+          { label: 'Capital Planning', path: '/reports/capital-planning' },
         ],
       },
     ],
@@ -111,6 +118,15 @@ export function Sidebar({ onNavigate }: SidebarProps) {
   const organizations = useAuthStore((s) => s.organizations);
   const isAdminOnly = location.pathname.startsWith('/admin') && !currentOrg;
 
+  const capabilities = currentOrg?.capabilities || [];
+  const isSuperadmin = user?.isSuperadmin;
+
+  const hasCapability = (cap?: string) => {
+    if (!cap) return true;
+    if (isSuperadmin) return true;
+    return capabilities.includes(cap);
+  };
+
   const go = (path: string) => {
     navigate(path);
     onNavigate?.();
@@ -130,6 +146,20 @@ export function Sidebar({ onNavigate }: SidebarProps) {
           onClick={() => go('/admin')}
           color="red"
         />
+        <NavLink
+          label="Idea Submissions"
+          leftSection={<IconBulb size={18} />}
+          active={location.pathname === '/admin/ideas'}
+          onClick={() => go('/admin/ideas')}
+          color="yellow"
+        />
+        <NavLink
+          label="AI Benchmarking"
+          leftSection={<IconScale size={18} />}
+          active={location.pathname === '/admin/shadow-ai'}
+          onClick={() => go('/admin/shadow-ai')}
+          color="violet"
+        />
         {organizations && organizations.length > 0 && (
           <>
             <Divider my="sm" />
@@ -147,7 +177,10 @@ export function Sidebar({ onNavigate }: SidebarProps) {
 
   return (
     <ScrollArea p="sm" data-tour="sidebar-nav">
-      {navSections.map((section, sIdx) => (
+      {navSections.map((section, sIdx) => {
+        const visibleItems = section.items.filter((item: any) => hasCapability(item.capability));
+        if (visibleItems.length === 0) return null;
+        return (
         <div key={sIdx}>
           {section.label && (
             <>
@@ -157,7 +190,7 @@ export function Sidebar({ onNavigate }: SidebarProps) {
               </Text>
             </>
           )}
-          {section.items.map((item: any) =>
+          {visibleItems.map((item: any) =>
             item.children && !item.path ? (
               // Collapsible group without a parent route (e.g. Reports)
               <NavLink
@@ -213,7 +246,8 @@ export function Sidebar({ onNavigate }: SidebarProps) {
             ),
           )}
         </div>
-      ))}
+        );
+      })}
 
       {user?.isSuperadmin && (
         <>
@@ -228,6 +262,20 @@ export function Sidebar({ onNavigate }: SidebarProps) {
             onClick={() => go('/admin')}
             color="red"
           />
+          <NavLink
+            label="Idea Submissions"
+            leftSection={<IconBulb size={18} />}
+            active={location.pathname === '/admin/ideas'}
+            onClick={() => go('/admin/ideas')}
+            color="yellow"
+          />
+          <NavLink
+            label="AI Benchmarking"
+            leftSection={<IconScale size={18} />}
+            active={location.pathname === '/admin/shadow-ai'}
+            onClick={() => go('/admin/shadow-ai')}
+            color="violet"
+          />
         </>
       )}
     </ScrollArea>

frontend/src/components/onboarding/OnboardingWizard.tsx

@@ -1,15 +1,17 @@
 import { useState } from 'react';
 import {
   Modal, Stepper, Button, Group, TextInput, NumberInput, Textarea,
-  Select, Stack, Text, Title, Alert, ActionIcon, Table, FileInput,
-  Card, ThemeIcon, Divider, Loader, Badge, SimpleGrid, Box,
+  Select, Stack, Text, Title, Alert, ActionIcon, Table,
+  Card, ThemeIcon, Divider, Badge, SimpleGrid, Box,
 } from '@mantine/core';
+import { DateInput } from '@mantine/dates';
 import { notifications } from '@mantine/notifications';
 import {
-  IconBuildingBank, IconUsers, IconFileSpreadsheet,
-  IconPlus, IconTrash, IconDownload, IconCheck, IconRocket,
-  IconAlertCircle,
+  IconBuildingBank, IconUsers,
+  IconPlus, IconTrash, IconCheck, IconRocket,
+  IconAlertCircle, IconFileSpreadsheet, IconPigMoney, IconX,
 } from '@tabler/icons-react';
+import { useNavigate } from 'react-router-dom';
 import api from '../../services/api';
 import { useAuthStore } from '../../stores/authStore';
 
@@ -24,56 +26,40 @@ interface UnitRow {
   ownerEmail: string;
 }
 
-// ── CSV Parsing (reused from BudgetsPage pattern) ──
-function parseCSV(text: string): Record<string, string>[] {
-  const lines = text.split('\n').filter((l) => l.trim());
-  if (lines.length < 2) return [];
-  const headers = lines[0].split(',').map((h) => h.trim().replace(/^"|"$/g, ''));
-  return lines.slice(1).map((line) => {
-    const values: string[] = [];
-    let current = '';
-    let inQuotes = false;
-    for (const char of line) {
-      if (char === '"') { inQuotes = !inQuotes; }
-      else if (char === ',' && !inQuotes) { values.push(current.trim()); current = ''; }
-      else { current += char; }
-    }
-    values.push(current.trim());
-    const row: Record<string, string> = {};
-    headers.forEach((h, i) => { row[h] = values[i] || ''; });
-    return row;
-  });
-}
-
 export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps) {
+  const navigate = useNavigate();
   const [active, setActive] = useState(0);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const setOrgSettings = useAuthStore((s) => s.setOrgSettings);
 
-  // ── Step 1: Account State ──
+  // ── Step 1: Operating Account State ──
   const [accountCreated, setAccountCreated] = useState(false);
   const [accountName, setAccountName] = useState('Operating Checking');
   const [accountNumber, setAccountNumber] = useState('1000');
   const [accountDescription, setAccountDescription] = useState('');
   const [initialBalance, setInitialBalance] = useState<number | string>(0);
+  const [balanceDate, setBalanceDate] = useState<Date | null>(new Date());
 
-  // ── Step 2: Assessment Group State ──
+  // ── Step 2: Reserve Account State ──
+  const [reserveCreated, setReserveCreated] = useState(false);
+  const [reserveSkipped, setReserveSkipped] = useState(false);
+  const [reserveName, setReserveName] = useState('Reserve Savings');
+  const [reserveNumber, setReserveNumber] = useState('2000');
+  const [reserveDescription, setReserveDescription] = useState('');
+  const [reserveBalance, setReserveBalance] = useState<number | string>(0);
+  const [reserveBalanceDate, setReserveBalanceDate] = useState<Date | null>(new Date());
+
+  // ── Step 3: Assessment Group State ──
   const [groupCreated, setGroupCreated] = useState(false);
   const [groupName, setGroupName] = useState('Standard Assessment');
   const [regularAssessment, setRegularAssessment] = useState<number | string>(0);
   const [frequency, setFrequency] = useState('monthly');
+  const [unitCount, setUnitCount] = useState<number | string>(0);
   const [units, setUnits] = useState<UnitRow[]>([]);
   const [unitsCreated, setUnitsCreated] = useState(false);
 
-  // ── Step 3: Budget State ──
-  const [budgetFile, setBudgetFile] = useState<File | null>(null);
-  const [budgetUploaded, setBudgetUploaded] = useState(false);
-  const [budgetImportResult, setBudgetImportResult] = useState<any>(null);
-
-  const currentYear = new Date().getFullYear();
-
-  // ── Step 1: Create Account ──
+  // ── Step 1: Create Operating Account ──
   const handleCreateAccount = async () => {
     if (!accountName.trim()) {
       setError('Account name is required');
@@ -99,6 +85,7 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
         accountType: 'asset',
         fundType: 'operating',
         initialBalance: balance,
+        initialBalanceDate: balanceDate ? balanceDate.toISOString().split('T')[0] : undefined,
       });
       setAccountCreated(true);
       notifications.show({
@@ -114,7 +101,53 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
     }
   };
 
-  // ── Step 2: Create Assessment Group ──
+  // ── Step 2: Create Reserve Account ──
+  const handleCreateReserve = async () => {
+    if (!reserveName.trim()) {
+      setError('Account name is required');
+      return;
+    }
+    if (!reserveNumber.trim()) {
+      setError('Account number is required');
+      return;
+    }
+    const balance = typeof reserveBalance === 'string' ? parseFloat(reserveBalance) : reserveBalance;
+    if (isNaN(balance)) {
+      setError('Initial balance must be a valid number');
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+    try {
+      await api.post('/accounts', {
+        accountNumber: reserveNumber.trim(),
+        name: reserveName.trim(),
+        description: reserveDescription.trim(),
+        accountType: 'asset',
+        fundType: 'reserve',
+        initialBalance: balance,
+        initialBalanceDate: reserveBalanceDate ? reserveBalanceDate.toISOString().split('T')[0] : undefined,
+      });
+      setReserveCreated(true);
+      notifications.show({
+        title: 'Reserve Account Created',
+        message: `${reserveName} has been created with an initial balance of $${balance.toLocaleString()}`,
+        color: 'green',
+      });
+    } catch (err: any) {
+      const msg = err.response?.data?.message || 'Failed to create reserve account';
+      setError(typeof msg === 'string' ? msg : JSON.stringify(msg));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleSkipReserve = () => {
+    setReserveSkipped(true);
+  };
+
+  // ── Step 3: Create Assessment Group ──
   const handleCreateGroup = async () => {
     if (!groupName.trim()) {
       setError('Group name is required');
@@ -126,6 +159,8 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
       return;
     }
 
+    const count = typeof unitCount === 'string' ? parseInt(unitCount) : unitCount;
+
     setLoading(true);
     setError(null);
     try {
@@ -133,6 +168,7 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
         name: groupName.trim(),
         regularAssessment: assessment,
         frequency,
+        unitCount: isNaN(count) ? 0 : count,
         isDefault: true,
       });
       setGroupCreated(true);
@@ -175,72 +211,19 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
     }
   };
 
-  // ── Step 3: Budget Import ──
-  const handleDownloadTemplate = async () => {
-    try {
-      const response = await api.get(`/budgets/${currentYear}/template`, {
-        responseType: 'blob',
-      });
-      const url = window.URL.createObjectURL(new Blob([response.data]));
-      const link = document.createElement('a');
-      link.href = url;
-      link.setAttribute('download', `budget_template_${currentYear}.csv`);
-      document.body.appendChild(link);
-      link.click();
-      link.remove();
-      window.URL.revokeObjectURL(url);
-    } catch {
-      notifications.show({
-        title: 'Error',
-        message: 'Failed to download template',
-        color: 'red',
-      });
-    }
-  };
-
-  const handleUploadBudget = async () => {
-    if (!budgetFile) {
-      setError('Please select a CSV file');
-      return;
-    }
-
-    setLoading(true);
-    setError(null);
-    try {
-      const text = await budgetFile.text();
-      const rows = parseCSV(text);
-      if (rows.length === 0) {
-        setError('CSV file appears to be empty or invalid');
-        setLoading(false);
-        return;
-      }
-
-      const { data } = await api.post(`/budgets/${currentYear}/import`, { rows });
-      setBudgetUploaded(true);
-      setBudgetImportResult(data);
-      notifications.show({
-        title: 'Budget Imported',
-        message: `Imported ${data.imported || rows.length} budget line(s) for ${currentYear}`,
-        color: 'green',
-      });
-    } catch (err: any) {
-      const msg = err.response?.data?.message || 'Failed to import budget';
-      setError(typeof msg === 'string' ? msg : JSON.stringify(msg));
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  // ── Finish Wizard ──
+  // ── Finish Wizard → Navigate to Budget Planning ──
   const handleFinish = async () => {
     setLoading(true);
     try {
       await api.patch('/organizations/settings', { onboardingComplete: true });
       setOrgSettings({ onboardingComplete: true });
       onComplete();
+      // Navigate to Budget Planning so user can set up their budget immediately
+      navigate('/board-planning/budgets');
     } catch {
       // Even if API fails, close the wizard — onboarding data is already created
       onComplete();
+      navigate('/board-planning/budgets');
     } finally {
       setLoading(false);
     }
@@ -264,8 +247,8 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
   // ── Navigation ──
   const canGoNext = () => {
     if (active === 0) return accountCreated;
-    if (active === 1) return groupCreated;
-    if (active === 2) return true; // Budget is optional
+    if (active === 1) return reserveCreated || reserveSkipped;
+    if (active === 2) return groupCreated;
     return false;
   };
 
@@ -305,22 +288,22 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
         <Stepper active={active} size="sm" mb="xl">
           <Stepper.Step
             label="Operating Account"
-            description="Set up your primary bank account"
+            description="Primary bank account"
             icon={<IconBuildingBank size={18} />}
             completedIcon={<IconCheck size={18} />}
           />
+          <Stepper.Step
+            label="Reserve Account"
+            description={reserveSkipped ? 'Skipped' : 'Savings account'}
+            icon={<IconPigMoney size={18} />}
+            completedIcon={reserveSkipped ? <IconX size={18} /> : <IconCheck size={18} />}
+          />
           <Stepper.Step
             label="Assessment Group"
             description="Define homeowner assessments"
             icon={<IconUsers size={18} />}
             completedIcon={<IconCheck size={18} />}
           />
-          <Stepper.Step
-            label="Budget"
-            description="Import your annual budget"
-            icon={<IconFileSpreadsheet size={18} />}
-            completedIcon={<IconCheck size={18} />}
-          />
         </Stepper>
 
         {error && (
@@ -343,6 +326,7 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
                   <Text fw={500}>{accountName} created successfully!</Text>
                   <Text size="sm" c="dimmed">
                     Initial balance: ${(typeof initialBalance === 'number' ? initialBalance : parseFloat(initialBalance as string) || 0).toLocaleString()}
+                    {balanceDate && ` as of ${balanceDate.toLocaleDateString()}`}
                   </Text>
                 </Alert>
               ) : (
@@ -372,17 +356,26 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
                     autosize
                     minRows={2}
                   />
-                  <NumberInput
-                    label="Current Balance"
-                    description="Enter the current balance of this bank account"
-                    placeholder="0.00"
-                    value={initialBalance}
-                    onChange={setInitialBalance}
-                    thousandSeparator=","
-                    prefix="$"
-                    decimalScale={2}
-                    mb="md"
-                  />
+                  <SimpleGrid cols={2} mb="md">
+                    <NumberInput
+                      label="Current Balance"
+                      description="Enter the current balance of this bank account"
+                      placeholder="0.00"
+                      value={initialBalance}
+                      onChange={setInitialBalance}
+                      thousandSeparator=","
+                      prefix="$"
+                      decimalScale={2}
+                    />
+                    <DateInput
+                      label="Balance As-Of Date"
+                      description="Date this balance was accurate (e.g. last statement date)"
+                      value={balanceDate}
+                      onChange={setBalanceDate}
+                      maxDate={new Date()}
+                      clearable={false}
+                    />
+                  </SimpleGrid>
                   <Button
                     onClick={handleCreateAccount}
                     loading={loading}
@@ -396,8 +389,103 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
           </Stack>
         )}
 
-        {/* ── Step 2: Assessment Group + Units ── */}
+        {/* ── Step 2: Reserve Account ── */}
         {active === 1 && (
+          <Stack gap="md">
+            <Card withBorder p="lg">
+              <Text fw={600} mb="xs">Set Up a Reserve Savings Account</Text>
+              <Text size="sm" c="dimmed" mb="md">
+                Most HOAs maintain a reserve fund for long-term capital projects like roof replacements,
+                paving, and major repairs. Setting this up now gives you a more complete financial picture
+                from the start.
+              </Text>
+
+              {reserveCreated ? (
+                <Alert icon={<IconCheck size={16} />} color="green" variant="light">
+                  <Text fw={500}>{reserveName} created successfully!</Text>
+                  <Text size="sm" c="dimmed">
+                    Initial balance: ${(typeof reserveBalance === 'number' ? reserveBalance : parseFloat(reserveBalance as string) || 0).toLocaleString()}
+                    {reserveBalanceDate && ` as of ${reserveBalanceDate.toLocaleDateString()}`}
+                  </Text>
+                </Alert>
+              ) : reserveSkipped ? (
+                <Alert icon={<IconX size={16} />} color="gray" variant="light">
+                  <Text fw={500}>Reserve account skipped</Text>
+                  <Text size="sm" c="dimmed">
+                    You can always add a reserve account later from the Accounts page.
+                  </Text>
+                </Alert>
+              ) : (
+                <>
+                  <SimpleGrid cols={2} mb="md">
+                    <TextInput
+                      label="Account Name"
+                      placeholder="e.g. Reserve Savings"
+                      value={reserveName}
+                      onChange={(e) => setReserveName(e.currentTarget.value)}
+                      required
+                    />
+                    <TextInput
+                      label="Account Number"
+                      placeholder="e.g. 2000"
+                      value={reserveNumber}
+                      onChange={(e) => setReserveNumber(e.currentTarget.value)}
+                      required
+                    />
+                  </SimpleGrid>
+                  <Textarea
+                    label="Description"
+                    placeholder="Optional description"
+                    value={reserveDescription}
+                    onChange={(e) => setReserveDescription(e.currentTarget.value)}
+                    mb="md"
+                    autosize
+                    minRows={2}
+                  />
+                  <SimpleGrid cols={2} mb="md">
+                    <NumberInput
+                      label="Current Balance"
+                      description="Enter the current balance of this reserve account"
+                      placeholder="0.00"
+                      value={reserveBalance}
+                      onChange={setReserveBalance}
+                      thousandSeparator=","
+                      prefix="$"
+                      decimalScale={2}
+                    />
+                    <DateInput
+                      label="Balance As-Of Date"
+                      description="Date this balance was accurate"
+                      value={reserveBalanceDate}
+                      onChange={setReserveBalanceDate}
+                      maxDate={new Date()}
+                      clearable={false}
+                    />
+                  </SimpleGrid>
+                  <Group>
+                    <Button
+                      onClick={handleCreateReserve}
+                      loading={loading}
+                      leftSection={<IconPigMoney size={16} />}
+                    >
+                      Create Reserve Account
+                    </Button>
+                    <Button
+                      variant="subtle"
+                      color="gray"
+                      onClick={handleSkipReserve}
+                    >
+                      No Reserve Account
+                    </Button>
+                  </Group>
+                </>
+              )}
+            </Card>
+          </Stack>
+        )}
+
+        {/* ── Step 3: Assessment Group + Units ── */}
+        {active === 2 && (
           <Stack gap="md">
             <Card withBorder p="lg">
               <Text fw={600} mb="xs">Create an Assessment Group</Text>
@@ -415,7 +503,7 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
                 </Alert>
               ) : (
                 <>
-                  <SimpleGrid cols={3} mb="md">
+                  <SimpleGrid cols={2} mb="md">
                     <TextInput
                       label="Group Name"
                       placeholder="e.g. Standard Assessment"
@@ -423,6 +511,17 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
                       onChange={(e) => setGroupName(e.currentTarget.value)}
                       required
                     />
+                    <NumberInput
+                      label="Total Unit Count"
+                      description="How many units/lots does your community have?"
+                      placeholder="e.g. 50"
+                      value={unitCount}
+                      onChange={setUnitCount}
+                      min={0}
+                      required
+                    />
+                  </SimpleGrid>
+                  <SimpleGrid cols={2} mb="md">
                     <NumberInput
                       label="Assessment Amount"
                       placeholder="0.00"
@@ -520,61 +619,6 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
           </Stack>
         )}
 
-        {/* ── Step 3: Budget Upload ── */}
-        {active === 2 && (
-          <Stack gap="md">
-            <Card withBorder p="lg">
-              <Text fw={600} mb="xs">Import Your {currentYear} Budget</Text>
-              <Text size="sm" c="dimmed" mb="md">
-                Upload a CSV file with your annual budget. If you don&apos;t have one ready, you can download a template
-                or skip this step and set it up later from the Budgets page.
-              </Text>
-
-              {budgetUploaded ? (
-                <Alert icon={<IconCheck size={16} />} color="green" variant="light">
-                  <Text fw={500}>Budget imported successfully!</Text>
-                  {budgetImportResult && (
-                    <Text size="sm" c="dimmed">
-                      {budgetImportResult.created || 0} new lines created, {budgetImportResult.updated || 0} updated
-                    </Text>
-                  )}
-                </Alert>
-              ) : (
-                <>
-                  <Group mb="md">
-                    <Button
-                      variant="light"
-                      leftSection={<IconDownload size={16} />}
-                      onClick={handleDownloadTemplate}
-                    >
-                      Download CSV Template
-                    </Button>
-                  </Group>
-
-                  <FileInput
-                    label="Upload Budget CSV"
-                    placeholder="Click to select a .csv file"
-                    accept=".csv"
-                    value={budgetFile}
-                    onChange={setBudgetFile}
-                    mb="md"
-                    leftSection={<IconFileSpreadsheet size={16} />}
-                  />
-
-                  <Button
-                    onClick={handleUploadBudget}
-                    loading={loading}
-                    leftSection={<IconFileSpreadsheet size={16} />}
-                    disabled={!budgetFile}
-                  >
-                    Import Budget
-                  </Button>
-                </>
-              )}
-            </Card>
-          </Stack>
-        )}
-
         {/* ── Completion Screen ── */}
         {active === 3 && (
           <Card withBorder p="xl" style={{ textAlign: 'center' }}>
@@ -583,16 +627,25 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
             </ThemeIcon>
             <Title order={3} mb="xs">You&apos;re All Set!</Title>
             <Text c="dimmed" mb="lg" maw={400} mx="auto">
-              Your organization is configured and ready to go. You can always update your accounts,
-              assessment groups, and budgets from the sidebar navigation.
+              Your organization is configured and ready to go. The next step is to set up your annual
+              budget — we&apos;ll take you straight to Budget Planning.
             </Text>
-            <SimpleGrid cols={3} mb="xl" maw={500} mx="auto">
+            <SimpleGrid cols={4} mb="xl" maw={600} mx="auto">
               <Card withBorder p="sm" style={{ textAlign: 'center' }}>
                 <ThemeIcon size={32} color="blue" variant="light" radius="xl" mx="auto" mb={4}>
                   <IconBuildingBank size={16} />
                 </ThemeIcon>
                 <Badge color="green" size="sm">Done</Badge>
-                <Text size="xs" mt={4}>Account</Text>
+                <Text size="xs" mt={4}>Operating</Text>
+              </Card>
+              <Card withBorder p="sm" style={{ textAlign: 'center' }}>
+                <ThemeIcon size={32} color="violet" variant="light" radius="xl" mx="auto" mb={4}>
+                  <IconPigMoney size={16} />
+                </ThemeIcon>
+                <Badge color={reserveSkipped ? 'gray' : 'green'} size="sm">
+                  {reserveSkipped ? 'Skipped' : 'Done'}
+                </Badge>
+                <Text size="xs" mt={4}>Reserve</Text>
               </Card>
               <Card withBorder p="sm" style={{ textAlign: 'center' }}>
                 <ThemeIcon size={32} color="blue" variant="light" radius="xl" mx="auto" mb={4}>
@@ -602,24 +655,30 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
                 <Text size="xs" mt={4}>Assessments</Text>
               </Card>
               <Card withBorder p="sm" style={{ textAlign: 'center' }}>
-                <ThemeIcon size={32} color="blue" variant="light" radius="xl" mx="auto" mb={4}>
+                <ThemeIcon size={32} color="cyan" variant="light" radius="xl" mx="auto" mb={4}>
                   <IconFileSpreadsheet size={16} />
                 </ThemeIcon>
-                <Badge color={budgetUploaded ? 'green' : 'yellow'} size="sm">
-                  {budgetUploaded ? 'Done' : 'Skipped'}
-                </Badge>
+                <Badge color="cyan" size="sm">Up Next</Badge>
                 <Text size="xs" mt={4}>Budget</Text>
               </Card>
             </SimpleGrid>
+            <Alert icon={<IconFileSpreadsheet size={16} />} color="blue" variant="light" mb="lg" ta="left">
+              <Text size="sm" fw={500} mb={4}>Set Up Your Budget</Text>
+              <Text size="sm" c="dimmed">
+                Your budget is critical for accurate financial health scores, cash flow forecasting,
+                and investment planning. Click below to go directly to Budget Planning where you can
+                download a CSV template, fill in your monthly amounts, and upload your budget.
+              </Text>
+            </Alert>
             <Button
               size="lg"
               onClick={handleFinish}
               loading={loading}
-              leftSection={<IconRocket size={18} />}
+              leftSection={<IconFileSpreadsheet size={18} />}
               variant="gradient"
               gradient={{ from: 'blue', to: 'cyan' }}
             >
-              Start Using LedgerIQ
+              Set Up My Budget
             </Button>
           </Card>
         )}
@@ -627,16 +686,11 @@ export function OnboardingWizard({ opened, onComplete }: OnboardingWizardProps)
         {/* ── Navigation Buttons ── */}
         {active < 3 && (
           <Group justify="flex-end" mt="xl">
-            {active === 2 && !budgetUploaded && (
-              <Button variant="subtle" onClick={nextStep}>
-                Skip for now
-              </Button>
-            )}
             <Button
               onClick={nextStep}
               disabled={!canGoNext()}
             >
-              {active === 2 ? (budgetUploaded ? 'Continue' : '') : 'Next Step'}
+              Next Step
             </Button>
           </Group>
         )}

frontend/src/pages/accounts/AccountsPage.tsx

@@ -37,10 +37,11 @@ import {
   IconStarFilled,
   IconAdjustments,
   IconInfoCircle,
+  IconArrowsTransferDown,
 } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 const INVESTMENT_TYPES = ['inv_cd', 'inv_money_market', 'inv_treasury', 'inv_savings', 'inv_brokerage'];
 
@@ -126,8 +127,9 @@ export function AccountsPage() {
   const [search, setSearch] = useState('');
   const [filterType, setFilterType] = useState<string | null>(null);
   const [showArchived, setShowArchived] = useState(false);
+  const [transferOpened, { open: openTransfer, close: closeTransfer }] = useDisclosure(false);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.FINANCIALS_ACCOUNTS_EDIT);
 
   // ── Accounts query ──
   const { data: accounts = [], isLoading } = useQuery<Account[]>({
@@ -283,6 +285,39 @@ export function AccountsPage() {
     },
   });
 
+  // ── Transfer form ──
+  const transferForm = useForm({
+    initialValues: {
+      fromAccountId: '',
+      toAccountId: '',
+      amount: 0,
+      transferDate: new Date() as Date | null,
+      memo: '',
+    },
+    validate: {
+      fromAccountId: (v) => (v ? null : 'Required'),
+      toAccountId: (v, values) => !v ? 'Required' : v === values.fromAccountId ? 'Must be different from source' : null,
+      amount: (v) => (v > 0 ? null : 'Must be greater than 0'),
+      transferDate: (v) => (v ? null : 'Required'),
+    },
+  });
+
+  const transferMutation = useMutation({
+    mutationFn: (values: { fromAccountId: string; toAccountId: string; amount: number; transferDate: string; memo: string }) =>
+      api.post('/accounts/transfer', values),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['accounts'] });
+      queryClient.invalidateQueries({ queryKey: ['trial-balance'] });
+      queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+      notifications.show({ message: 'Transfer completed successfully', color: 'green' });
+      closeTransfer();
+      transferForm.reset();
+    },
+    onError: (err: any) => {
+      notifications.show({ message: err.response?.data?.message || 'Transfer failed', color: 'red' });
+    },
+  });
+
   // ── Investment edit form ──
   const invForm = useForm({
     initialValues: {
@@ -408,6 +443,9 @@ export function AccountsPage() {
   const activeAccounts = filtered.filter((a) => a.is_active);
   const archivedAccounts = filtered.filter((a) => !a.is_active);
 
+  // Asset accounts for transfer modal (all active asset accounts, not just filtered by search)
+  const assetAccounts = accounts.filter((a) => a.is_active && !a.is_system && a.account_type === 'asset');
+
   // ── Investments split by fund type ──
   const operatingInvestments = investments.filter((i) => i.fund_type === 'operating' && i.is_active);
   const reserveInvestments = investments.filter((i) => i.fund_type === 'reserve' && i.is_active);
@@ -505,9 +543,14 @@ export function AccountsPage() {
             size="sm"
           />
           {!isReadOnly && (
-            <Button leftSection={<IconPlus size={16} />} onClick={handleNew}>
-              Add Account
-            </Button>
+            <>
+              <Button variant="light" leftSection={<IconArrowsTransferDown size={16} />} onClick={openTransfer}>
+                Transfer Funds
+              </Button>
+              <Button leftSection={<IconPlus size={16} />} onClick={handleNew}>
+                Add Account
+              </Button>
+            </>
           )}
         </Group>
       </Group>
@@ -854,6 +897,69 @@ export function AccountsPage() {
         )}
       </Modal>
 
+      {/* Transfer Funds Modal */}
+      <Modal opened={transferOpened} onClose={closeTransfer} title="Transfer Funds Between Accounts" size="md" closeOnClickOutside={false}>
+        <form onSubmit={transferForm.onSubmit((values) => {
+          transferMutation.mutate({
+            ...values,
+            transferDate: values.transferDate ? values.transferDate.toISOString().split('T')[0] : new Date().toISOString().split('T')[0],
+          });
+        })}>
+          <Stack>
+            <Alert icon={<IconInfoCircle size={16} />} color="blue" variant="light">
+              This creates a journal entry transferring funds between asset accounts.
+              Both accounts will be updated in the general ledger.
+            </Alert>
+            <Select
+              label="From Account"
+              placeholder="Select source account"
+              required
+              data={assetAccounts.map((a) => ({
+                value: a.id,
+                label: `${a.name} (${a.fund_type}) — ${fmt(a.balance)}`,
+              }))}
+              searchable
+              {...transferForm.getInputProps('fromAccountId')}
+            />
+            <Select
+              label="To Account"
+              placeholder="Select destination account"
+              required
+              data={assetAccounts
+                .filter((a) => a.id !== transferForm.values.fromAccountId)
+                .map((a) => ({
+                  value: a.id,
+                  label: `${a.name} (${a.fund_type}) — ${fmt(a.balance)}`,
+                }))}
+              searchable
+              {...transferForm.getInputProps('toAccountId')}
+            />
+            <NumberInput
+              label="Amount"
+              required
+              prefix="$"
+              decimalScale={2}
+              thousandSeparator=","
+              min={0.01}
+              {...transferForm.getInputProps('amount')}
+            />
+            <DateInput
+              label="Transfer Date"
+              required
+              {...transferForm.getInputProps('transferDate')}
+            />
+            <TextInput
+              label="Memo (optional)"
+              placeholder="e.g. Monthly reserve contribution"
+              {...transferForm.getInputProps('memo')}
+            />
+            <Button type="submit" leftSection={<IconArrowsTransferDown size={16} />} loading={transferMutation.isPending}>
+              Complete Transfer
+            </Button>
+          </Stack>
+        </form>
+      </Modal>
+
       {/* Investment Edit Modal */}
       <Modal opened={invEditOpened} onClose={closeInvEdit} title="Edit Investment Account" size="md" closeOnClickOutside={false}>
         {editingInvestment && (

frontend/src/pages/admin/AdminIdeasPage.tsx

@@ -0,0 +1,308 @@
+import { useState } from 'react';
+import {
+  Title, Text, Card, Table, Group, Stack, Badge, Loader, Center,
+  Select, TextInput, Textarea, Button, Modal, SimpleGrid, ActionIcon,
+  Tooltip, Paper,
+} from '@mantine/core';
+import { useDisclosure } from '@mantine/hooks';
+import { notifications } from '@mantine/notifications';
+import {
+  IconBulb, IconSearch, IconNote, IconFilter,
+} from '@tabler/icons-react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import api from '../../services/api';
+
+interface AdminIdea {
+  id: string;
+  title: string;
+  description: string | null;
+  status: string;
+  createdAt: string;
+  adminNote: string | null;
+  orgId: string;
+  orgName: string;
+  userId: string;
+  userEmail: string;
+  userFirstName: string;
+  userLastName: string;
+}
+
+const statusColor: Record<string, string> = {
+  new: 'blue',
+  reviewed: 'yellow',
+  accepted: 'green',
+  rejected: 'red',
+};
+
+const statusOptions = [
+  { value: 'new', label: 'New' },
+  { value: 'reviewed', label: 'Reviewed' },
+  { value: 'accepted', label: 'Accepted' },
+  { value: 'rejected', label: 'Rejected' },
+];
+
+function formatDate(dateStr: string | null | undefined): string {
+  if (!dateStr) return '—';
+  return new Date(dateStr).toLocaleDateString();
+}
+
+function formatDateTime(dateStr: string | null | undefined): string {
+  if (!dateStr) return '—';
+  return new Date(dateStr).toLocaleString();
+}
+
+export function AdminIdeasPage() {
+  const [search, setSearch] = useState('');
+  const [statusFilter, setStatusFilter] = useState<string | null>(null);
+  const [selectedIdea, setSelectedIdea] = useState<AdminIdea | null>(null);
+  const [detailOpened, { open: openDetail, close: closeDetail }] = useDisclosure(false);
+  const [noteText, setNoteText] = useState('');
+  const queryClient = useQueryClient();
+
+  const { data: ideas, isLoading } = useQuery<AdminIdea[]>({
+    queryKey: ['admin-ideas'],
+    queryFn: async () => { const { data } = await api.get('/admin/ideas'); return data; },
+  });
+
+  const updateStatus = useMutation({
+    mutationFn: async ({ id, status }: { id: string; status: string }) => {
+      await api.put(`/admin/ideas/${id}/status`, { status });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin-ideas'] });
+      notifications.show({ message: 'Status updated', color: 'green' });
+    },
+  });
+
+  const updateNote = useMutation({
+    mutationFn: async ({ id, adminNote }: { id: string; adminNote: string }) => {
+      await api.put(`/admin/ideas/${id}/note`, { adminNote });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin-ideas'] });
+      notifications.show({ message: 'Note saved', color: 'green' });
+    },
+  });
+
+  const openIdeaDetail = (idea: AdminIdea) => {
+    setSelectedIdea(idea);
+    setNoteText(idea.adminNote || '');
+    openDetail();
+  };
+
+  const handleSaveNote = () => {
+    if (selectedIdea) {
+      updateNote.mutate({ id: selectedIdea.id, adminNote: noteText });
+    }
+  };
+
+  const filtered = (ideas || []).filter((idea) => {
+    const matchesSearch = !search ||
+      idea.title.toLowerCase().includes(search.toLowerCase()) ||
+      idea.description?.toLowerCase().includes(search.toLowerCase()) ||
+      idea.orgName.toLowerCase().includes(search.toLowerCase()) ||
+      idea.userEmail.toLowerCase().includes(search.toLowerCase());
+    const matchesStatus = !statusFilter || idea.status === statusFilter;
+    return matchesSearch && matchesStatus;
+  });
+
+  const counts = {
+    total: ideas?.length || 0,
+    new: ideas?.filter(i => i.status === 'new').length || 0,
+    reviewed: ideas?.filter(i => i.status === 'reviewed').length || 0,
+    accepted: ideas?.filter(i => i.status === 'accepted').length || 0,
+    rejected: ideas?.filter(i => i.status === 'rejected').length || 0,
+  };
+
+  if (isLoading) {
+    return <Center h={400}><Loader /></Center>;
+  }
+
+  return (
+    <Stack>
+      <Group justify="space-between">
+        <Group>
+          <IconBulb size={28} />
+          <Title order={2}>Idea Submissions</Title>
+        </Group>
+        <Badge size="lg" variant="light">{counts.total} total</Badge>
+      </Group>
+
+      {/* Summary cards */}
+      <SimpleGrid cols={{ base: 2, sm: 4 }}>
+        <Paper withBorder p="md" radius="md">
+          <Text size="xs" c="dimmed" tt="uppercase" fw={700}>New</Text>
+          <Text size="xl" fw={700} c="blue">{counts.new}</Text>
+        </Paper>
+        <Paper withBorder p="md" radius="md">
+          <Text size="xs" c="dimmed" tt="uppercase" fw={700}>Reviewed</Text>
+          <Text size="xl" fw={700} c="yellow">{counts.reviewed}</Text>
+        </Paper>
+        <Paper withBorder p="md" radius="md">
+          <Text size="xs" c="dimmed" tt="uppercase" fw={700}>Accepted</Text>
+          <Text size="xl" fw={700} c="green">{counts.accepted}</Text>
+        </Paper>
+        <Paper withBorder p="md" radius="md">
+          <Text size="xs" c="dimmed" tt="uppercase" fw={700}>Rejected</Text>
+          <Text size="xl" fw={700} c="red">{counts.rejected}</Text>
+        </Paper>
+      </SimpleGrid>
+
+      {/* Filters */}
+      <Group>
+        <TextInput
+          placeholder="Search ideas, tenants, users..."
+          leftSection={<IconSearch size={16} />}
+          value={search}
+          onChange={(e) => setSearch(e.currentTarget.value)}
+          style={{ flex: 1 }}
+        />
+        <Select
+          placeholder="All statuses"
+          leftSection={<IconFilter size={16} />}
+          data={statusOptions}
+          value={statusFilter}
+          onChange={setStatusFilter}
+          clearable
+          w={160}
+        />
+      </Group>
+
+      {/* Ideas table */}
+      <Card withBorder p={0}>
+        <Table striped highlightOnHover>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th>Date</Table.Th>
+              <Table.Th>Tenant</Table.Th>
+              <Table.Th>Submitted By</Table.Th>
+              <Table.Th>Title</Table.Th>
+              <Table.Th>Status</Table.Th>
+              <Table.Th w={40}></Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {filtered.length === 0 ? (
+              <Table.Tr>
+                <Table.Td colSpan={6}>
+                  <Text ta="center" c="dimmed" py="lg">
+                    {ideas?.length === 0 ? 'No ideas submitted yet' : 'No ideas match your filters'}
+                  </Text>
+                </Table.Td>
+              </Table.Tr>
+            ) : (
+              filtered.map((idea) => (
+                <Table.Tr
+                  key={idea.id}
+                  style={{ cursor: 'pointer' }}
+                  onClick={() => openIdeaDetail(idea)}
+                >
+                  <Table.Td>
+                    <Text size="xs">{formatDate(idea.createdAt)}</Text>
+                  </Table.Td>
+                  <Table.Td>
+                    <Text size="sm" fw={500}>{idea.orgName}</Text>
+                  </Table.Td>
+                  <Table.Td>
+                    <Text size="sm">{idea.userFirstName} {idea.userLastName}</Text>
+                    <Text size="xs" c="dimmed">{idea.userEmail}</Text>
+                  </Table.Td>
+                  <Table.Td>
+                    <Text size="sm" fw={500} lineClamp={1}>{idea.title}</Text>
+                  </Table.Td>
+                  <Table.Td>
+                    <Badge size="sm" variant="light" color={statusColor[idea.status]}>
+                      {idea.status}
+                    </Badge>
+                  </Table.Td>
+                  <Table.Td>
+                    {idea.adminNote && (
+                      <Tooltip label="Has admin note">
+                        <IconNote size={16} color="gray" />
+                      </Tooltip>
+                    )}
+                  </Table.Td>
+                </Table.Tr>
+              ))
+            )}
+          </Table.Tbody>
+        </Table>
+      </Card>
+
+      {/* Detail Modal */}
+      <Modal
+        opened={detailOpened}
+        onClose={closeDetail}
+        title={<Text fw={600}>Idea Detail</Text>}
+        size="lg"
+      >
+        {selectedIdea && (
+          <Stack>
+            <Card withBorder>
+              <SimpleGrid cols={2} spacing="xs">
+                <Text size="xs" c="dimmed">Tenant</Text>
+                <Text size="sm" fw={500}>{selectedIdea.orgName}</Text>
+                <Text size="xs" c="dimmed">Submitted By</Text>
+                <Text size="sm">{selectedIdea.userFirstName} {selectedIdea.userLastName} ({selectedIdea.userEmail})</Text>
+                <Text size="xs" c="dimmed">Date</Text>
+                <Text size="sm">{formatDateTime(selectedIdea.createdAt)}</Text>
+              </SimpleGrid>
+            </Card>
+
+            <Card withBorder>
+              <Text fw={600} mb="xs">Title</Text>
+              <Text size="sm">{selectedIdea.title}</Text>
+              {selectedIdea.description && (
+                <>
+                  <Text fw={600} mt="md" mb="xs">Description</Text>
+                  <Text size="sm" style={{ whiteSpace: 'pre-wrap' }}>{selectedIdea.description}</Text>
+                </>
+              )}
+            </Card>
+
+            <Card withBorder>
+              <Text fw={600} mb="xs">Status</Text>
+              <Select
+                data={statusOptions}
+                value={selectedIdea.status}
+                onChange={(val) => {
+                  if (val && val !== selectedIdea.status) {
+                    updateStatus.mutate({ id: selectedIdea.id, status: val }, {
+                      onSuccess: () => {
+                        setSelectedIdea({ ...selectedIdea, status: val });
+                      },
+                    });
+                  }
+                }}
+                w={200}
+              />
+            </Card>
+
+            <Card withBorder>
+              <Group justify="space-between" mb="xs">
+                <Text fw={600}>Private Admin Note</Text>
+                <Text size="xs" c="dimmed">Only visible to super admins</Text>
+              </Group>
+              <Textarea
+                placeholder="Add internal notes — sprint reference, thoughts, follow-up actions..."
+                minRows={3}
+                value={noteText}
+                onChange={(e) => setNoteText(e.currentTarget.value)}
+              />
+              <Button
+                size="xs"
+                variant="light"
+                mt="xs"
+                onClick={handleSaveNote}
+                loading={updateNote.isPending}
+                disabled={noteText === (selectedIdea.adminNote || '')}
+              >
+                Save Note
+              </Button>
+            </Card>
+          </Stack>
+        )}
+      </Modal>
+    </Stack>
+  );
+}

frontend/src/pages/admin/AdminPage.tsx

@@ -11,7 +11,7 @@ import {
   IconCrown, IconPlus, IconArchive, IconChevronDown,
   IconCircleCheck, IconBan, IconArchiveOff, IconDashboard,
   IconHeartRateMonitor, IconSparkles, IconCalendar, IconActivity,
-  IconCurrencyDollar, IconClipboardCheck, IconLogin, IconEye,
+  IconCurrencyDollar, IconClipboardCheck, IconLogin, IconEye, IconBulb,
 } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { useNavigate } from 'react-router-dom';
@@ -211,6 +211,16 @@ export function AdminPage() {
     },
   });
 
+  const toggleIdeation = useMutation({
+    mutationFn: async ({ orgId, enabled }: { orgId: string; enabled: boolean }) => {
+      await api.put(`/admin/organizations/${orgId}/settings`, { ideationEnabled: enabled });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin-tenant-detail', selectedOrgId] });
+      queryClient.invalidateQueries({ queryKey: ['admin-orgs'] });
+    },
+  });
+
   const impersonateUser = useMutation({
     mutationFn: async (userId: string) => {
       const { data } = await api.post(`/admin/impersonate/${userId}`);
@@ -782,6 +792,27 @@ export function AdminPage() {
               </SimpleGrid>
             </Card>
 
+            <Card withBorder>
+              <Text fw={600} mb="xs">Feature Toggles</Text>
+              <Group justify="space-between">
+                <Group gap="xs">
+                  <IconBulb size={16} />
+                  <div>
+                    <Text size="sm">Ideation</Text>
+                    <Text size="xs" c="dimmed">Allow users to submit feature ideas</Text>
+                  </div>
+                </Group>
+                <Switch
+                  checked={tenantDetail.organization.settings?.ideationEnabled === true}
+                  onChange={(e) => {
+                    if (selectedOrgId) {
+                      toggleIdeation.mutate({ orgId: selectedOrgId, enabled: e.currentTarget.checked });
+                    }
+                  }}
+                />
+              </Group>
+            </Card>
+
             <Card withBorder>
               <Text fw={600} mb="xs">Subscription</Text>
               <Stack gap="xs">

frontend/src/pages/admin/AdminShadowAiPage.tsx

@@ -0,0 +1,780 @@
+import { useState, useEffect } from 'react';
+import {
+  Title, Text, Card, SimpleGrid, Group, Stack, Badge, Loader, Center,
+  Tabs, TextInput, Button, PasswordInput, Select, Table, Accordion,
+  Switch, Paper, RingProgress, Divider, Alert, Code, ScrollArea, Box,
+  Tooltip, ActionIcon,
+} from '@mantine/core';
+import {
+  IconScale, IconSettings, IconPlayerPlay, IconHistory,
+  IconCheck, IconX, IconAlertTriangle, IconClock, IconTrash,
+  IconRefresh, IconArrowRight, IconChevronDown,
+} from '@tabler/icons-react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import api from '../../services/api';
+
+// ── Interfaces ──
+
+interface ShadowModel {
+  id: string;
+  slot: string;
+  name: string;
+  api_url: string;
+  api_key: string;
+  model_name: string;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+interface ShadowRunResult {
+  id: string;
+  run_id: string;
+  model_role: string;
+  model_name: string;
+  api_url: string;
+  raw_response: string;
+  parsed_response: any;
+  response_time_ms: number;
+  token_usage: any;
+  status: string;
+  error_message: string;
+  created_at: string;
+}
+
+interface ShadowRun {
+  id: string;
+  tenant_id: string;
+  tenant_name: string;
+  feature: string;
+  status: string;
+  prompt_messages: any;
+  started_at: string;
+  completed_at: string;
+  created_at: string;
+  results: ShadowRunResult[];
+  result_count?: string;
+  success_count?: string;
+}
+
+interface AdminOrg {
+  id: string;
+  name: string;
+  status: string;
+}
+
+// ── Helper Functions ──
+
+const featureLabels: Record<string, string> = {
+  operating_health: 'Operating Health',
+  reserve_health: 'Reserve Health',
+  investment_recommendations: 'Investment Recommendations',
+};
+
+const roleLabels: Record<string, string> = {
+  production: 'Production',
+  alternate_a: 'Alternate A',
+  alternate_b: 'Alternate B',
+};
+
+const statusColor: Record<string, string> = {
+  running: 'blue',
+  completed: 'green',
+  partial: 'yellow',
+  failed: 'red',
+  pending: 'gray',
+  success: 'green',
+  error: 'red',
+};
+
+function formatDuration(ms: number | null): string {
+  if (!ms) return '-';
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function formatDate(d: string): string {
+  if (!d) return '-';
+  return new Date(d).toLocaleString();
+}
+
+// ── Model Configuration Tab ──
+
+function ModelConfigTab() {
+  const queryClient = useQueryClient();
+  const { data: models, isLoading } = useQuery<ShadowModel[]>({
+    queryKey: ['shadow-ai-models'],
+    queryFn: () => api.get('/admin/shadow-ai/models').then((r) => r.data),
+  });
+
+  const modelA = models?.find((m) => m.slot === 'A');
+  const modelB = models?.find((m) => m.slot === 'B');
+
+  return (
+    <Stack>
+      <Text size="sm" c="dimmed">
+        Configure alternate AI models to benchmark against the production model.
+        Each model can use any OpenAI-compatible API endpoint.
+      </Text>
+      <SimpleGrid cols={{ base: 1, md: 3 }}>
+        <ProductionModelCard />
+        <ModelSlotCard slot="A" model={modelA} isLoading={isLoading} />
+        <ModelSlotCard slot="B" model={modelB} isLoading={isLoading} />
+      </SimpleGrid>
+    </Stack>
+  );
+}
+
+function ProductionModelCard() {
+  return (
+    <Card withBorder shadow="sm">
+      <Stack gap="sm">
+        <Group justify="space-between">
+          <Text fw={600}>Production Model</Text>
+          <Badge color="green" variant="light">Active</Badge>
+        </Group>
+        <Divider />
+        <Text size="sm" c="dimmed">Configured via environment variables</Text>
+        <TextInput label="Model" value="(from AI_MODEL env var)" readOnly disabled size="sm" />
+        <TextInput label="API URL" value="(from AI_API_URL env var)" readOnly disabled size="sm" />
+        <Text size="xs" c="dimmed" mt="xs">
+          Production model settings are managed through server environment
+          variables and cannot be changed from the UI.
+        </Text>
+      </Stack>
+    </Card>
+  );
+}
+
+function ModelSlotCard({ slot, model, isLoading }: { slot: string; model?: ShadowModel; isLoading: boolean }) {
+  const queryClient = useQueryClient();
+  const [name, setName] = useState('');
+  const [apiUrl, setApiUrl] = useState('');
+  const [apiKey, setApiKey] = useState('');
+  const [modelName, setModelName] = useState('');
+  const [isActive, setIsActive] = useState(true);
+
+  useEffect(() => {
+    if (model) {
+      setName(model.name);
+      setApiUrl(model.api_url);
+      setApiKey(model.api_key);
+      setModelName(model.model_name);
+      setIsActive(model.is_active);
+    }
+  }, [model]);
+
+  const saveMutation = useMutation({
+    mutationFn: () => api.put(`/admin/shadow-ai/models/${slot}`, { name, apiUrl, apiKey, modelName, isActive }),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['shadow-ai-models'] }),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: () => api.delete(`/admin/shadow-ai/models/${slot}`),
+    onSuccess: () => {
+      setName(''); setApiUrl(''); setApiKey(''); setModelName(''); setIsActive(true);
+      queryClient.invalidateQueries({ queryKey: ['shadow-ai-models'] });
+    },
+  });
+
+  if (isLoading) return <Card withBorder shadow="sm"><Center h={200}><Loader size="sm" /></Center></Card>;
+
+  return (
+    <Card withBorder shadow="sm">
+      <Stack gap="sm">
+        <Group justify="space-between">
+          <Text fw={600}>Alternate {slot}</Text>
+          {model ? (
+            <Badge color={isActive ? 'blue' : 'gray'} variant="light">
+              {isActive ? 'Active' : 'Inactive'}
+            </Badge>
+          ) : (
+            <Badge color="gray" variant="light">Not configured</Badge>
+          )}
+        </Group>
+        <Divider />
+        <TextInput label="Display Name" placeholder="e.g. GPT-4o" value={name} onChange={(e) => setName(e.target.value)} size="sm" />
+        <TextInput label="API URL" description="Base URL only — /chat/completions is added automatically" placeholder="https://openrouter.ai/api/v1" value={apiUrl} onChange={(e) => setApiUrl(e.target.value)} size="sm" />
+        <PasswordInput label="API Key" placeholder="sk-..." value={apiKey} onChange={(e) => setApiKey(e.target.value)} size="sm" />
+        <TextInput label="Model Name" placeholder="gpt-4o" value={modelName} onChange={(e) => setModelName(e.target.value)} size="sm" />
+        <Switch label="Active" checked={isActive} onChange={(e) => setIsActive(e.currentTarget.checked)} />
+        <Group>
+          <Button
+            size="sm"
+            onClick={() => saveMutation.mutate()}
+            loading={saveMutation.isPending}
+            disabled={!name || !apiUrl || !apiKey || !modelName}
+          >
+            Save
+          </Button>
+          {model && (
+            <Button size="sm" color="red" variant="light" onClick={() => deleteMutation.mutate()} loading={deleteMutation.isPending}>
+              <IconTrash size={16} />
+            </Button>
+          )}
+        </Group>
+        {saveMutation.isError && <Text size="xs" c="red">Failed to save</Text>}
+        {saveMutation.isSuccess && <Text size="xs" c="green">Saved</Text>}
+      </Stack>
+    </Card>
+  );
+}
+
+// ── Run Comparison Tab ──
+
+function RunComparisonTab() {
+  const queryClient = useQueryClient();
+  const [tenantId, setTenantId] = useState<string | null>(null);
+  const [feature, setFeature] = useState<string | null>(null);
+  const [activeRunId, setActiveRunId] = useState<string | null>(null);
+
+  const { data: orgs } = useQuery<AdminOrg[]>({
+    queryKey: ['admin-orgs'],
+    queryFn: () => api.get('/admin/organizations').then((r) => r.data),
+  });
+
+  const triggerMutation = useMutation({
+    mutationFn: () => api.post('/admin/shadow-ai/runs', { tenantId, feature }),
+    onSuccess: (res) => {
+      setActiveRunId(res.data.runId);
+    },
+  });
+
+  const { data: activeRun } = useQuery<ShadowRun>({
+    queryKey: ['shadow-ai-run', activeRunId],
+    queryFn: () => api.get(`/admin/shadow-ai/runs/${activeRunId}`).then((r) => r.data),
+    enabled: !!activeRunId,
+    refetchInterval: (query) => {
+      const run = query.state.data;
+      return run?.status === 'running' ? 3000 : false;
+    },
+  });
+
+  const orgOptions = (orgs || [])
+    .filter((o) => o.status === 'active')
+    .map((o) => ({ value: o.id, label: o.name }));
+
+  const featureOptions = [
+    { value: 'operating_health', label: 'Operating Health Score' },
+    { value: 'reserve_health', label: 'Reserve Health Score' },
+    { value: 'investment_recommendations', label: 'Investment Recommendations' },
+  ];
+
+  return (
+    <Stack>
+      <Card withBorder shadow="sm">
+        <Stack gap="md">
+          <Text fw={600}>Run Shadow Comparison</Text>
+          <SimpleGrid cols={{ base: 1, sm: 3 }}>
+            <Select
+              label="Tenant"
+              placeholder="Select a tenant"
+              data={orgOptions}
+              value={tenantId}
+              onChange={setTenantId}
+              searchable
+            />
+            <Select
+              label="AI Feature"
+              placeholder="Select feature"
+              data={featureOptions}
+              value={feature}
+              onChange={setFeature}
+            />
+            <Stack justify="flex-end">
+              <Button
+                leftSection={<IconPlayerPlay size={16} />}
+                onClick={() => triggerMutation.mutate()}
+                loading={triggerMutation.isPending}
+                disabled={!tenantId || !feature}
+              >
+                Run Comparison
+              </Button>
+            </Stack>
+          </SimpleGrid>
+          {triggerMutation.isError && (
+            <Alert color="red" icon={<IconAlertTriangle size={16} />}>
+              Failed to start comparison. Ensure at least one alternate model is configured.
+            </Alert>
+          )}
+        </Stack>
+      </Card>
+
+      {activeRun && (
+        <Card withBorder shadow="sm">
+          <Stack gap="md">
+            <Group justify="space-between">
+              <Group>
+                <Text fw={600}>
+                  {featureLabels[activeRun.feature] || activeRun.feature}
+                </Text>
+                <Badge color={statusColor[activeRun.status]}>{activeRun.status}</Badge>
+              </Group>
+              {activeRun.tenant_name && (
+                <Text size="sm" c="dimmed">Tenant: {activeRun.tenant_name}</Text>
+              )}
+            </Group>
+
+            {activeRun.status === 'running' && (
+              <Center py="md">
+                <Stack align="center" gap="xs">
+                  <Loader size="md" />
+                  <Text size="sm" c="dimmed">Running models... This may take a few minutes.</Text>
+                  <Group gap="xs">
+                    {(activeRun.results || []).map((r) => (
+                      <Badge key={r.model_role} color={statusColor[r.status]} variant="light">
+                        {roleLabels[r.model_role]}: {r.status}
+                      </Badge>
+                    ))}
+                  </Group>
+                </Stack>
+              </Center>
+            )}
+
+            {activeRun.status !== 'running' && activeRun.results && (
+              <ComparisonResults results={activeRun.results} feature={activeRun.feature} />
+            )}
+          </Stack>
+        </Card>
+      )}
+    </Stack>
+  );
+}
+
+// ── History Tab ──
+
+function HistoryTab() {
+  const [selectedRunId, setSelectedRunId] = useState<string | null>(null);
+  const [tenantFilter, setTenantFilter] = useState<string | null>(null);
+  const [featureFilter, setFeatureFilter] = useState<string | null>(null);
+
+  const { data: orgs } = useQuery<AdminOrg[]>({
+    queryKey: ['admin-orgs'],
+    queryFn: () => api.get('/admin/organizations').then((r) => r.data),
+  });
+
+  const { data: historyData, isLoading } = useQuery({
+    queryKey: ['shadow-ai-runs', tenantFilter, featureFilter],
+    queryFn: () => {
+      const params = new URLSearchParams();
+      if (tenantFilter) params.set('tenantId', tenantFilter);
+      if (featureFilter) params.set('feature', featureFilter);
+      params.set('limit', '50');
+      return api.get(`/admin/shadow-ai/runs?${params}`).then((r) => r.data);
+    },
+  });
+
+  const { data: selectedRun } = useQuery<ShadowRun>({
+    queryKey: ['shadow-ai-run', selectedRunId],
+    queryFn: () => api.get(`/admin/shadow-ai/runs/${selectedRunId}`).then((r) => r.data),
+    enabled: !!selectedRunId,
+  });
+
+  const orgOptions = [
+    { value: '', label: 'All Tenants' },
+    ...(orgs || []).map((o) => ({ value: o.id, label: o.name })),
+  ];
+
+  const featureOptions = [
+    { value: '', label: 'All Features' },
+    { value: 'operating_health', label: 'Operating Health' },
+    { value: 'reserve_health', label: 'Reserve Health' },
+    { value: 'investment_recommendations', label: 'Investment Recommendations' },
+  ];
+
+  const runs: ShadowRun[] = historyData?.runs || [];
+
+  return (
+    <Stack>
+      <Group>
+        <Select
+          size="sm"
+          placeholder="Filter by tenant"
+          data={orgOptions}
+          value={tenantFilter || ''}
+          onChange={(v) => setTenantFilter(v || null)}
+          clearable
+          w={200}
+        />
+        <Select
+          size="sm"
+          placeholder="Filter by feature"
+          data={featureOptions}
+          value={featureFilter || ''}
+          onChange={(v) => setFeatureFilter(v || null)}
+          clearable
+          w={200}
+        />
+      </Group>
+
+      {isLoading ? (
+        <Center py="xl"><Loader /></Center>
+      ) : runs.length === 0 ? (
+        <Text c="dimmed" ta="center" py="xl">No shadow runs found.</Text>
+      ) : (
+        <Table striped highlightOnHover>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th>Date</Table.Th>
+              <Table.Th>Tenant</Table.Th>
+              <Table.Th>Feature</Table.Th>
+              <Table.Th>Status</Table.Th>
+              <Table.Th>Models</Table.Th>
+              <Table.Th>Duration</Table.Th>
+              <Table.Th></Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {runs.map((run) => {
+              const duration = run.completed_at && run.started_at
+                ? new Date(run.completed_at).getTime() - new Date(run.started_at).getTime()
+                : null;
+              return (
+                <Table.Tr
+                  key={run.id}
+                  style={{ cursor: 'pointer' }}
+                  onClick={() => setSelectedRunId(run.id)}
+                  bg={selectedRunId === run.id ? 'var(--mantine-color-blue-light)' : undefined}
+                >
+                  <Table.Td>{formatDate(run.created_at)}</Table.Td>
+                  <Table.Td>{run.tenant_name || '-'}</Table.Td>
+                  <Table.Td>{featureLabels[run.feature] || run.feature}</Table.Td>
+                  <Table.Td><Badge color={statusColor[run.status]} size="sm">{run.status}</Badge></Table.Td>
+                  <Table.Td>{run.success_count || '0'}/{run.result_count || '0'}</Table.Td>
+                  <Table.Td>{formatDuration(duration)}</Table.Td>
+                  <Table.Td><IconArrowRight size={14} /></Table.Td>
+                </Table.Tr>
+              );
+            })}
+          </Table.Tbody>
+        </Table>
+      )}
+
+      {selectedRun && selectedRun.results && (
+        <Card withBorder shadow="sm" mt="md">
+          <Stack gap="md">
+            <Group justify="space-between">
+              <Group>
+                <Text fw={600}>{featureLabels[selectedRun.feature] || selectedRun.feature}</Text>
+                <Badge color={statusColor[selectedRun.status]}>{selectedRun.status}</Badge>
+              </Group>
+              <Text size="sm" c="dimmed">
+                {selectedRun.tenant_name} | {formatDate(selectedRun.created_at)}
+              </Text>
+            </Group>
+            <ComparisonResults results={selectedRun.results} feature={selectedRun.feature} />
+          </Stack>
+        </Card>
+      )}
+    </Stack>
+  );
+}
+
+// ── Comparison Results Component ──
+
+function ComparisonResults({ results, feature }: { results: ShadowRunResult[]; feature: string }) {
+  const isHealthScore = feature === 'operating_health' || feature === 'reserve_health';
+
+  // Collect all parsed values for diff highlighting
+  const parsedValues = results
+    .filter((r) => r.status === 'success' && r.parsed_response)
+    .map((r) => r.parsed_response);
+
+  return (
+    <SimpleGrid cols={{ base: 1, md: Math.min(results.length, 3) }}>
+      {results.map((result) => (
+        <ResultCard
+          key={result.model_role}
+          result={result}
+          isHealthScore={isHealthScore}
+          allParsed={parsedValues}
+        />
+      ))}
+    </SimpleGrid>
+  );
+}
+
+function ResultCard({
+  result,
+  isHealthScore,
+  allParsed,
+}: {
+  result: ShadowRunResult;
+  isHealthScore: boolean;
+  allParsed: any[];
+}) {
+  const roleColor: Record<string, string> = {
+    production: 'green',
+    alternate_a: 'blue',
+    alternate_b: 'violet',
+  };
+
+  return (
+    <Card withBorder shadow="xs" padding="md">
+      <Stack gap="sm">
+        <Group justify="space-between">
+          <Group gap="xs">
+            <Badge color={roleColor[result.model_role] || 'gray'} variant="filled">
+              {roleLabels[result.model_role]}
+            </Badge>
+          </Group>
+          <Badge
+            color={statusColor[result.status]}
+            variant="light"
+            leftSection={result.status === 'success' ? <IconCheck size={12} /> : result.status === 'error' ? <IconX size={12} /> : <IconClock size={12} />}
+          >
+            {result.status}
+          </Badge>
+        </Group>
+
+        <Text size="xs" c="dimmed" truncate>{result.model_name}</Text>
+
+        {result.response_time_ms && (
+          <Badge color="gray" variant="light" size="sm">
+            {formatDuration(result.response_time_ms)}
+          </Badge>
+        )}
+
+        {result.token_usage && (
+          <Text size="xs" c="dimmed">
+            Tokens: {result.token_usage.prompt_tokens || '?'} prompt / {result.token_usage.completion_tokens || '?'} completion
+          </Text>
+        )}
+
+        <Divider />
+
+        {result.status === 'error' && (
+          <Alert color="red" icon={<IconAlertTriangle size={16} />}>
+            <Text size="sm">{result.error_message || 'Unknown error'}</Text>
+          </Alert>
+        )}
+
+        {result.status === 'success' && result.parsed_response && (
+          isHealthScore
+            ? <HealthScoreDisplay data={result.parsed_response} allParsed={allParsed} />
+            : <InvestmentDisplay data={result.parsed_response} allParsed={allParsed} />
+        )}
+
+        {result.status === 'success' && (
+          <Accordion variant="contained">
+            <Accordion.Item value="raw">
+              <Accordion.Control>
+                <Text size="xs">Raw JSON Response</Text>
+              </Accordion.Control>
+              <Accordion.Panel>
+                <ScrollArea h={300}>
+                  <Code block style={{ fontSize: 11 }}>
+                    {JSON.stringify(result.parsed_response, null, 2)}
+                  </Code>
+                </ScrollArea>
+              </Accordion.Panel>
+            </Accordion.Item>
+          </Accordion>
+        )}
+      </Stack>
+    </Card>
+  );
+}
+
+// ── Health Score Display ──
+
+function HealthScoreDisplay({ data, allParsed }: { data: any; allParsed: any[] }) {
+  const score = data.score ?? data.raw_text;
+  const label = data.label || '';
+  const summary = data.summary || '';
+  const factors = data.factors || [];
+  const recommendations = data.recommendations || [];
+
+  // Check if score differs from other models
+  const scores = allParsed.map((p) => p.score).filter((s) => typeof s === 'number');
+  const scoreDiffers = scores.length > 1 && !scores.every((s) => s === scores[0]);
+
+  const labelColor: Record<string, string> = {
+    Excellent: 'green', Good: 'teal', Fair: 'yellow',
+    'Needs Attention': 'orange', 'At Risk': 'red', Critical: 'red',
+  };
+
+  return (
+    <Stack gap="sm">
+      {typeof score === 'number' && (
+        <Group justify="center">
+          <Box bg={scoreDiffers ? 'yellow.0' : undefined} p="xs" style={{ borderRadius: 8 }}>
+            <RingProgress
+              size={100}
+              thickness={10}
+              roundCaps
+              sections={[{ value: score, color: labelColor[label] || 'blue' }]}
+              label={
+                <Text ta="center" fw={700} size="lg">{score}</Text>
+              }
+            />
+          </Box>
+        </Group>
+      )}
+
+      {label && (
+        <Group justify="center">
+          <Badge color={labelColor[label] || 'gray'} size="lg">{label}</Badge>
+        </Group>
+      )}
+
+      {summary && <Text size="sm">{summary}</Text>}
+
+      {factors.length > 0 && (
+        <>
+          <Text size="xs" fw={600} c="dimmed" tt="uppercase">Factors</Text>
+          {factors.map((f: any, i: number) => (
+            <Group key={i} gap="xs" wrap="nowrap">
+              <Badge
+                size="xs"
+                variant="light"
+                color={f.impact === 'positive' ? 'green' : f.impact === 'negative' ? 'red' : 'gray'}
+              >
+                {f.impact}
+              </Badge>
+              <Text size="xs" style={{ flex: 1 }}><b>{f.name}:</b> {f.detail}</Text>
+            </Group>
+          ))}
+        </>
+      )}
+
+      {recommendations.length > 0 && (
+        <>
+          <Text size="xs" fw={600} c="dimmed" tt="uppercase">Recommendations</Text>
+          {recommendations.map((r: any, i: number) => (
+            <Group key={i} gap="xs" wrap="nowrap">
+              <Badge
+                size="xs"
+                variant="light"
+                color={r.priority === 'high' ? 'red' : r.priority === 'medium' ? 'yellow' : 'blue'}
+              >
+                {r.priority}
+              </Badge>
+              <Text size="xs" style={{ flex: 1 }}>{r.text}</Text>
+            </Group>
+          ))}
+        </>
+      )}
+    </Stack>
+  );
+}
+
+// ── Investment Display ──
+
+function InvestmentDisplay({ data, allParsed }: { data: any; allParsed: any[] }) {
+  const recommendations = data.recommendations || [];
+  const overall = data.overall_assessment || '';
+  const riskNotes = data.risk_notes || [];
+
+  const recCounts = allParsed.map((p) => (p.recommendations || []).length);
+  const countDiffers = recCounts.length > 1 && !recCounts.every((c) => c === recCounts[0]);
+
+  const typeColors: Record<string, string> = {
+    cd_ladder: 'violet', new_investment: 'blue', reallocation: 'teal',
+    maturity_action: 'orange', liquidity_warning: 'red', general: 'gray',
+  };
+
+  return (
+    <Stack gap="sm">
+      {overall && (
+        <Paper p="xs" bg="gray.0" radius="sm">
+          <Text size="sm">{overall}</Text>
+        </Paper>
+      )}
+
+      {recommendations.length > 0 && (
+        <>
+          <Group gap="xs">
+            <Text size="xs" fw={600} c="dimmed" tt="uppercase">
+              Recommendations
+            </Text>
+            <Badge
+              size="xs"
+              variant="light"
+              color={countDiffers ? 'yellow' : 'gray'}
+            >
+              {recommendations.length}
+            </Badge>
+          </Group>
+          {recommendations.map((rec: any, i: number) => (
+            <Card key={i} withBorder padding="xs" radius="sm">
+              <Stack gap={4}>
+                <Group gap="xs">
+                  <Badge size="xs" color={typeColors[rec.type] || 'gray'}>{rec.type}</Badge>
+                  <Badge size="xs" variant="light" color={rec.priority === 'high' ? 'red' : rec.priority === 'medium' ? 'yellow' : 'blue'}>
+                    {rec.priority}
+                  </Badge>
+                  {rec.fund_type && <Badge size="xs" variant="outline">{rec.fund_type}</Badge>}
+                </Group>
+                <Text size="sm" fw={600}>{rec.title}</Text>
+                <Text size="xs">{rec.summary}</Text>
+                {rec.suggested_amount && (
+                  <Text size="xs" c="dimmed">
+                    Amount: ${rec.suggested_amount.toLocaleString()}
+                    {rec.suggested_rate ? ` | Rate: ${rec.suggested_rate}%` : ''}
+                    {rec.suggested_term ? ` | Term: ${rec.suggested_term}` : ''}
+                  </Text>
+                )}
+              </Stack>
+            </Card>
+          ))}
+        </>
+      )}
+
+      {riskNotes.length > 0 && (
+        <>
+          <Text size="xs" fw={600} c="dimmed" tt="uppercase">Risk Notes</Text>
+          {riskNotes.map((note: string, i: number) => (
+            <Group key={i} gap="xs" wrap="nowrap">
+              <IconAlertTriangle size={14} color="orange" />
+              <Text size="xs">{note}</Text>
+            </Group>
+          ))}
+        </>
+      )}
+    </Stack>
+  );
+}
+
+// ── Main Page ──
+
+export function AdminShadowAiPage() {
+  return (
+    <Stack gap="lg" p="md">
+      <Group>
+        <IconScale size={28} />
+        <Title order={2}>AI Benchmarking</Title>
+      </Group>
+      <Text c="dimmed" size="sm">
+        Compare AI model outputs side-by-side using real tenant data.
+        Configure alternate models, run shadow comparisons, and review historical results.
+      </Text>
+
+      <Tabs defaultValue="run">
+        <Tabs.List>
+          <Tabs.Tab value="config" leftSection={<IconSettings size={16} />}>
+            Model Configuration
+          </Tabs.Tab>
+          <Tabs.Tab value="run" leftSection={<IconPlayerPlay size={16} />}>
+            Run Comparison
+          </Tabs.Tab>
+          <Tabs.Tab value="history" leftSection={<IconHistory size={16} />}>
+            History
+          </Tabs.Tab>
+        </Tabs.List>
+
+        <Tabs.Panel value="config" pt="md">
+          <ModelConfigTab />
+        </Tabs.Panel>
+
+        <Tabs.Panel value="run" pt="md">
+          <RunComparisonTab />
+        </Tabs.Panel>
+
+        <Tabs.Panel value="history" pt="md">
+          <HistoryTab />
+        </Tabs.Panel>
+      </Tabs>
+    </Stack>
+  );
+}

frontend/src/pages/assessment-groups/AssessmentGroupsPage.tsx

@@ -12,7 +12,7 @@ import {
 } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 interface AssessmentGroup {
   id: string;
@@ -79,7 +79,7 @@ export function AssessmentGroupsPage() {
   const [opened, { open, close }] = useDisclosure(false);
   const [editing, setEditing] = useState<AssessmentGroup | null>(null);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.ASSESSMENTS_GROUPS_EDIT);
 
   const { data: groups = [], isLoading } = useQuery<AssessmentGroup[]>({
     queryKey: ['assessment-groups'],

frontend/src/pages/board-planning/BudgetPlanningPage.tsx

@@ -1,17 +1,17 @@
 import { useState, useEffect, useRef } from 'react';
 import {
   Title, Table, Group, Button, Stack, Text, NumberInput,
-  Select, Loader, Center, Badge, Card, Alert, Modal,
+  Select, Loader, Center, Badge, Card, Alert, Modal, ThemeIcon,
 } from '@mantine/core';
 import { notifications } from '@mantine/notifications';
 import {
   IconDeviceFloppy, IconInfoCircle, IconPencil, IconX,
   IconCheck, IconArrowBack, IconTrash, IconRefresh,
-  IconUpload, IconDownload,
+  IconUpload, IconDownload, IconFileSpreadsheet,
 } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 import { usePreferencesStore } from '../../stores/preferencesStore';
 
 interface PlanLine {
@@ -87,7 +87,7 @@ const statusColors: Record<string, string> = {
 
 export function BudgetPlanningPage() {
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.PLANNING_BUDGETS_EDIT);
   const isDark = usePreferencesStore((s) => s.colorScheme) === 'dark';
   const stickyBg = isDark ? 'var(--mantine-color-dark-7)' : 'white';
   const stickyBorder = isDark ? 'var(--mantine-color-dark-4)' : '#e9ecef';
@@ -659,7 +659,37 @@ export function BudgetPlanningPage() {
                 {lineData.length === 0 && (
                   <Table.Tr>
                     <Table.Td colSpan={15}>
-                      <Text ta="center" c="dimmed" py="lg">No budget plan lines.</Text>
+                      <Card withBorder p="xl" mx="auto" maw={600} my="lg" style={{ textAlign: 'center' }}>
+                        <ThemeIcon size={60} radius="xl" variant="light" color="blue" mx="auto" mb="md">
+                          <IconFileSpreadsheet size={28} />
+                        </ThemeIcon>
+                        <Title order={4} mb="xs">Get Started with Your {selectedYear} Budget</Title>
+                        <Text c="dimmed" size="sm" mb="lg" maw={450} mx="auto">
+                          Your budget plan is created but has no line items yet. Download the
+                          CSV template pre-filled with your chart of accounts, fill in your
+                          monthly amounts, then upload it here.
+                        </Text>
+                        <Group justify="center" gap="md">
+                          <Button
+                            variant="light"
+                            leftSection={<IconDownload size={16} />}
+                            onClick={handleDownloadTemplate}
+                          >
+                            Download Budget Template
+                          </Button>
+                          <Button
+                            leftSection={<IconUpload size={16} />}
+                            onClick={handleImportCSV}
+                            loading={importMutation.isPending}
+                          >
+                            Upload Budget CSV
+                          </Button>
+                        </Group>
+                        <Text size="xs" c="dimmed" mt="md">
+                          Tip: The template includes all your active accounts. Fill in the monthly
+                          dollar amounts for each line, save as CSV, then upload.
+                        </Text>
+                      </Card>
                     </Table.Td>
                   </Table.Tr>
                 )}

frontend/src/pages/board-planning/InvestmentScenarioDetailPage.tsx

@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useState, useMemo } from 'react';
 import {
   Title, Text, Stack, Group, Button, Table, Badge, Card, ActionIcon,
   Loader, Center, Select, Modal, TextInput, Alert, SimpleGrid, Tooltip,
@@ -40,7 +40,7 @@ export function InvestmentScenarioDetailPage() {
     },
   });
 
-  const { data: projection, isLoading: projLoading } = useQuery({
+  const { data: projection, isLoading: projLoading, dataUpdatedAt: projUpdatedAt } = useQuery({
     queryKey: ['board-planning-projection', id],
     queryFn: async () => {
       const { data } = await api.get(`/board-planning/scenarios/${id}/projection`);
@@ -49,6 +49,17 @@ export function InvestmentScenarioDetailPage() {
     enabled: !!id,
   });
 
+  // When projection refreshes (which may create auto-renew records on the backend),
+  // re-fetch the scenario so the investments list picks up any new renewal records.
+  const [lastProjUpdate, setLastProjUpdate] = useState(0);
+  if (projUpdatedAt && projUpdatedAt !== lastProjUpdate) {
+    setLastProjUpdate(projUpdatedAt);
+    if (lastProjUpdate > 0) {
+      // Only re-fetch after a real update (not the initial load)
+      queryClient.invalidateQueries({ queryKey: ['board-planning-scenario', id] });
+    }
+  }
+
   const addMutation = useMutation({
     mutationFn: (dto: any) => api.post(`/board-planning/scenarios/${id}/investments`, dto),
     onSuccess: () => {
@@ -100,12 +111,40 @@ export function InvestmentScenarioDetailPage() {
     },
   });
 
+  // Compute shared time range for aligned charts (must be above early returns to satisfy Rules of Hooks)
+  const investments = scenario?.investments || [];
+  const summary = projection?.summary;
+
+  const { sharedStartDate, sharedEndDate } = useMemo(() => {
+    const allDates: Date[] = [];
+
+    // Dates from investments
+    for (const inv of investments) {
+      if (inv.purchase_date) allDates.push(new Date(inv.purchase_date));
+      if (inv.maturity_date) allDates.push(new Date(inv.maturity_date));
+    }
+
+    // Dates from projection datapoints
+    const dps = projection?.datapoints || [];
+    if (dps.length > 0) {
+      allDates.push(new Date(dps[0].year, dps[0].monthNum - 1, 1));
+      const last = dps[dps.length - 1];
+      allDates.push(new Date(last.year, last.monthNum - 1, 1));
+    }
+
+    if (allDates.length === 0) return { sharedStartDate: undefined, sharedEndDate: undefined };
+
+    const min = new Date(Math.min(...allDates.map((d) => d.getTime())));
+    const max = new Date(Math.max(...allDates.map((d) => d.getTime())));
+    return {
+      sharedStartDate: new Date(min.getFullYear(), min.getMonth(), 1),
+      sharedEndDate: new Date(max.getFullYear(), max.getMonth(), 1),
+    };
+  }, [investments, projection]);
+
   if (isLoading) return <Center h={400}><Loader size="lg" /></Center>;
   if (!scenario) return <Center h={400}><Text>Scenario not found</Text></Center>;
 
-  const investments = scenario.investments || [];
-  const summary = projection?.summary;
-
   // Build a lookup of per-investment interest from the projection
   const interestDetailMap: Record<string, { interest: number; principal: number }> = {};
   if (summary?.investment_interest_details) {
@@ -259,7 +298,13 @@ export function InvestmentScenarioDetailPage() {
       </Card>
 
       {/* Investment Timeline */}
-      {investments.length > 0 && <InvestmentTimeline investments={investments} />}
+      {investments.length > 0 && (
+        <InvestmentTimeline
+          investments={investments}
+          sharedStartDate={sharedStartDate}
+          sharedEndDate={sharedEndDate}
+        />
+      )}
 
       {/* Projection Chart */}
       {projection && (
@@ -267,6 +312,8 @@ export function InvestmentScenarioDetailPage() {
           datapoints={projection.datapoints || []}
           title="Scenario Projection"
           summary={projection.summary}
+          sharedStartDate={sharedStartDate}
+          sharedEndDate={sharedEndDate}
         />
       )}
       {projLoading && <Center py="xl"><Loader /></Center>}

frontend/src/pages/board-planning/components/InvestmentTimeline.tsx

@@ -13,9 +13,12 @@ const typeColors: Record<string, string> = {
 
 interface Props {
   investments: any[];
+  /** Optional shared time range to align with ProjectionChart */
+  sharedStartDate?: Date;
+  sharedEndDate?: Date;
 }
 
-export function InvestmentTimeline({ investments }: Props) {
+export function InvestmentTimeline({ investments, sharedStartDate, sharedEndDate }: Props) {
   const { items, startDate, endDate, totalMonths } = useMemo(() => {
     const now = new Date();
     const items = investments
@@ -28,16 +31,24 @@ export function InvestmentTimeline({ investments }: Props) {
 
     if (!items.length) return { items: [], startDate: now, endDate: now, totalMonths: 1 };
 
-    const allDates = items.flatMap((i: any) => [i.start, i.end].filter(Boolean)) as Date[];
-    const startDate = new Date(Math.min(...allDates.map((d) => d.getTime())));
-    const endDate = new Date(Math.max(...allDates.map((d) => d.getTime())));
+    // Use shared range if provided (to align with ProjectionChart), otherwise compute from investments
+    let startDate: Date;
+    let endDate: Date;
+    if (sharedStartDate && sharedEndDate) {
+      startDate = sharedStartDate;
+      endDate = sharedEndDate;
+    } else {
+      const allDates = items.flatMap((i: any) => [i.start, i.end].filter(Boolean)) as Date[];
+      startDate = new Date(Math.min(...allDates.map((d) => d.getTime())));
+      endDate = new Date(Math.max(...allDates.map((d) => d.getTime())));
+    }
     const totalMonths = Math.max(
       (endDate.getFullYear() - startDate.getFullYear()) * 12 + (endDate.getMonth() - startDate.getMonth()) + 1,
       1,
     );
 
     return { items, startDate, endDate, totalMonths };
-  }, [investments]);
+  }, [investments, sharedStartDate, sharedEndDate]);
 
   if (!items.length) return null;
 

frontend/src/pages/board-planning/components/ProjectionChart.tsx

@@ -23,18 +23,31 @@ interface Props {
   datapoints: Datapoint[];
   title?: string;
   summary?: any;
+  /** Optional shared time range to align with InvestmentTimeline */
+  sharedStartDate?: Date;
+  sharedEndDate?: Date;
 }
 
-export function ProjectionChart({ datapoints, title = 'Financial Projection', summary }: Props) {
+export function ProjectionChart({ datapoints, title = 'Financial Projection', summary, sharedStartDate, sharedEndDate }: Props) {
   const [fundFilter, setFundFilter] = useState('all');
 
   const chartData = useMemo(() => {
-    return datapoints.map((d) => ({
+    let filtered = datapoints;
+    // If shared range provided, filter datapoints to match
+    if (sharedStartDate && sharedEndDate) {
+      const startKey = sharedStartDate.getFullYear() * 12 + sharedStartDate.getMonth();
+      const endKey = sharedEndDate.getFullYear() * 12 + sharedEndDate.getMonth();
+      filtered = datapoints.filter((d) => {
+        const dpKey = d.year * 12 + (d.monthNum - 1);
+        return dpKey >= startKey && dpKey <= endKey;
+      });
+    }
+    return filtered.map((d) => ({
       ...d,
       label: `${d.month}`,
       total: d.operating_cash + d.operating_investments + d.reserve_cash + d.reserve_investments,
     }));
-  }, [datapoints]);
+  }, [datapoints, sharedStartDate, sharedEndDate]);
 
   // Find first forecast month for reference line
   const forecastStart = chartData.findIndex((d) => d.is_forecast);

frontend/src/pages/budgets/BudgetsPage.tsx

@@ -8,7 +8,7 @@ import { IconDeviceFloppy, IconInfoCircle, IconPencil, IconX, IconArrowRight } f
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { useNavigate } from 'react-router-dom';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 import { usePreferencesStore } from '../../stores/preferencesStore';
 
 interface BudgetLine {
@@ -40,7 +40,7 @@ export function BudgetsPage() {
   const [editData, setEditData] = useState<BudgetLine[] | null>(null); // null = not editing
   const queryClient = useQueryClient();
   const navigate = useNavigate();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.FINANCIALS_BUDGETS_EDIT);
   const isDark = usePreferencesStore((s) => s.colorScheme) === 'dark';
   const stickyBg = isDark ? 'var(--mantine-color-dark-7)' : 'white';
   const stickyBorder = isDark ? 'var(--mantine-color-dark-4)' : '#e9ecef';

frontend/src/pages/capital-projects/CapitalProjectsPage.tsx

@@ -14,7 +14,7 @@ import {
 import { useNavigate } from 'react-router-dom';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 // ---------------------------------------------------------------------------
 // Types & constants
@@ -252,7 +252,7 @@ export function CapitalProjectsPage() {
   const [dragOverYear, setDragOverYear] = useState<number | null>(null);
   const printModeRef = useRef(false);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.PLANNING_PROJECTS_EDIT);
 
   // ---- Data fetching ----
 

frontend/src/pages/dashboard/DashboardPage.tsx

@@ -1,7 +1,7 @@
 import {
   Title, Text, SimpleGrid, Card, Group, ThemeIcon, Stack, Table,
   Badge, Loader, Center, Divider, RingProgress, Tooltip, Button,
-  Popover, List,
+  Popover, List, Anchor,
 } from '@mantine/core';
 import {
   IconCash,
@@ -15,10 +15,14 @@ import {
   IconHeartbeat,
   IconRefresh,
   IconInfoCircle,
+  IconCoin,
+  IconCalendarEvent,
 } from '@tabler/icons-react';
 import { useState, useCallback } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { useAuthStore, useIsReadOnly } from '../../stores/authStore';
+import { useNavigate } from 'react-router-dom';
+import { useAuthStore } from '../../stores/authStore';
+import { useHasAnyCapability, CAPABILITIES } from '../../permissions';
 import api from '../../services/api';
 
 interface HealthScore {
@@ -58,6 +62,28 @@ function TrajectoryIcon({ trajectory }: { trajectory: string | null }) {
   return null;
 }
 
+// Map missing data items to navigation links
+const missingDataLinks: Record<string, { label: string; path: string }> = {
+  'reserve fund account': { label: 'Set up a reserve account', path: '/accounts' },
+  'reserve account': { label: 'Set up a reserve account', path: '/accounts' },
+  'reserve projects': { label: 'Add reserve projects', path: '/projects' },
+  'capital projects': { label: 'Add capital projects', path: '/projects' },
+  'projects': { label: 'Add projects', path: '/projects' },
+  'budget': { label: 'Set up a budget', path: '/board-planning/budgets' },
+  'operating budget': { label: 'Set up a budget', path: '/board-planning/budgets' },
+  'reserve budget': { label: 'Set up a budget', path: '/board-planning/budgets' },
+  'assessment groups': { label: 'Create assessment groups', path: '/assessment-groups' },
+  'accounts': { label: 'Set up accounts', path: '/accounts' },
+};
+
+function getMissingDataLink(item: string): { label: string; path: string } | null {
+  const lower = item.toLowerCase();
+  for (const [key, value] of Object.entries(missingDataLinks)) {
+    if (lower.includes(key)) return value;
+  }
+  return null;
+}
+
 function HealthScoreCard({
   score,
   title,
@@ -65,6 +91,7 @@ function HealthScoreCard({
   isRefreshing,
   onRefresh,
   lastFailed,
+  onNavigate,
 }: {
   score: HealthScore | null;
   title: string;
@@ -72,6 +99,7 @@ function HealthScoreCard({
   isRefreshing?: boolean;
   onRefresh?: () => void;
   lastFailed?: boolean;
+  onNavigate?: (path: string) => void;
 }) {
   // No score at all yet
   if (!score) {
@@ -118,9 +146,19 @@ function HealthScoreCard({
           <Stack align="center" gap="xs">
             <Badge color="gray" variant="light" size="lg">Pending</Badge>
             <Text size="xs" c="dimmed" ta="center">Missing data:</Text>
-            {missingItems.map((item: string, i: number) => (
-              <Text key={i} size="xs" c="dimmed" ta="center">{item}</Text>
-            ))}
+            {missingItems.map((item: string, i: number) => {
+              const link = getMissingDataLink(item);
+              return link ? (
+                <Anchor key={i} size="xs" href={link.path} onClick={(e: React.MouseEvent) => {
+                  e.preventDefault();
+                  onNavigate?.(link.path);
+                }}>
+                  {item} &rarr; {link.label}
+                </Anchor>
+              ) : (
+                <Text key={i} size="xs" c="dimmed" ta="center">{item}</Text>
+              );
+            })}
           </Stack>
         </Center>
       </Card>
@@ -313,8 +351,13 @@ interface DashboardData {
 
 export function DashboardPage() {
   const currentOrg = useAuthStore((s) => s.currentOrg);
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useHasAnyCapability(
+    CAPABILITIES.FINANCIALS_ACCOUNTS_EDIT,
+    CAPABILITIES.FINANCIALS_BUDGETS_EDIT,
+    CAPABILITIES.FINANCIALS_ACTUALS_EDIT,
+  );
   const queryClient = useQueryClient();
+  const navigate = useNavigate();
 
   // Track whether a refresh is in progress (per score type) for async polling
   const [operatingRefreshing, setOperatingRefreshing] = useState(false);
@@ -326,6 +369,16 @@ export function DashboardPage() {
     enabled: !!currentOrg,
   });
 
+  const { data: investmentActivities } = useQuery<{
+    maturing_investments: any[];
+    upcoming_scenario_investments: any[];
+    total_activities: number;
+  }>({
+    queryKey: ['upcoming-investment-activities'],
+    queryFn: async () => { const { data } = await api.get('/reports/upcoming-investment-activities'); return data; },
+    enabled: !!currentOrg,
+  });
+
   const { data: healthScores } = useQuery<HealthScoresData>({
     queryKey: ['health-scores'],
     queryFn: async () => { const { data } = await api.get('/health-scores/latest'); return data; },
@@ -429,6 +482,7 @@ export function DashboardPage() {
               isRefreshing={operatingRefreshing}
               onRefresh={!isReadOnly ? handleRefreshOperating : undefined}
               lastFailed={!!healthScores?.operating_last_failed}
+              onNavigate={navigate}
             />
             <HealthScoreCard
               score={healthScores?.reserve || null}
@@ -441,6 +495,7 @@ export function DashboardPage() {
               isRefreshing={reserveRefreshing}
               onRefresh={!isReadOnly ? handleRefreshReserve : undefined}
               lastFailed={!!healthScores?.reserve_last_failed}
+              onNavigate={navigate}
             />
           </SimpleGrid>
 
@@ -493,6 +548,97 @@ export function DashboardPage() {
             </Card>
           </SimpleGrid>
 
+          {/* Upcoming Investment Activities */}
+          {(investmentActivities?.total_activities || 0) > 0 && (
+            <Card withBorder padding="lg" radius="md">
+              <Group justify="space-between" mb="sm">
+                <Group gap="xs">
+                  <ThemeIcon color="teal" variant="light" size={28} radius="md">
+                    <IconCalendarEvent size={16} />
+                  </ThemeIcon>
+                  <Title order={4}>Upcoming Investment Activities</Title>
+                </Group>
+                <Badge variant="light" color="teal">{investmentActivities?.total_activities} upcoming</Badge>
+              </Group>
+              <Table striped highlightOnHover>
+                <Table.Thead>
+                  <Table.Tr>
+                    <Table.Th>Activity</Table.Th>
+                    <Table.Th>Type</Table.Th>
+                    <Table.Th>Fund</Table.Th>
+                    <Table.Th ta="right">Amount</Table.Th>
+                    <Table.Th>Date</Table.Th>
+                    <Table.Th>Timeline</Table.Th>
+                  </Table.Tr>
+                </Table.Thead>
+                <Table.Tbody>
+                  {(investmentActivities?.maturing_investments || []).map((inv: any) => (
+                    <Table.Tr key={`mat-${inv.id}`}>
+                      <Table.Td>
+                        <Group gap={6}>
+                          <IconCoin size={14} color="var(--mantine-color-orange-6)" />
+                          <Text size="sm" fw={500}>{inv.name}</Text>
+                        </Group>
+                        {inv.institution && <Text size="xs" c="dimmed">{inv.institution}</Text>}
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="xs" color="orange" variant="light">Maturing</Badge>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="xs" color={inv.fund_type === 'reserve' ? 'violet' : 'blue'} variant="light">
+                          {inv.fund_type}
+                        </Badge>
+                      </Table.Td>
+                      <Table.Td ta="right" ff="monospace">
+                        <Text size="sm" fw={500}>{fmt(inv.maturity_value)}</Text>
+                        <Text size="xs" c="green">+{fmt(inv.interest_earned)} interest</Text>
+                      </Table.Td>
+                      <Table.Td>
+                        <Text size="sm">{new Date(inv.maturity_date).toLocaleDateString()}</Text>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="sm" color={inv.days_remaining <= 14 ? 'red' : inv.days_remaining <= 30 ? 'yellow' : 'gray'} variant="light">
+                          {inv.days_remaining} days
+                        </Badge>
+                      </Table.Td>
+                    </Table.Tr>
+                  ))}
+                  {(investmentActivities?.upcoming_scenario_investments || []).map((si: any) => (
+                    <Table.Tr key={`plan-${si.id}`}>
+                      <Table.Td>
+                        <Group gap={6}>
+                          <IconTrendingUp size={14} color="var(--mantine-color-blue-6)" />
+                          <Text size="sm" fw={500}>{si.label}</Text>
+                        </Group>
+                        <Text size="xs" c="dimmed">Scenario: {si.scenario_name}</Text>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="xs" color="blue" variant="light">Planned Purchase</Badge>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="xs" color={si.fund_type === 'reserve' ? 'violet' : 'blue'} variant="light">
+                          {si.fund_type}
+                        </Badge>
+                      </Table.Td>
+                      <Table.Td ta="right" ff="monospace">
+                        <Text size="sm" fw={500}>{fmt(si.principal)}</Text>
+                        {si.interest_rate && <Text size="xs" c="dimmed">{parseFloat(si.interest_rate).toFixed(2)}% APY</Text>}
+                      </Table.Td>
+                      <Table.Td>
+                        <Text size="sm">{new Date(si.purchase_date).toLocaleDateString()}</Text>
+                      </Table.Td>
+                      <Table.Td>
+                        <Badge size="sm" color={si.days_until <= 14 ? 'red' : si.days_until <= 30 ? 'yellow' : 'gray'} variant="light">
+                          {si.days_until} days
+                        </Badge>
+                      </Table.Td>
+                    </Table.Tr>
+                  ))}
+                </Table.Tbody>
+              </Table>
+            </Card>
+          )}
+
           <SimpleGrid cols={{ base: 1, md: 2 }}>
             <Card withBorder padding="lg" radius="md">
               <Title order={4}>Quick Stats</Title>

frontend/src/pages/investment-planning/InvestmentPlanningPage.tsx

@@ -43,7 +43,7 @@ import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { notifications } from '@mantine/notifications';
 import { useNavigate } from 'react-router-dom';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 // ── Types ──
 
@@ -385,7 +385,7 @@ export function InvestmentPlanningPage() {
   const [targetScenarioId, setTargetScenarioId] = useState<string | null>(null);
   const [newScenarioName, setNewScenarioName] = useState('');
   const [investmentStartDate, setInvestmentStartDate] = useState<Date | null>(new Date());
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.PLANNING_INVESTMENTS_EDIT);
 
   // Load investment scenarios for the "Add to Plan" modal
   const { data: investmentScenarios } = useQuery<any[]>({
@@ -559,6 +559,32 @@ export function InvestmentPlanningPage() {
     }
   }, []);
 
+  // Auto-refresh: if no recommendations exist or they are older than 30 days, trigger automatically
+  const autoRefreshTriggered = useRef(false);
+  useEffect(() => {
+    if (autoRefreshTriggered.current || isProcessing || isTriggering || isReadOnly) return;
+    if (savedRec === undefined) return; // still loading
+
+    const shouldAutoRefresh = (() => {
+      // No saved recommendation at all
+      if (!savedRec) return true;
+      // Error state with no cached data
+      if (savedRec.status === 'error' && (!savedRec.recommendations || savedRec.recommendations.length === 0)) return true;
+      // Recommendations older than 30 days
+      if (savedRec.created_at) {
+        const age = Date.now() - new Date(savedRec.created_at).getTime();
+        const thirtyDays = 30 * 24 * 60 * 60 * 1000;
+        if (age > thirtyDays) return true;
+      }
+      return false;
+    })();
+
+    if (shouldAutoRefresh) {
+      autoRefreshTriggered.current = true;
+      handleTriggerAI();
+    }
+  }, [savedRec, isProcessing, isTriggering, isReadOnly, handleTriggerAI]);
+
   // Build AI result from saved recommendation for display
   const aiResult: AIResponse | null = hasResults
     ? {

frontend/src/pages/investments/InvestmentsPage.tsx

@@ -10,7 +10,7 @@ import { notifications } from '@mantine/notifications';
 import { IconPlus, IconEdit } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 interface Investment {
   id: string; name: string; institution: string; account_number_last4: string;
@@ -26,7 +26,7 @@ export function InvestmentsPage() {
   const [opened, { open, close }] = useDisclosure(false);
   const [editing, setEditing] = useState<Investment | null>(null);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.PLANNING_INVESTMENTS_EDIT);
 
   const { data: investments = [], isLoading } = useQuery<Investment[]>({
     queryKey: ['investments'],

frontend/src/pages/invoices/InvoicesPage.tsx

@@ -9,7 +9,7 @@ import { notifications } from '@mantine/notifications';
 import { IconSend, IconInfoCircle, IconCheck, IconX } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 interface Invoice {
   id: string; invoice_number: string; unit_number: string; unit_id: string;
@@ -65,7 +65,7 @@ export function InvoicesPage() {
   const [preview, setPreview] = useState<Preview | null>(null);
   const [previewLoading, setPreviewLoading] = useState(false);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.TRANSACTIONS_EDIT);
 
   const { data: invoices = [], isLoading } = useQuery<Invoice[]>({
     queryKey: ['invoices'],

frontend/src/pages/monthly-actuals/MonthlyActualsPage.tsx

@@ -10,7 +10,7 @@ import {
 } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 import { usePreferencesStore } from '../../stores/preferencesStore';
 import { AttachmentPanel } from '../../components/attachments/AttachmentPanel';
 
@@ -69,7 +69,7 @@ export function MonthlyActualsPage() {
   const [isEditing, setIsEditing] = useState(false);
   const [confirmOpened, { open: openConfirm, close: closeConfirm }] = useDisclosure(false);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.FINANCIALS_ACTUALS_EDIT);
   const isDark = usePreferencesStore((s) => s.colorScheme) === 'dark';
   const stickyBg = isDark ? 'var(--mantine-color-dark-7)' : 'white';
   const stickyBorder = isDark ? 'var(--mantine-color-dark-4)' : '#e9ecef';

frontend/src/pages/org-members/OrgMembersPage.tsx

@@ -12,8 +12,10 @@ import {
   IconShieldCheck, IconInfoCircle,
 } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useNavigate } from 'react-router-dom';
 import api from '../../services/api';
-import { useAuthStore, useIsReadOnly } from '../../stores/authStore';
+import { useAuthStore } from '../../stores/authStore';
+import { useCanEdit, useHasCapability, CAPABILITIES } from '../../permissions';
 
 interface OrgMember {
   id: string;
@@ -29,19 +31,21 @@ interface OrgMember {
 
 const ROLE_OPTIONS = [
   { value: 'president', label: 'President' },
+  { value: 'vice_president', label: 'Vice President' },
   { value: 'treasurer', label: 'Treasurer' },
   { value: 'secretary', label: 'Secretary' },
-  { value: 'board_member', label: 'Board Member' },
-  { value: 'property_manager', label: 'Property Manager' },
+  { value: 'member_at_large', label: 'Member at Large' },
+  { value: 'manager', label: 'Property Manager' },
   { value: 'viewer', label: 'Viewer (Read-Only)' },
 ];
 
 const roleColors: Record<string, string> = {
   president: 'red',
+  vice_president: 'grape',
   treasurer: 'blue',
   secretary: 'green',
-  board_member: 'violet',
-  property_manager: 'orange',
+  member_at_large: 'violet',
+  manager: 'orange',
   viewer: 'gray',
   admin: 'red',
 };
@@ -52,7 +56,9 @@ export function OrgMembersPage() {
   const [editingMember, setEditingMember] = useState<OrgMember | null>(null);
   const queryClient = useQueryClient();
   const { user, currentOrg } = useAuthStore();
-  const isReadOnly = useIsReadOnly();
+  const navigate = useNavigate();
+  const isReadOnly = !useCanEdit(CAPABILITIES.SETTINGS_MEMBERS_MANAGE);
+  const canManagePermissions = useHasCapability(CAPABILITIES.SETTINGS_PERMISSIONS_MANAGE);
 
   const { data: members = [], isLoading } = useQuery<OrgMember[]>({
     queryKey: ['org-members'],
@@ -68,7 +74,7 @@ export function OrgMembersPage() {
       firstName: '',
       lastName: '',
       password: '',
-      role: 'board_member',
+      role: 'member_at_large',
     },
     validate: {
       email: (v) => (/^\S+@\S+\.\S+$/.test(v) ? null : 'Valid email required'),
@@ -80,7 +86,7 @@ export function OrgMembersPage() {
 
   const editForm = useForm({
     initialValues: {
-      role: 'board_member',
+      role: 'member_at_large',
     },
   });
 
@@ -163,11 +169,18 @@ export function OrgMembersPage() {
           <Title order={2}>Organization Members</Title>
           <Text c="dimmed" size="sm">Manage who has access to {currentOrg?.name}</Text>
         </div>
-        {!isReadOnly && (
-          <Button leftSection={<IconUserPlus size={16} />} onClick={openAdd}>
-            Add Member
-          </Button>
-        )}
+        <Group>
+          {canManagePermissions && (
+            <Button variant="light" leftSection={<IconShieldCheck size={16} />} onClick={() => navigate('/settings/permissions')}>
+              Role Permissions
+            </Button>
+          )}
+          {!isReadOnly && (
+            <Button leftSection={<IconUserPlus size={16} />} onClick={openAdd}>
+              Add Member
+            </Button>
+          )}
+        </Group>
       </Group>
 
       <SimpleGrid cols={{ base: 1, sm: 3 }}>
@@ -214,6 +227,13 @@ export function OrgMembersPage() {
         As an organization administrator, you can add board members, property managers, and
         viewers to give them access to this tenant. Each member can log in with their own
         credentials and see the same financial data.
+        {currentOrg?.planLevel && !['enterprise'].includes(currentOrg.planLevel) && (
+          <Text size="sm" mt={6} fw={500}>
+            Your {currentOrg.planLevel === 'professional' ? 'Professional' : 'Starter'} plan
+            supports up to 5 user accounts ({activeMembers.length}/5 used).
+            {activeMembers.length >= 5 && ' Upgrade to Enterprise for unlimited members.'}
+          </Text>
+        )}
       </Alert>
 
       <Table striped highlightOnHover>

frontend/src/pages/payments/PaymentsPage.tsx

@@ -10,7 +10,7 @@ import { notifications } from '@mantine/notifications';
 import { IconPlus, IconEdit, IconTrash } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 interface Payment {
   id: string; unit_id: string; unit_number: string; invoice_id: string;
@@ -23,7 +23,7 @@ export function PaymentsPage() {
   const [editing, setEditing] = useState<Payment | null>(null);
   const [deleteConfirm, setDeleteConfirm] = useState<Payment | null>(null);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.TRANSACTIONS_EDIT);
 
   const { data: payments = [], isLoading } = useQuery<Payment[]>({
     queryKey: ['payments'],

frontend/src/pages/pricing/PricingPage.tsx

@@ -1,19 +1,21 @@
 import { useState } from 'react';
 import {
   Container, Title, Text, SimpleGrid, Card, Stack, Group, Badge,
-  Button, List, ThemeIcon, TextInput, Center, Alert,
+  Button, List, ThemeIcon, TextInput, Center, Alert, SegmentedControl, Box,
 } from '@mantine/core';
 import { IconCheck, IconX, IconRocket, IconStar, IconCrown, IconAlertCircle } from '@tabler/icons-react';
 import { useNavigate } from 'react-router-dom';
 import api from '../../services/api';
 import logoSrc from '../../assets/logo.png';
 
+type BillingInterval = 'month' | 'year';
+
 const plans = [
   {
     id: 'starter',
     name: 'Starter',
-    price: '$29',
-    period: '/month',
+    monthlyPrice: 29,
+    annualPrice: 261, // 29 * 12 * 0.75
     description: 'For small communities getting started',
     icon: IconRocket,
     color: 'blue',
@@ -29,8 +31,8 @@ const plans = [
   {
     id: 'professional',
     name: 'Professional',
-    price: '$79',
-    period: '/month',
+    monthlyPrice: 79,
+    annualPrice: 711, // 79 * 12 * 0.75
     description: 'For growing HOAs that need full features',
     icon: IconStar,
     color: 'violet',
@@ -47,8 +49,8 @@ const plans = [
   {
     id: 'enterprise',
     name: 'Enterprise',
-    price: 'Custom',
-    period: '',
+    monthlyPrice: 0,
+    annualPrice: 0,
     description: 'For large communities and management firms',
     icon: IconCrown,
     color: 'orange',
@@ -64,29 +66,53 @@ const plans = [
   },
 ];
 
+function formatPrice(plan: typeof plans[0], interval: BillingInterval) {
+  if (plan.externalUrl) return { display: 'Custom', sub: '' };
+  if (interval === 'year') {
+    const monthly = (plan.annualPrice / 12).toFixed(2);
+    return {
+      display: `$${monthly}`,
+      sub: `/mo billed annually ($${plan.annualPrice}/yr)`,
+    };
+  }
+  return { display: `$${plan.monthlyPrice}`, sub: '/month' };
+}
+
 export function PricingPage() {
   const navigate = useNavigate();
   const [loading, setLoading] = useState<string | null>(null);
   const [error, setError] = useState('');
   const [email, setEmail] = useState('');
   const [businessName, setBusinessName] = useState('');
+  const [billingInterval, setBillingInterval] = useState<BillingInterval>('month');
+
+  const handleStartTrial = async (planId: string) => {
+    if (!email.trim()) {
+      setError('Email address is required to start a trial');
+      return;
+    }
+    if (!businessName.trim()) {
+      setError('HOA / Business name is required to start a trial');
+      return;
+    }
 
-  const handleSelectPlan = async (planId: string) => {
     setLoading(planId);
     setError('');
     try {
-      const { data } = await api.post('/billing/create-checkout-session', {
+      const { data } = await api.post('/billing/start-trial', {
         planId,
-        email: email || undefined,
-        businessName: businessName || undefined,
+        billingInterval,
+        email: email.trim(),
+        businessName: businessName.trim(),
       });
-      if (data.url) {
-        window.location.href = data.url;
+      if (data.subscriptionId) {
+        // Navigate to pending page with subscription ID for polling
+        navigate(`/onboarding/pending?session_id=${data.subscriptionId}`);
       } else {
-        setError('Unable to create checkout session');
+        setError('Unable to start trial');
       }
     } catch (err: any) {
-      setError(err.response?.data?.message || 'Failed to start checkout');
+      setError(err.response?.data?.message || 'Failed to start trial');
     } finally {
       setLoading(null);
     }
@@ -104,20 +130,48 @@ export function PricingPage() {
         </Text>
       </Stack>
 
-      {/* Optional pre-capture fields */}
+      {/* Monthly / Annual Toggle */}
+      <Center mb="xl">
+        <Box pos="relative">
+          <SegmentedControl
+            value={billingInterval}
+            onChange={(val) => setBillingInterval(val as BillingInterval)}
+            data={[
+              { label: 'Monthly', value: 'month' },
+              { label: 'Annual', value: 'year' },
+            ]}
+            size="md"
+            radius="xl"
+          />
+          {billingInterval === 'year' && (
+            <Badge
+              color="green"
+              variant="filled"
+              size="sm"
+              style={{ position: 'absolute', top: -10, right: -40 }}
+            >
+              Save 25%
+            </Badge>
+          )}
+        </Box>
+      </Center>
+
+      {/* Pre-capture fields (required for trial) */}
       <Center mb="xl">
         <Group>
           <TextInput
-            placeholder="Email address"
+            placeholder="Email address *"
             value={email}
             onChange={(e) => setEmail(e.currentTarget.value)}
             style={{ width: 220 }}
+            required
           />
           <TextInput
-            placeholder="HOA / Business name"
+            placeholder="HOA / Business name *"
             value={businessName}
             onChange={(e) => setBusinessName(e.currentTarget.value)}
             style={{ width: 220 }}
+            required
           />
         </Group>
       </Center>
@@ -129,87 +183,101 @@ export function PricingPage() {
       )}
 
       <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="lg">
-        {plans.map((plan) => (
-          <Card
-            key={plan.id}
-            withBorder
-            shadow={plan.popular ? 'lg' : 'sm'}
-            radius="md"
-            p="xl"
-            style={plan.popular ? {
-              border: '2px solid var(--mantine-color-violet-5)',
-              position: 'relative',
-            } : undefined}
-          >
-            {plan.popular && (
-              <Badge
-                color="violet"
-                variant="filled"
-                style={{ position: 'absolute', top: -10, right: 20 }}
-              >
-                Most Popular
-              </Badge>
-            )}
+        {plans.map((plan) => {
+          const price = formatPrice(plan, billingInterval);
+          return (
+            <Card
+              key={plan.id}
+              withBorder
+              shadow={plan.popular ? 'lg' : 'sm'}
+              radius="md"
+              p="xl"
+              style={plan.popular ? {
+                border: '2px solid var(--mantine-color-violet-5)',
+                position: 'relative',
+              } : undefined}
+            >
+              {plan.popular && (
+                <Badge
+                  color="violet"
+                  variant="filled"
+                  style={{ position: 'absolute', top: -10, right: 20 }}
+                >
+                  Most Popular
+                </Badge>
+              )}
+
+              <Stack gap="md">
+                <Group>
+                  <ThemeIcon size="lg" color={plan.color} variant="light" radius="md">
+                    <plan.icon size={20} />
+                  </ThemeIcon>
+                  <div>
+                    <Text fw={700} size="lg">{plan.name}</Text>
+                    <Text size="xs" c="dimmed">{plan.description}</Text>
+                  </div>
+                </Group>
 
-            <Stack gap="md">
-              <Group>
-                <ThemeIcon size="lg" color={plan.color} variant="light" radius="md">
-                  <plan.icon size={20} />
-                </ThemeIcon>
                 <div>
-                  <Text fw={700} size="lg">{plan.name}</Text>
-                  <Text size="xs" c="dimmed">{plan.description}</Text>
+                  <Group align="baseline" gap={4}>
+                    <Text fw={800} size="xl" ff="monospace" style={{ fontSize: plan.externalUrl ? 28 : 36 }}>
+                      {plan.externalUrl ? 'Request Quote' : price.display}
+                    </Text>
+                  </Group>
+                  {price.sub && (
+                    <Text size="xs" c="dimmed" mt={2}>
+                      {price.sub}
+                    </Text>
+                  )}
+                  {!plan.externalUrl && billingInterval === 'year' && (
+                    <Text size="xs" c="dimmed" td="line-through" mt={2}>
+                      ${plan.monthlyPrice}/mo without annual discount
+                    </Text>
+                  )}
                 </div>
-              </Group>
 
-              <Group align="baseline" gap={4}>
-                <Text fw={800} size="xl" ff="monospace" style={{ fontSize: plan.externalUrl ? 28 : 36 }}>
-                  {plan.externalUrl ? 'Request Quote' : plan.price}
-                </Text>
-                {plan.period && <Text size="sm" c="dimmed">{plan.period}</Text>}
-              </Group>
+                <List spacing="xs" size="sm" center>
+                  {plan.features.map((f, i) => (
+                    <List.Item
+                      key={i}
+                      icon={
+                        <ThemeIcon
+                          size={20}
+                          radius="xl"
+                          color={f.included ? 'teal' : 'gray'}
+                          variant={f.included ? 'filled' : 'light'}
+                        >
+                          {f.included ? <IconCheck size={12} /> : <IconX size={12} />}
+                        </ThemeIcon>
+                      }
+                    >
+                      <Text c={f.included ? undefined : 'dimmed'}>{f.text}</Text>
+                    </List.Item>
+                  ))}
+                </List>
 
-              <List spacing="xs" size="sm" center>
-                {plan.features.map((f, i) => (
-                  <List.Item
-                    key={i}
-                    icon={
-                      <ThemeIcon
-                        size={20}
-                        radius="xl"
-                        color={f.included ? 'teal' : 'gray'}
-                        variant={f.included ? 'filled' : 'light'}
-                      >
-                        {f.included ? <IconCheck size={12} /> : <IconX size={12} />}
-                      </ThemeIcon>
-                    }
-                  >
-                    <Text c={f.included ? undefined : 'dimmed'}>{f.text}</Text>
-                  </List.Item>
-                ))}
-              </List>
-
-              <Button
-                fullWidth
-                size="md"
-                color={plan.color}
-                variant={plan.popular ? 'filled' : 'light'}
-                loading={!plan.externalUrl ? loading === plan.id : false}
-                onClick={() =>
-                  plan.externalUrl
-                    ? window.open(plan.externalUrl, '_blank', 'noopener')
-                    : handleSelectPlan(plan.id)
-                }
-              >
-                {plan.externalUrl ? 'Request Quote' : 'Get Started'}
-              </Button>
-            </Stack>
-          </Card>
-        ))}
+                <Button
+                  fullWidth
+                  size="md"
+                  color={plan.color}
+                  variant={plan.popular ? 'filled' : 'light'}
+                  loading={!plan.externalUrl ? loading === plan.id : false}
+                  onClick={() =>
+                    plan.externalUrl
+                      ? window.open(plan.externalUrl, '_blank', 'noopener')
+                      : handleStartTrial(plan.id)
+                  }
+                >
+                  {plan.externalUrl ? 'Request Quote' : 'Start Free Trial'}
+                </Button>
+              </Stack>
+            </Card>
+          );
+        })}
       </SimpleGrid>
 
       <Text ta="center" size="sm" c="dimmed" mt="xl">
-        All plans include a 14-day free trial. No credit card required to start.
+        All plans include a 14-day free trial. No credit card required.
       </Text>
     </Container>
   );

frontend/src/pages/projects/ProjectsPage.tsx

@@ -2,17 +2,17 @@ import { useState, useRef } from 'react';
 import {
   Title, Table, Group, Button, Stack, Text, Modal, TextInput,
   NumberInput, Select, Textarea, Badge, ActionIcon, Loader, Center,
-  Card, SimpleGrid, Progress, Switch, Tooltip,
+  Card, SimpleGrid, Progress, Switch, Tooltip, ThemeIcon, List,
 } from '@mantine/core';
 import { DateInput } from '@mantine/dates';
 import { useForm } from '@mantine/form';
 import { useDisclosure } from '@mantine/hooks';
 import { notifications } from '@mantine/notifications';
-import { IconPlus, IconEdit, IconUpload, IconDownload, IconLock, IconLockOpen } from '@tabler/icons-react';
+import { IconPlus, IconEdit, IconUpload, IconDownload, IconLock, IconLockOpen, IconShieldCheck, IconBulb, IconRocket } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
 import { parseCSV, downloadBlob } from '../../utils/csv';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 // ---------------------------------------------------------------------------
 // Types & constants
@@ -79,7 +79,7 @@ export function ProjectsPage() {
   const [editing, setEditing] = useState<Project | null>(null);
   const queryClient = useQueryClient();
   const fileInputRef = useRef<HTMLInputElement>(null);
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.PLANNING_PROJECTS_EDIT);
 
   // ---- Data fetching ----
 
@@ -465,10 +465,55 @@ export function ProjectsPage() {
           ))}
           {projects.length === 0 && (
             <Table.Tr>
-              <Table.Td colSpan={9}>
-                <Text ta="center" c="dimmed" py="lg">
-                  No projects yet
-                </Text>
+              <Table.Td colSpan={9} p={0}>
+                <Card p="xl" style={{ textAlign: 'center' }}>
+                  <ThemeIcon size={60} radius="xl" variant="gradient" gradient={{ from: 'violet', to: 'blue' }} mx="auto" mb="md">
+                    <IconShieldCheck size={32} />
+                  </ThemeIcon>
+                  <Title order={3} mb="xs">Capital Projects & Reserve Planning</Title>
+                  <Text c="dimmed" maw={550} mx="auto" mb="lg">
+                    Track your community&apos;s capital improvement projects, reserve fund allocations,
+                    and long-term maintenance schedule. This is where you build a comprehensive
+                    picture of your HOA&apos;s future capital needs.
+                  </Text>
+                  <Card withBorder p="md" maw={550} mx="auto" mb="lg" ta="left">
+                    <Text fw={600} mb="xs">
+                      <IconBulb size={16} style={{ verticalAlign: 'middle', marginRight: 6 }} />
+                      Common HOA Projects to Get Started
+                    </Text>
+                    <List size="sm" spacing="xs" c="dimmed">
+                      <List.Item><Text span fw={500} c="dark">Roof Replacement</Text> — Track the remaining useful life and reserve funding for your building&apos;s roof</List.Item>
+                      <List.Item><Text span fw={500} c="dark">Parking Lot / Paving</Text> — Plan for periodic seal-coating and resurfacing</List.Item>
+                      <List.Item><Text span fw={500} c="dark">Pool & Recreation</Text> — Budget for pool resurfacing, equipment, and amenity upgrades</List.Item>
+                      <List.Item><Text span fw={500} c="dark">Painting & Exterior</Text> — Schedule exterior painting cycles (typically every 5-7 years)</List.Item>
+                      <List.Item><Text span fw={500} c="dark">HVAC Systems</Text> — Track common-area heating and cooling equipment lifecycles</List.Item>
+                      <List.Item><Text span fw={500} c="dark">Elevator Modernization</Text> — Plan for required elevator upgrades and code compliance</List.Item>
+                    </List>
+                  </Card>
+                  <Group justify="center" gap="md">
+                    {!isReadOnly && (
+                      <>
+                        <Button
+                          size="md"
+                          leftSection={<IconRocket size={18} />}
+                          variant="gradient"
+                          gradient={{ from: 'violet', to: 'blue' }}
+                          onClick={handleNew}
+                        >
+                          Create Your First Project
+                        </Button>
+                        <Button
+                          size="md"
+                          variant="light"
+                          leftSection={<IconUpload size={16} />}
+                          onClick={() => fileInputRef.current?.click()}
+                        >
+                          Import from CSV
+                        </Button>
+                      </>
+                    )}
+                  </Group>
+                </Card>
               </Table.Td>
             </Table.Tr>
           )}

frontend/src/pages/reports/CapitalPlanningPage.tsx

@@ -0,0 +1,196 @@
+import { useState } from 'react';
+import {
+  Title, Text, Card, Table, Group, Stack, Badge, Loader, Center,
+  Button, NumberInput,
+} from '@mantine/core';
+import { IconPrinter } from '@tabler/icons-react';
+import { useQuery } from '@tanstack/react-query';
+import api from '../../services/api';
+
+interface ProjectItem {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  estimated_cost: number;
+  target_year: number | null;
+  useful_life_years: number | null;
+  last_replacement_date: string | null;
+  fund_source: string;
+  status: string;
+  priority: number;
+  condition_rating: number | null;
+  year_amounts: Record<number, number>;
+  beyond: number;
+}
+
+interface CategoryGroup {
+  category: string;
+  projects: ProjectItem[];
+}
+
+interface CapitalPlanningData {
+  title: string;
+  start_year: number;
+  years: number[];
+  categories: CategoryGroup[];
+  year_totals: Record<number, number>;
+  beyond_total: number;
+  grand_total: number;
+  generated_at: string;
+}
+
+const fmt = (v: number) =>
+  v === 0 ? '-' : v.toLocaleString('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+
+export function CapitalPlanningPage() {
+  const [startYear, setStartYear] = useState(new Date().getFullYear());
+
+  const { data, isLoading } = useQuery<CapitalPlanningData>({
+    queryKey: ['capital-planning', startYear],
+    queryFn: async () => {
+      const { data } = await api.get(`/reports/capital-planning?startYear=${startYear}`);
+      return data;
+    },
+  });
+
+  if (isLoading) return <Center h={300}><Loader /></Center>;
+
+  const years = data?.years || [];
+  const hasProjects = (data?.categories || []).some((c) => c.projects.length > 0);
+
+  return (
+    <Stack>
+      <Group justify="space-between">
+        <div>
+          <Title order={2}>Capital Planning Report</Title>
+          <Text c="dimmed" size="sm">{data?.title || '5-Year Capital Project Forecast'}</Text>
+        </div>
+        <Group>
+          <NumberInput
+            size="xs"
+            w={100}
+            value={startYear}
+            onChange={(v) => v && setStartYear(Number(v))}
+            min={2020}
+            max={2050}
+          />
+          <Button
+            variant="light"
+            leftSection={<IconPrinter size={16} />}
+            onClick={() => window.print()}
+          >
+            Print / PDF
+          </Button>
+        </Group>
+      </Group>
+
+      {!hasProjects ? (
+        <Card withBorder p="xl">
+          <Text ta="center" c="dimmed" py="lg">
+            No capital projects found. Add projects on the Projects page to generate this report.
+          </Text>
+        </Card>
+      ) : (
+        <Card withBorder p="lg" className="capital-planning-print">
+          <Title order={3} ta="center" mb="xs">{data?.title}</Title>
+          <Text ta="center" c="dimmed" size="sm" mb="md">
+            Generated {new Date(data?.generated_at || '').toLocaleDateString()}
+          </Text>
+
+          <Table striped withTableBorder withColumnBorders>
+            <Table.Thead>
+              <Table.Tr>
+                <Table.Th>Description</Table.Th>
+                <Table.Th ta="center" w={60}>Life (yr)</Table.Th>
+                <Table.Th ta="center" w={90}>Last Done</Table.Th>
+                {years.map((y) => (
+                  <Table.Th key={y} ta="right" w={100}>{y}</Table.Th>
+                ))}
+                <Table.Th ta="right" w={100}>Beyond</Table.Th>
+              </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>
+              {(data?.categories || []).map((cat) => {
+                const catTotals: Record<number, number> = {};
+                let catBeyond = 0;
+                for (const y of years) catTotals[y] = 0;
+                for (const p of cat.projects) {
+                  for (const y of years) catTotals[y] += p.year_amounts[y] || 0;
+                  catBeyond += p.beyond;
+                }
+
+                return [
+                  <Table.Tr key={`cat-${cat.category}`} style={{ background: 'var(--mantine-color-blue-0)' }}>
+                    <Table.Td colSpan={3 + years.length + 1}>
+                      <Text fw={700} size="sm">{cat.category}</Text>
+                    </Table.Td>
+                  </Table.Tr>,
+                  ...cat.projects.map((p) => (
+                    <Table.Tr key={p.id}>
+                      <Table.Td>
+                        <Text size="sm">{p.name}</Text>
+                        {p.status !== 'planned' && (
+                          <Badge size="xs" variant="light" ml={4}
+                            color={p.status === 'completed' ? 'green' : p.status === 'in_progress' ? 'blue' : 'gray'}>
+                            {p.status}
+                          </Badge>
+                        )}
+                      </Table.Td>
+                      <Table.Td ta="center">
+                        <Text size="sm">{p.useful_life_years || '-'}</Text>
+                      </Table.Td>
+                      <Table.Td ta="center">
+                        <Text size="sm">
+                          {p.last_replacement_date
+                            ? new Date(p.last_replacement_date).getFullYear()
+                            : '-'}
+                        </Text>
+                      </Table.Td>
+                      {years.map((y) => (
+                        <Table.Td key={y} ta="right" ff="monospace">
+                          <Text size="sm">{fmt(p.year_amounts[y] || 0)}</Text>
+                        </Table.Td>
+                      ))}
+                      <Table.Td ta="right" ff="monospace">
+                        <Text size="sm">{fmt(p.beyond)}</Text>
+                      </Table.Td>
+                    </Table.Tr>
+                  )),
+                  <Table.Tr key={`subtotal-${cat.category}`} style={{ borderTop: '2px solid var(--mantine-color-gray-4)' }}>
+                    <Table.Td colSpan={3}>
+                      <Text size="sm" fw={600} fs="italic">Subtotal — {cat.category}</Text>
+                    </Table.Td>
+                    {years.map((y) => (
+                      <Table.Td key={y} ta="right" ff="monospace">
+                        <Text size="sm" fw={600}>{fmt(catTotals[y])}</Text>
+                      </Table.Td>
+                    ))}
+                    <Table.Td ta="right" ff="monospace">
+                      <Text size="sm" fw={600}>{fmt(catBeyond)}</Text>
+                    </Table.Td>
+                  </Table.Tr>,
+                ];
+              })}
+            </Table.Tbody>
+            <Table.Tfoot>
+              <Table.Tr style={{ background: 'var(--mantine-color-dark-0)' }}>
+                <Table.Td colSpan={3}>
+                  <Text fw={700}>TOTAL</Text>
+                </Table.Td>
+                {years.map((y) => (
+                  <Table.Td key={y} ta="right" ff="monospace">
+                    <Text fw={700}>{fmt(data?.year_totals[y] || 0)}</Text>
+                  </Table.Td>
+                ))}
+                <Table.Td ta="right" ff="monospace">
+                  <Text fw={700}>{fmt(data?.beyond_total || 0)}</Text>
+                </Table.Td>
+              </Table.Tr>
+            </Table.Tfoot>
+          </Table>
+        </Card>
+      )}
+    </Stack>
+  );
+}

frontend/src/pages/reserves/ReservesPage.tsx

@@ -11,7 +11,7 @@ import { notifications } from '@mantine/notifications';
 import { IconPlus, IconEdit } from '@tabler/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import api from '../../services/api';
-import { useIsReadOnly } from '../../stores/authStore';
+import { useCanEdit, CAPABILITIES } from '../../permissions';
 
 interface ReserveComponent {
   id: string; name: string; category: string; description: string;
@@ -27,7 +27,7 @@ export function ReservesPage() {
   const [opened, { open, close }] = useDisclosure(false);
   const [editing, setEditing] = useState<ReserveComponent | null>(null);
   const queryClient = useQueryClient();
-  const isReadOnly = useIsReadOnly();
+  const isReadOnly = !useCanEdit(CAPABILITIES.PLANNING_PROJECTS_EDIT);
 
   const { data: components = [], isLoading } = useQuery<ReserveComponent[]>({
     queryKey: ['reserve-components'],

frontend/src/pages/settings/PermissionSettingsPage.tsx

@@ -0,0 +1,250 @@
+import { useState, useEffect, useMemo } from 'react';
+import {
+  Title, Text, Card, Stack, Group, Table, Checkbox, Button, Alert,
+  Badge, Tooltip, Divider, Loader, Center,
+} from '@mantine/core';
+import { notifications } from '@mantine/notifications';
+import { IconShieldCheck, IconRefresh, IconInfoCircle } from '@tabler/icons-react';
+import { useAuthStore } from '../../stores/authStore';
+import { CAPABILITY_AREAS } from '../../permissions/capabilities';
+import { DEFAULT_ROLE_CAPABILITIES } from '../../permissions/default-role-capabilities';
+import api from '../../services/api';
+
+/** Roles shown as columns (homeowner hidden from UI per product decision) */
+const DISPLAY_ROLES = [
+  { value: 'president', label: 'President' },
+  { value: 'vice_president', label: 'Vice President' },
+  { value: 'treasurer', label: 'Treasurer' },
+  { value: 'secretary', label: 'Secretary' },
+  { value: 'member_at_large', label: 'Member at Large' },
+  { value: 'manager', label: 'Property Manager' },
+  { value: 'viewer', label: 'Viewer' },
+];
+
+interface PermissionOverrides {
+  [role: string]: {
+    grant?: string[];
+    revoke?: string[];
+  };
+}
+
+function buildCheckedState(overrides: PermissionOverrides): Record<string, Record<string, boolean>> {
+  const state: Record<string, Record<string, boolean>> = {};
+  for (const role of DISPLAY_ROLES) {
+    const defaults = new Set(DEFAULT_ROLE_CAPABILITIES[role.value] || []);
+    const roleOverride = overrides[role.value];
+
+    if (roleOverride?.grant) {
+      for (const cap of roleOverride.grant) defaults.add(cap);
+    }
+    if (roleOverride?.revoke) {
+      for (const cap of roleOverride.revoke) defaults.delete(cap);
+    }
+
+    state[role.value] = {};
+    for (const area of CAPABILITY_AREAS) {
+      for (const cap of area.capabilities) {
+        state[role.value][cap.key] = defaults.has(cap.key);
+      }
+    }
+  }
+  return state;
+}
+
+function buildOverridesFromState(checkedState: Record<string, Record<string, boolean>>): PermissionOverrides {
+  const overrides: PermissionOverrides = {};
+  for (const role of DISPLAY_ROLES) {
+    const defaults = new Set(DEFAULT_ROLE_CAPABILITIES[role.value] || []);
+    const grant: string[] = [];
+    const revoke: string[] = [];
+
+    for (const [cap, checked] of Object.entries(checkedState[role.value] || {})) {
+      const isDefault = defaults.has(cap);
+      if (checked && !isDefault) grant.push(cap);
+      if (!checked && isDefault) revoke.push(cap);
+    }
+
+    if (grant.length > 0 || revoke.length > 0) {
+      overrides[role.value] = {};
+      if (grant.length > 0) overrides[role.value].grant = grant;
+      if (revoke.length > 0) overrides[role.value].revoke = revoke;
+    }
+  }
+  return overrides;
+}
+
+export function PermissionSettingsPage() {
+  const { currentOrg, setOrgSettings } = useAuthStore();
+  const [saving, setSaving] = useState(false);
+  const [loaded, setLoaded] = useState(false);
+
+  const existingOverrides: PermissionOverrides = useMemo(
+    () => currentOrg?.settings?.permissionOverrides || {},
+    [currentOrg?.settings?.permissionOverrides],
+  );
+
+  const [checkedState, setCheckedState] = useState<Record<string, Record<string, boolean>>>(() =>
+    buildCheckedState(existingOverrides),
+  );
+
+  useEffect(() => {
+    setCheckedState(buildCheckedState(existingOverrides));
+    setLoaded(true);
+  }, [existingOverrides]);
+
+  const currentOverrides = useMemo(() => buildOverridesFromState(checkedState), [checkedState]);
+  const hasChanges = JSON.stringify(currentOverrides) !== JSON.stringify(existingOverrides);
+
+  const toggleCapability = (role: string, cap: string) => {
+    setCheckedState((prev) => ({
+      ...prev,
+      [role]: {
+        ...prev[role],
+        [cap]: !prev[role]?.[cap],
+      },
+    }));
+  };
+
+  const resetRole = (roleValue: string) => {
+    const defaults = new Set(DEFAULT_ROLE_CAPABILITIES[roleValue] || []);
+    const newRoleState: Record<string, boolean> = {};
+    for (const area of CAPABILITY_AREAS) {
+      for (const cap of area.capabilities) {
+        newRoleState[cap.key] = defaults.has(cap.key);
+      }
+    }
+    setCheckedState((prev) => ({ ...prev, [roleValue]: newRoleState }));
+  };
+
+  const handleSave = async () => {
+    setSaving(true);
+    try {
+      const overrides = buildOverridesFromState(checkedState);
+      const res = await api.patch('/organizations/settings', { permissionOverrides: overrides });
+      setOrgSettings(res.data);
+      notifications.show({ title: 'Saved', message: 'Permission settings updated. Members will see changes on next login or page refresh.', color: 'green' });
+    } catch (err: any) {
+      notifications.show({ title: 'Error', message: err.response?.data?.message || 'Failed to save', color: 'red' });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const isOverridden = (role: string, cap: string) => {
+    const isDefault = (DEFAULT_ROLE_CAPABILITIES[role] || []).includes(cap);
+    const isChecked = checkedState[role]?.[cap] ?? false;
+    return isChecked !== isDefault;
+  };
+
+  if (!loaded) {
+    return <Center mt="xl"><Loader /></Center>;
+  }
+
+  return (
+    <Stack gap="md">
+      <Group justify="space-between" align="center">
+        <Group gap="xs">
+          <IconShieldCheck size={28} />
+          <Title order={2}>Role Permissions</Title>
+        </Group>
+        <Group>
+          <Button
+            variant="default"
+            leftSection={<IconRefresh size={16} />}
+            onClick={() => setCheckedState(buildCheckedState(existingOverrides))}
+            disabled={!hasChanges}
+          >
+            Discard Changes
+          </Button>
+          <Button
+            onClick={handleSave}
+            loading={saving}
+            disabled={!hasChanges}
+          >
+            Save Changes
+          </Button>
+        </Group>
+      </Group>
+
+      <Alert icon={<IconInfoCircle size={16} />} color="blue" variant="light">
+        Customize which capabilities each role has in your organization.
+        Highlighted cells differ from the system defaults. Use "Reset" to revert a role to defaults.
+        The <strong>Viewer</strong> role is always read-only regardless of settings.
+      </Alert>
+
+      <Card withBorder p={0} style={{ overflow: 'auto' }}>
+        <Table striped highlightOnHover withColumnBorders style={{ minWidth: 900 }}>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th style={{ position: 'sticky', left: 0, background: 'var(--mantine-color-body)', zIndex: 1, minWidth: 200 }}>
+                Capability
+              </Table.Th>
+              {DISPLAY_ROLES.map((role) => (
+                <Table.Th key={role.value} style={{ textAlign: 'center', minWidth: 110 }}>
+                  <Stack gap={4} align="center">
+                    <Text size="xs" fw={600}>{role.label}</Text>
+                    <Tooltip label={`Reset ${role.label} to defaults`}>
+                      <Button
+                        variant="subtle"
+                        size="compact-xs"
+                        onClick={() => resetRole(role.value)}
+                      >
+                        Reset
+                      </Button>
+                    </Tooltip>
+                  </Stack>
+                </Table.Th>
+              ))}
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {CAPABILITY_AREAS.map((area) => (
+              <>
+                <Table.Tr key={`area-${area.label}`}>
+                  <Table.Td
+                    colSpan={DISPLAY_ROLES.length + 1}
+                    style={{ background: 'var(--mantine-color-gray-1)', fontWeight: 700 }}
+                  >
+                    <Text size="sm" fw={700} tt="uppercase">{area.label}</Text>
+                  </Table.Td>
+                </Table.Tr>
+                {area.capabilities.map((cap) => (
+                  <Table.Tr key={cap.key}>
+                    <Table.Td style={{ position: 'sticky', left: 0, background: 'var(--mantine-color-body)', zIndex: 1 }}>
+                      <Text size="sm">{cap.label}</Text>
+                    </Table.Td>
+                    {DISPLAY_ROLES.map((role) => {
+                      const checked = checkedState[role.value]?.[cap.key] ?? false;
+                      const overridden = isOverridden(role.value, cap.key);
+                      return (
+                        <Table.Td
+                          key={role.value}
+                          style={{
+                            textAlign: 'center',
+                            background: overridden ? 'var(--mantine-color-yellow-0)' : undefined,
+                          }}
+                        >
+                          <Checkbox
+                            checked={checked}
+                            onChange={() => toggleCapability(role.value, cap.key)}
+                            styles={{ input: { cursor: 'pointer' } }}
+                          />
+                        </Table.Td>
+                      );
+                    })}
+                  </Table.Tr>
+                ))}
+              </>
+            ))}
+          </Table.Tbody>
+        </Table>
+      </Card>
+
+      {hasChanges && (
+        <Alert color="yellow" variant="light">
+          You have unsaved changes. Click "Save Changes" to apply.
+        </Alert>
+      )}
+    </Stack>
+  );
+}

frontend/src/pages/settings/SettingsPage.tsx

@@ -1,11 +1,11 @@
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import {
   Title, Text, Card, Stack, Group, SimpleGrid, Badge, ThemeIcon, Divider,
-  Tabs, Button, Switch,
+  Tabs, Button, Switch, Loader,
 } from '@mantine/core';
 import {
   IconBuilding, IconUser, IconSettings, IconShieldLock,
-  IconFingerprint, IconLink, IconLogout,
+  IconFingerprint, IconLink, IconLogout, IconCreditCard,
 } from '@tabler/icons-react';
 import { notifications } from '@mantine/notifications';
 import { useAuthStore } from '../../stores/authStore';
@@ -15,10 +15,40 @@ import { PasskeySettings } from './PasskeySettings';
 import { LinkedAccounts } from './LinkedAccounts';
 import api from '../../services/api';
 
+interface SubscriptionInfo {
+  plan: string;
+  planName: string;
+  billingInterval: string;
+  status: string;
+  collectionMethod: string;
+  trialEndsAt: string | null;
+  currentPeriodEnd: string | null;
+  cancelAtPeriodEnd: boolean;
+  hasStripeCustomer: boolean;
+}
+
+const statusColors: Record<string, string> = {
+  active: 'green',
+  trial: 'blue',
+  past_due: 'orange',
+  archived: 'red',
+  suspended: 'red',
+};
+
 export function SettingsPage() {
   const { user, currentOrg } = useAuthStore();
   const { compactView, toggleCompactView } = usePreferencesStore();
   const [loggingOutAll, setLoggingOutAll] = useState(false);
+  const [subscription, setSubscription] = useState<SubscriptionInfo | null>(null);
+  const [subLoading, setSubLoading] = useState(true);
+  const [portalLoading, setPortalLoading] = useState(false);
+
+  useEffect(() => {
+    api.get('/billing/subscription')
+      .then(({ data }) => setSubscription(data))
+      .catch(() => { /* billing not configured or no subscription */ })
+      .finally(() => setSubLoading(false));
+  }, []);
 
   const handleLogoutEverywhere = async () => {
     setLoggingOutAll(true);
@@ -32,6 +62,32 @@ export function SettingsPage() {
     }
   };
 
+  const handleManageBilling = async () => {
+    setPortalLoading(true);
+    try {
+      const { data } = await api.post('/billing/portal');
+      if (data.url) {
+        window.location.href = data.url;
+      }
+    } catch (err: any) {
+      const msg = err.response?.data?.message || 'Unable to open billing portal';
+      notifications.show({ message: typeof msg === 'string' ? msg : 'Unable to open billing portal', color: 'red' });
+    } finally {
+      setPortalLoading(false);
+    }
+  };
+
+  const formatInterval = (interval: string) => {
+    return interval === 'year' ? 'Annual' : 'Monthly';
+  };
+
+  const formatDate = (iso: string | null) => {
+    if (!iso) return null;
+    return new Date(iso).toLocaleDateString('en-US', {
+      year: 'numeric', month: 'short', day: 'numeric',
+    });
+  };
+
   return (
     <Stack>
       <div>
@@ -63,6 +119,79 @@ export function SettingsPage() {
           </Stack>
         </Card>
 
+        {/* Billing / Subscription */}
+        <Card withBorder padding="lg">
+          <Group mb="md">
+            <ThemeIcon color="teal" variant="light" size={40} radius="md">
+              <IconCreditCard size={24} />
+            </ThemeIcon>
+            <div>
+              <Text fw={600} size="lg">Billing</Text>
+              <Text c="dimmed" size="sm">Subscription and payment</Text>
+            </div>
+          </Group>
+          {subLoading ? (
+            <Group justify="center" py="md"><Loader size="sm" /></Group>
+          ) : subscription ? (
+            <Stack gap="xs">
+              <Group justify="space-between">
+                <Text size="sm" c="dimmed">Plan</Text>
+                <Group gap={4}>
+                  <Badge variant="light">{subscription.planName}</Badge>
+                  <Badge variant="light" color="gray" size="sm">{formatInterval(subscription.billingInterval)}</Badge>
+                </Group>
+              </Group>
+              <Group justify="space-between">
+                <Text size="sm" c="dimmed">Status</Text>
+                <Badge
+                  color={statusColors[subscription.status] || 'gray'}
+                  variant="light"
+                >
+                  {subscription.status === 'past_due' ? 'Past Due' : subscription.status}
+                  {subscription.cancelAtPeriodEnd ? ' (Canceling)' : ''}
+                </Badge>
+              </Group>
+              {subscription.trialEndsAt && subscription.status === 'trial' && (
+                <Group justify="space-between">
+                  <Text size="sm" c="dimmed">Trial Ends</Text>
+                  <Text size="sm" fw={500}>{formatDate(subscription.trialEndsAt)}</Text>
+                </Group>
+              )}
+              {subscription.currentPeriodEnd && subscription.status !== 'trial' && (
+                <Group justify="space-between">
+                  <Text size="sm" c="dimmed">Current Period Ends</Text>
+                  <Text size="sm" fw={500}>{formatDate(subscription.currentPeriodEnd)}</Text>
+                </Group>
+              )}
+              {subscription.collectionMethod === 'send_invoice' && (
+                <Group justify="space-between">
+                  <Text size="sm" c="dimmed">Payment</Text>
+                  <Badge variant="light" color="cyan" size="sm">Invoice / ACH</Badge>
+                </Group>
+              )}
+              {subscription.hasStripeCustomer ? (
+                <Button
+                  variant="light"
+                  color="teal"
+                  size="sm"
+                  leftSection={<IconCreditCard size={16} />}
+                  onClick={handleManageBilling}
+                  loading={portalLoading}
+                  mt="xs"
+                >
+                  Manage Billing
+                </Button>
+              ) : subscription.status === 'trial' ? (
+                <Text size="xs" c="dimmed" mt="xs">
+                  Billing portal will be available once you add a payment method.
+                </Text>
+              ) : null}
+            </Stack>
+          ) : (
+            <Text size="sm" c="dimmed">No active subscription</Text>
+          )}
+        </Card>
+
         {/* User Profile */}
         <Card withBorder padding="lg">
           <Group mb="md">
@@ -108,7 +237,7 @@ export function SettingsPage() {
             </Group>
             <Group justify="space-between">
               <Text size="sm" c="dimmed">Version</Text>
-              <Badge variant="light">2026.03.17</Badge>
+              <Badge variant="light">2026.4.6</Badge>
             </Group>
             <Group justify="space-between">
               <Text size="sm" c="dimmed">API</Text>