Add policy document naming, simplify settings UI, improve sync icons

- Add customizable policy document naming pattern with {year}, {sequence}, {description} tokens
- Simplify Upload Settings card by removing verbose token grid
- Change Paperless sync icons to cloud-based design (green cloud-check for synced, orange cloud-arrow for pending)
- Fix benefit plan modal to show renamed filename instead of original
- Fix delete button stretching in document list
- Rename attachments when expense details change (date, category, provider, amount)
- Add background sync with longer timeout for Paperless

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: JavaDogWebDesign

app/assets/css/pages/settings.css

@@ -540,40 +540,6 @@ html.dark-mode .toggle-slider:before {
     margin: 0;
 }
 
-/* Naming Tokens Grid */
-.naming-tokens-grid {
-    display: flex;
-    flex-wrap: wrap;
-    gap: var(--spacing-xs);
-    margin-bottom: var(--spacing-lg);
-    padding: var(--spacing-sm);
-    background: var(--bg-secondary);
-    border-radius: var(--radius-md);
-}
-
-.token-item {
-    display: flex;
-    align-items: center;
-    gap: var(--spacing-xs);
-    font-size: 0.8rem;
-}
-
-.token-item code {
-    background: var(--bg-primary);
-    color: var(--accent-blue);
-    padding: 2px 6px;
-    border-radius: 4px;
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-    font-weight: 500;
-    border: 1px solid var(--border-color);
-}
-
-.token-item span {
-    color: var(--text-secondary);
-    font-size: 0.75rem;
-}
-
 /* Naming Pattern Groups */
 .naming-pattern-group {
     margin-bottom: var(--spacing-md);
@@ -628,16 +594,16 @@ html.dark-mode .toggle-slider:before {
     border-radius: var(--radius-sm);
 }
 
-/* Dark mode adjustments */
-html.dark-mode .naming-tokens-grid {
-    background: rgba(255, 255, 255, 0.05);
-}
-
-html.dark-mode .token-item code {
-    background: var(--bg-primary);
-    border-color: var(--border-color);
+/* Inline preview (compact) */
+.naming-preview-inline {
+    display: block;
+    font-family: var(--font-mono);
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+    margin-top: 4px;
 }
 
+/* Dark mode adjustments */
 html.dark-mode .naming-preview {
     background: rgba(255, 255, 255, 0.05);
 }

app/assets/js/services/expenses.js

@@ -1051,37 +1051,40 @@ function getSyncStatusIcon(syncStatus, paperlessDocId = null) {
     // Get Paperless URL from global config (set by server)
     const paperlessUrl = window.paperlessConfig?.url;
 
+    // Cloud icon paths
+    const cloudPath = 'M18 10h-1.26A8 8 0 1 0 9 20h9a5 5 0 0 0 0-10z';
+
     switch (syncStatus) {
         case 'synced':
             // If we have paperless URL and doc ID, make it a link
             if (paperlessUrl && paperlessDocId) {
                 return `<a href="${paperlessUrl}/documents/${paperlessDocId}" target="_blank" rel="noopener"
                           class="sync-status sync-synced" title="View in Paperless (opens in new tab)">
                     <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
-                        <polyline points="22 4 12 14.01 9 11.01"/>
+                        <path d="${cloudPath}"/>
+                        <polyline points="9 13 12 16 16 11"/>
                     </svg>
                 </a>`;
             }
             return `<span class="sync-status sync-synced" title="Synced to Paperless">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                    <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
-                    <polyline points="22 4 12 14.01 9 11.01"/>
+                    <path d="${cloudPath}"/>
+                    <polyline points="9 13 12 16 16 11"/>
                 </svg>
             </span>`;
         case 'failed':
             return `<span class="sync-status sync-failed" title="Paperless sync failed - click to retry">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                    <circle cx="12" cy="12" r="10"/>
-                    <line x1="15" y1="9" x2="9" y2="15"/>
-                    <line x1="9" y1="9" x2="15" y2="15"/>
+                    <path d="${cloudPath}"/>
+                    <line x1="10" y1="11" x2="14" y2="15"/>
+                    <line x1="14" y1="11" x2="10" y2="15"/>
                 </svg>
             </span>`;
         case 'pending':
-            return `<span class="sync-status sync-pending" title="Sync pending">
+            return `<span class="sync-status sync-pending" title="Syncing to Paperless">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                    <circle cx="12" cy="12" r="10"/>
-                    <polyline points="12 6 12 12 16 14"/>
+                    <path d="${cloudPath}"/>
+                    <polyline points="12 17 12 11 15 14"/>
                 </svg>
             </span>`;
         default:

app/assets/js/services/planYears.js

@@ -452,7 +452,8 @@ export function handlePlanYearFormSubmit(e) {
             const targetPlanYearId = planYearId || result.data.plan_year_id;
             if (hasFiles && targetPlanYearId) {
                 try {
-                    await uploadPolicyDocuments(targetPlanYearId, fileInput.files);
+                    // Pass silent=true since we show our own consolidated message
+                    await uploadPolicyDocuments(targetPlanYearId, fileInput.files, true);
                     showAlert(planYearId ? 'Benefit plan updated successfully with documents!' : 'Benefit plan added successfully with documents!', 'success');
                 } catch (error) {
                     console.error('Error uploading documents:', error);

app/assets/js/services/policyYearDocuments.js

@@ -11,37 +11,40 @@ function getSyncStatusIcon(syncStatus, paperlessDocId = null) {
     // Get Paperless URL from global config (set by server)
     const paperlessUrl = window.paperlessConfig?.url;
 
+    // Cloud icon path
+    const cloudPath = 'M18 10h-1.26A8 8 0 1 0 9 20h9a5 5 0 0 0 0-10z';
+
     switch (syncStatus) {
         case 'synced':
             // If we have paperless URL and doc ID, make it a link
             if (paperlessUrl && paperlessDocId) {
                 return `<a href="${paperlessUrl}/documents/${paperlessDocId}" target="_blank" rel="noopener"
                           class="sync-status sync-synced" title="View in Paperless (opens in new tab)">
                     <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
-                        <polyline points="22 4 12 14.01 9 11.01"/>
+                        <path d="${cloudPath}"/>
+                        <polyline points="9 13 12 16 16 11"/>
                     </svg>
                 </a>`;
             }
             return `<span class="sync-status sync-synced" title="Synced to Paperless">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                    <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
-                    <polyline points="22 4 12 14.01 9 11.01"/>
+                    <path d="${cloudPath}"/>
+                    <polyline points="9 13 12 16 16 11"/>
                 </svg>
             </span>`;
         case 'failed':
             return `<span class="sync-status sync-failed" title="Paperless sync failed - click to retry">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                    <circle cx="12" cy="12" r="10"/>
-                    <line x1="15" y1="9" x2="9" y2="15"/>
-                    <line x1="9" y1="9" x2="15" y2="15"/>
+                    <path d="${cloudPath}"/>
+                    <line x1="10" y1="11" x2="14" y2="15"/>
+                    <line x1="14" y1="11" x2="10" y2="15"/>
                 </svg>
             </span>`;
         case 'pending':
-            return `<span class="sync-status sync-pending" title="Sync pending">
+            return `<span class="sync-status sync-pending" title="Syncing to Paperless">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                    <circle cx="12" cy="12" r="10"/>
-                    <polyline points="12 6 12 12 16 14"/>
+                    <path d="${cloudPath}"/>
+                    <polyline points="12 17 12 11 15 14"/>
                 </svg>
             </span>`;
         default:
@@ -132,7 +135,9 @@ function createPolicyDocumentItem(doc) {
     const docItem = document.createElement('div');
     docItem.className = 'existing-receipt-item';
 
-    const fileName = doc.original_filename;
+    // Extract the renamed filename from file_path (the actual saved filename)
+    const filePathParts = doc.file_path.split('/');
+    const fileName = filePathParts[filePathParts.length - 1];
     const fileType = doc.file_type.toLowerCase();
     // Remove data/{user_id}/ prefix to show just benefit_plans/{year}/filename
     const filePath = doc.file_path.replace(/^data\/\d+\//, '');
@@ -190,7 +195,10 @@ function createPolicyDocumentItem(doc) {
         }
     }
 
-    // Add delete button
+    // Add actions container with delete button (prevents button from stretching)
+    const actionsDiv = document.createElement('div');
+    actionsDiv.className = 'existing-receipt-actions';
+
     const deleteBtn = document.createElement('button');
     deleteBtn.type = 'button';
     deleteBtn.className = 'btn btn-small existing-receipt-delete receipt-delete-btn';
@@ -200,15 +208,19 @@ function createPolicyDocumentItem(doc) {
         deletePolicyDocument(doc.id);
     };
 
-    docItem.appendChild(deleteBtn);
+    actionsDiv.appendChild(deleteBtn);
+    docItem.appendChild(actionsDiv);
 
     return docItem;
 }
 
 /**
  * Upload documents for a policy year
+ * @param {number} planYearId - The plan year ID
+ * @param {FileList} files - Files to upload
+ * @param {boolean} silent - If true, don't show success toast (caller handles it)
  */
-export async function uploadPolicyDocuments(planYearId, files) {
+export async function uploadPolicyDocuments(planYearId, files, silent = false) {
     if (!files || files.length === 0) {
         return;
     }
@@ -227,7 +239,10 @@ export async function uploadPolicyDocuments(planYearId, files) {
         const data = await response.json();
 
         if (response.ok && data.success) {
-            showAlert(`${data.uploaded.length} document(s) uploaded successfully!`, 'success');
+            // Only show toast if not silent (caller may handle messaging)
+            if (!silent) {
+                showAlert(`${data.uploaded.length} document(s) uploaded successfully!`, 'success');
+            }
 
             // Reload documents
             const documents = await loadPolicyDocuments(planYearId);

app/database.py

@@ -400,6 +400,12 @@ def init_database():
     except sqlite3.OperationalError:
         pass  # Column already exists
 
+    # Add policy_naming_pattern column to users table if it doesn't exist
+    try:
+        cursor.execute("ALTER TABLE users ADD COLUMN policy_naming_pattern TEXT DEFAULT 'Policy_{year}_{sequence}'")
+    except sqlite3.OperationalError:
+        pass  # Column already exists
+
     # Add OIDC columns to users table for SSO authentication
     try:
         cursor.execute("ALTER TABLE users ADD COLUMN oidc_sub TEXT")

app/routes/attachments.py

@@ -147,11 +147,11 @@ def add_attachments(expense_id):
                     }
                 })
 
-    # Sync to Paperless after transaction is committed
+    # Sync to Paperless in background (non-blocking)
     for sync_item in pending_syncs:
         try:
-            from services.paperless_service import sync_to_paperless_safe
-            sync_to_paperless_safe(
+            from services.paperless_service import sync_to_paperless_background
+            sync_to_paperless_background(
                 user_id=user_id,
                 file_path=sync_item['file_path'],
                 metadata=sync_item['metadata'],
@@ -207,7 +207,7 @@ def delete_attachment(attachment_id):
         try:
             from services.paperless_service import delete_from_paperless
             # Build title to search for if no doc_id
-            title = f"HSA-{paperless_info['date']}"
+            title = f"HealthReceipts-{paperless_info['date']}"
             if paperless_info['provider']:
                 title += f"-{paperless_info['provider']}"
             title += f"-{paperless_info['category']}"

app/routes/expenses.py

@@ -178,11 +178,11 @@ def create_expense():
 
         conn.commit()
 
-        # Sync to Paperless after transaction is committed
+        # Sync to Paperless in background (non-blocking)
         for sync_item in pending_syncs:
             try:
-                from services.paperless_service import sync_to_paperless_safe
-                sync_to_paperless_safe(
+                from services.paperless_service import sync_to_paperless_background
+                sync_to_paperless_background(
                     user_id=user_id,
                     file_path=sync_item['file_path'],
                     metadata=sync_item['metadata'],

app/routes/plan_year_documents.py

@@ -5,7 +5,7 @@
 from werkzeug.utils import secure_filename
 from database import db_connection, db_readonly
 from utils.decorators import login_required
-from utils.helpers import get_benefit_plan_documents_folder
+from utils.helpers import get_benefit_plan_documents_folder, generate_policy_document_filename, get_user_policy_naming_pattern
 from services.file_service import save_uploaded_file, delete_file_safely, get_file_size
 
 plan_year_documents_bp = Blueprint('plan_year_documents', __name__)
@@ -52,7 +52,8 @@ def list_documents(plan_year_id):
 
         # Get all documents for this plan year
         documents = conn.execute('''
-            SELECT id, original_filename, file_type, file_size, file_path, created_at
+            SELECT id, original_filename, file_type, file_size, file_path, created_at,
+                   paperless_sync_status, paperless_doc_id
             FROM plan_year_documents
             WHERE plan_year_id = ?
             ORDER BY created_at DESC
@@ -95,22 +96,42 @@ def add_documents(plan_year_id):
         cursor = conn.cursor()
         plan_year_start_str = plan_year['plan_year_start']
 
-        for file in files:
-            # Save file (no compression for documents)
+        # Get user's policy naming pattern
+        policy_pattern = get_user_policy_naming_pattern(user_id)
+
+        # Get existing document count for sequence numbering
+        existing_count = conn.execute(
+            'SELECT COUNT(*) as count FROM plan_year_documents WHERE plan_year_id = ?',
+            (plan_year_id,)
+        ).fetchone()['count']
+
+        for idx, file in enumerate(files):
+            sequence = existing_count + idx + 1
+
+            # Get original filename for display (before renaming)
+            original_filename = secure_filename(file.filename)
+
+            # Generate proper filename for the document using user's pattern
+            base_filename = generate_policy_document_filename(
+                pattern=policy_pattern,
+                year=year,
+                sequence=sequence,
+                original_filename=original_filename
+            )
+
+            # Save file with generated filename (no compression for documents)
             result = save_uploaded_file(
                 file,
                 docs_folder,
                 user_id=None,  # No compression for documents
+                filename_override=base_filename,
                 compress=False
             )
 
             if result:
                 file_path, saved_filename, db_file_type = result
                 file_size = get_file_size(file_path)
 
-                # Get original filename for display
-                original_filename = secure_filename(file.filename)
-
                 cursor.execute('''
                     INSERT INTO plan_year_documents (plan_year_id, file_path, file_type, original_filename, file_size)
                     VALUES (?, ?, ?, ?, ?)
@@ -130,15 +151,15 @@ def add_documents(plan_year_id):
                     'plan_year_start': plan_year_start_str
                 })
 
-    # Sync to Paperless after transaction is committed
+    # Sync to Paperless in background (non-blocking)
     for sync_item in pending_syncs:
         try:
-            from services.paperless_service import sync_to_paperless_safe
+            from services.paperless_service import sync_to_paperless_background
             metadata = {
                 'date': sync_item['plan_year_start'],
                 'category': 'policy'
             }
-            sync_to_paperless_safe(
+            sync_to_paperless_background(
                 user_id=user_id,
                 file_path=sync_item['file_path'],
                 metadata=metadata,
@@ -193,7 +214,7 @@ def delete_document(document_id):
         try:
             from services.paperless_service import delete_from_paperless
             # Build title to search for if no doc_id
-            title = f"HSA-Policy-{paperless_info['date']}"
+            title = f"HealthReceipts-Policy-{paperless_info['date']}"
 
             delete_from_paperless(
                 user_id=user_id,