From 0ab4adcef3120d8ac64b1022a6d24536bc3c5f68 Mon Sep 17 00:00:00 2001
From: Frank Steiler <frank@steiler.de>
Date: Mon, 25 May 2026 22:36:46 +0200
Subject: [PATCH] fix(auto-itemize): extract invoiceNumber+notes via LLM, fix
 sticky PDF (#1581)

The LLM JSON schema for budget extraction was missing `invoiceNumber` and
`notes` fields, so those values were never returned even when the model
successfully identified them. The schema in `budgetExtraction.ts`, the
prompt in `prompts.ts`, and the provider profiles were updated to include
both fields, and the `openAICompatibleProvider` now maps them through to
the extraction result.

The `invoiceAutoItemizeService` now propagates `invoiceNumber` and `notes`
from the extraction result into the auto-itemize response. The
`AutoItemizePage` displays both fields in the extraction summary card once
results arrive, giving users a quick confirmation that the LLM found the
right invoice metadata without having to navigate away.

The PDF viewer inside `AutoItemizePage` was not staying fixed while the
user scrolled the results panel. The CSS was reworked so the PDF iframe
takes a full-viewport sticky column and the results panel scrolls
independently, resolving the sticky/full-viewport layout regression
introduced in #1577.

Fixes #1581

Co-Authored-By: Claude backend-developer (Haiku 4.5) <noreply@anthropic.com>
Co-Authored-By: Claude frontend-developer (Haiku 4.5) <noreply@anthropic.com>
Co-Authored-By: Claude qa-integration-tester (Sonnet 4.5) <noreply@anthropic.com>
Co-Authored-By: Claude e2e-test-engineer (Sonnet 4.5) <noreply@anthropic.com>
---
 .../AutoItemizePage.module.css                |  14 +-
 .../AutoItemizePage/AutoItemizePage.test.tsx  | 131 ++++++++++++++++++
 .../pages/AutoItemizePage/AutoItemizePage.tsx |  91 ++++++++----
 e2e/pages/AutoItemizePage.ts                  |  34 ++++-
 .../invoice-auto-itemize-page.spec.ts         | 103 +++++++++++++-
 .../openAICompatibleProvider.test.ts          |  82 +++++++++++
 .../openAICompatibleProvider.ts               |  14 +-
 .../src/services/budgetExtraction/prompts.ts  |  12 +-
 .../budgetExtraction/providerProfiles.test.ts |  24 +++-
 .../budgetExtraction/providerProfiles.ts      |  10 +-
 .../invoiceAutoItemizeService.test.ts         | 107 ++++++++++++++
 .../src/services/invoiceAutoItemizeService.ts |   2 +
 shared/src/types/budgetExtraction.ts          |   6 +-
 shared/src/types/invoiceAutoItemize.ts        |   4 +
 14 files changed, 586 insertions(+), 48 deletions(-)

diff --git a/client/src/pages/AutoItemizePage/AutoItemizePage.module.css b/client/src/pages/AutoItemizePage/AutoItemizePage.module.css
index c3308d802..1bec9f742 100644
--- a/client/src/pages/AutoItemizePage/AutoItemizePage.module.css
+++ b/client/src/pages/AutoItemizePage/AutoItemizePage.module.css
@@ -43,6 +43,7 @@
   align-items: start;
   overflow-y: auto;
   flex: 1;
+  min-height: 0;
 }
 
 @media (max-width: 860px) {
@@ -69,12 +70,15 @@
   display: flex;
   flex-direction: column;
   position: sticky;
-  top: calc(var(--auto-itemize-header-height) + var(--spacing-6));
+  top: var(--auto-itemize-header-height);
+  height: calc(100vh - var(--auto-itemize-header-height));
 }
 
 @media (max-width: 860px) {
   .previewColumn {
     position: static;
+    height: auto;
+    top: auto;
   }
 }
 
@@ -636,12 +640,16 @@
   position: relative;
   border-radius: var(--radius-lg);
   overflow: hidden;
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
 }
 
 .pdfIframe {
   width: 100%;
-  height: calc(100vh - var(--auto-itemize-header-height) - var(--spacing-12));
-  min-height: 480px;
+  flex: 1;
+  min-height: 0;
   border: 1px solid var(--color-border);
   border-radius: var(--radius-lg);
   background: var(--color-bg-tertiary);
diff --git a/client/src/pages/AutoItemizePage/AutoItemizePage.test.tsx b/client/src/pages/AutoItemizePage/AutoItemizePage.test.tsx
index 88d3f7995..067d9a686 100644
--- a/client/src/pages/AutoItemizePage/AutoItemizePage.test.tsx
+++ b/client/src/pages/AutoItemizePage/AutoItemizePage.test.tsx
@@ -1509,6 +1509,137 @@ describe('AutoItemizePage', () => {
     });
   });
 
+  // ─── Story #1581: SuggestionBadge for invoiceNumber and notes ────────────
+
+  describe('SuggestionBadge for extracted invoiceNumber and notes (Story #1581)', () => {
+    it('badge appears for invoiceNumber when extractedInvoiceNumber differs from stored', async () => {
+      // Invoice has invoiceNumber 'INV-001'; LLM extracts 'RE-2024-001' (different)
+      mockFetchInvoiceById.mockResolvedValue(makeInvoice({ invoiceNumber: 'INV-001' }));
+      mockGetPaperlessDocument.mockResolvedValue(makePaperlessDoc());
+      mockAutoItemize.mockResolvedValue({
+        lines: [],
+        warnings: [],
+        extractedInvoiceNumber: 'RE-2024-001',
+      });
+
+      renderPage();
+
+      await waitFor(() => {
+        expect(screen.getByText(/LLM suggests/i)).toBeInTheDocument();
+      });
+    });
+
+    it('badge absent when extractedInvoiceNumber is undefined', async () => {
+      mockFetchInvoiceById.mockResolvedValue(makeInvoice({ invoiceNumber: 'INV-001' }));
+      mockGetPaperlessDocument.mockResolvedValue(makePaperlessDoc());
+      // No extractedInvoiceNumber in response
+      mockAutoItemize.mockResolvedValue({ lines: [], warnings: [] });
+
+      renderPage();
+
+      await waitFor(() => {
+        expect(screen.getByRole('button', { name: /^Save$/i })).toBeInTheDocument();
+      });
+
+      expect(screen.queryByText(/LLM suggests/i)).not.toBeInTheDocument();
+    });
+
+    it('badge absent when extractedInvoiceNumber matches stored value', async () => {
+      // Both invoice and extracted value are 'INV-001' — no difference, no badge
+      mockFetchInvoiceById.mockResolvedValue(makeInvoice({ invoiceNumber: 'INV-001' }));
+      mockGetPaperlessDocument.mockResolvedValue(makePaperlessDoc());
+      mockAutoItemize.mockResolvedValue({
+        lines: [],
+        warnings: [],
+        extractedInvoiceNumber: 'INV-001', // same as stored
+      });
+
+      renderPage();
+
+      await waitFor(() => {
+        expect(screen.getByRole('button', { name: /^Save$/i })).toBeInTheDocument();
+      });
+
+      expect(screen.queryByText(/LLM suggests/i)).not.toBeInTheDocument();
+    });
+
+    it('Apply button updates the #invoice-number field and dismisses the badge', async () => {
+      mockFetchInvoiceById.mockResolvedValue(makeInvoice({ invoiceNumber: 'INV-001' }));
+      mockGetPaperlessDocument.mockResolvedValue(makePaperlessDoc());
+      mockAutoItemize.mockResolvedValue({
+        lines: [],
+        warnings: [],
+        extractedInvoiceNumber: 'RE-2024-001',
+      });
+
+      renderPage();
+
+      await waitFor(() => {
+        expect(screen.getByText(/LLM suggests/i)).toBeInTheDocument();
+      });
+
+      // Click the Apply button for the invoiceNumber suggestion
+      const applyButtons = screen.getAllByRole('button', { name: /Apply/i });
+      fireEvent.click(applyButtons[0]!);
+
+      // The invoice-number field should now hold the extracted value
+      const invoiceNumberField = document.getElementById('invoice-number') as HTMLInputElement;
+      expect(invoiceNumberField).not.toBeNull();
+      expect(invoiceNumberField.value).toBe('RE-2024-001');
+
+      // Badge disappears after applying (extracted value now matches the field value)
+      await waitFor(() => {
+        expect(screen.queryByText(/LLM suggests/i)).not.toBeInTheDocument();
+      });
+    });
+
+    it('badge appears for notes when extractedNotes differs from stored notes', async () => {
+      // Invoice has notes: null; LLM extracts a non-empty summary
+      mockFetchInvoiceById.mockResolvedValue(makeInvoice({ notes: null }));
+      mockGetPaperlessDocument.mockResolvedValue(makePaperlessDoc());
+      mockAutoItemize.mockResolvedValue({
+        lines: [],
+        warnings: [],
+        extractedNotes: 'Kitchen renovation labor and materials.',
+      });
+
+      renderPage();
+
+      await waitFor(() => {
+        expect(screen.getByText(/LLM suggests/i)).toBeInTheDocument();
+      });
+    });
+
+    it('Apply button for notes updates the #notes textarea and dismisses the badge', async () => {
+      mockFetchInvoiceById.mockResolvedValue(makeInvoice({ notes: null }));
+      mockGetPaperlessDocument.mockResolvedValue(makePaperlessDoc());
+      mockAutoItemize.mockResolvedValue({
+        lines: [],
+        warnings: [],
+        extractedNotes: 'Kitchen renovation labor and materials.',
+      });
+
+      renderPage();
+
+      await waitFor(() => {
+        expect(screen.getByText(/LLM suggests/i)).toBeInTheDocument();
+      });
+
+      const applyButtons = screen.getAllByRole('button', { name: /Apply/i });
+      fireEvent.click(applyButtons[0]!);
+
+      // The #notes textarea should now hold the extracted value
+      const notesField = document.getElementById('notes') as HTMLTextAreaElement;
+      expect(notesField).not.toBeNull();
+      expect(notesField.value).toBe('Kitchen renovation labor and materials.');
+
+      // Badge disappears after applying
+      await waitFor(() => {
+        expect(screen.queryByText(/LLM suggests/i)).not.toBeInTheDocument();
+      });
+    });
+  });
+
   // ─── Story #1576: PDF iframe ─────────────────────────────────────────────
 
   describe('PDF iframe in ready state (Story #1576)', () => {
diff --git a/client/src/pages/AutoItemizePage/AutoItemizePage.tsx b/client/src/pages/AutoItemizePage/AutoItemizePage.tsx
index a13db8c20..22651cfb2 100644
--- a/client/src/pages/AutoItemizePage/AutoItemizePage.tsx
+++ b/client/src/pages/AutoItemizePage/AutoItemizePage.tsx
@@ -82,6 +82,8 @@ export function AutoItemizePage() {
   > | null>(null);
   const [extractedInvoiceDate, setExtractedInvoiceDate] = useState<string | undefined>(undefined);
   const [extractedDueDate, setExtractedDueDate] = useState<string | undefined>(undefined);
+  const [extractedInvoiceNumber, setExtractedInvoiceNumber] = useState<string | undefined>(undefined);
+  const [extractedNotes, setExtractedNotes] = useState<string | undefined>(undefined);
 
   // Metadata edits
   const [metadataEdits, setMetadataEdits] = useState<MetadataEdits>({
@@ -158,6 +160,8 @@ export function AutoItemizePage() {
       setElapsed(0);
       setPdfLoaded(false);
       setPdfFailed(false);
+      setExtractedInvoiceNumber(undefined);
+      setExtractedNotes(undefined);
 
       try {
         // Load Paperless status for the fallback link
@@ -219,6 +223,8 @@ export function AutoItemizePage() {
           setWarnings(_autoItemizeResult.warnings);
           setExtractedInvoiceDate(_autoItemizeResult.extractedInvoiceDate ?? undefined);
           setExtractedDueDate(_autoItemizeResult.extractedDueDate ?? undefined);
+          setExtractedInvoiceNumber(_autoItemizeResult.extractedInvoiceNumber ?? undefined);
+          setExtractedNotes(_autoItemizeResult.extractedNotes ?? undefined);
           setPageStatus('ready');
         } else {
           setPageError(t('autoItemize.unexpectedResponse'));
@@ -516,6 +522,23 @@ export function AutoItemizePage() {
     [extractedDueDate, metadataEdits.dueDate],
   );
 
+  const invoiceNumberSuggestion = useMemo(
+    () =>
+      extractedInvoiceNumber &&
+      extractedInvoiceNumber !== (metadataEdits.invoiceNumber ?? '')
+        ? extractedInvoiceNumber
+        : undefined,
+    [extractedInvoiceNumber, metadataEdits.invoiceNumber],
+  );
+
+  const notesSuggestion = useMemo(
+    () =>
+      extractedNotes && extractedNotes !== (metadataEdits.notes ?? '')
+        ? extractedNotes
+        : undefined,
+    [extractedNotes, metadataEdits.notes],
+  );
+
   const computedLineTotal = useMemo(
     () => lines.filter((l) => l.included).reduce((sum, line) => sum + (line.totalAmount ?? 0), 0),
     [lines],
@@ -631,18 +654,28 @@ export function AutoItemizePage() {
 
               <div className={styles.fieldRow}>
                 <label htmlFor="invoice-number">{t('autoItemize.invoiceNumber')}</label>
-                <div className={styles.fieldControl}>
-                  <input
-                    id="invoice-number"
-                    type="text"
-                    value={metadataEdits.invoiceNumber ?? ''}
-                    onChange={(e) =>
-                      setMetadataEdits((prev) => ({
-                        ...prev,
-                        invoiceNumber: e.target.value || null,
-                      }))
-                    }
-                  />
+                <div>
+                  <div className={styles.fieldControl}>
+                    <input
+                      id="invoice-number"
+                      type="text"
+                      value={metadataEdits.invoiceNumber ?? ''}
+                      onChange={(e) =>
+                        setMetadataEdits((prev) => ({
+                          ...prev,
+                          invoiceNumber: e.target.value || null,
+                        }))
+                      }
+                    />
+                  </div>
+                  {invoiceNumberSuggestion && (
+                    <SuggestionBadge
+                      suggestedValue={invoiceNumberSuggestion}
+                      fieldLabel={t('autoItemize.invoiceNumber')}
+                      displayValue={invoiceNumberSuggestion}
+                      onApply={() => handleApplySuggestion('invoiceNumber', invoiceNumberSuggestion)}
+                    />
+                  )}
                 </div>
               </div>
 
@@ -730,18 +763,28 @@ export function AutoItemizePage() {
 
               <div className={styles.fieldRow}>
                 <label htmlFor="notes">{t('autoItemize.notes')}</label>
-                <div className={styles.fieldControl}>
-                  <textarea
-                    id="notes"
-                    value={metadataEdits.notes ?? ''}
-                    onChange={(e) =>
-                      setMetadataEdits((prev) => ({
-                        ...prev,
-                        notes: e.target.value || null,
-                      }))
-                    }
-                    rows={3}
-                  />
+                <div>
+                  <div className={styles.fieldControl}>
+                    <textarea
+                      id="notes"
+                      value={metadataEdits.notes ?? ''}
+                      onChange={(e) =>
+                        setMetadataEdits((prev) => ({
+                          ...prev,
+                          notes: e.target.value || null,
+                        }))
+                      }
+                      rows={3}
+                    />
+                  </div>
+                  {notesSuggestion && (
+                    <SuggestionBadge
+                      suggestedValue={notesSuggestion}
+                      fieldLabel={t('autoItemize.notes')}
+                      displayValue={notesSuggestion}
+                      onApply={() => handleApplySuggestion('notes', notesSuggestion)}
+                    />
+                  )}
                 </div>
               </div>
 
diff --git a/e2e/pages/AutoItemizePage.ts b/e2e/pages/AutoItemizePage.ts
index 081ba9f50..76e75ec0e 100644
--- a/e2e/pages/AutoItemizePage.ts
+++ b/e2e/pages/AutoItemizePage.ts
@@ -17,6 +17,7 @@
  *   - pageTitle: h1 with t('autoItemize.title') = "Auto-Itemize Invoice"
  *   - breadcrumb: <a class="breadcrumb"> with t('autoItemize.backToInvoice') = "Back to Invoice"
  *   - metadataCard: invoice metadata form with inputs #invoice-number, #amount, #date, #due-date, #notes
+ *   - SuggestionBadge fields: invoiceNumber, amount, date, dueDate, notes (all use same badge pattern)
  *   - statusSelect: <select id="invoice-status"> with status options
  *   - lineList: <ul role="list" aria-label="Extracted line items"> containing <li class*="lineCard">
  *   - Each lineCard:
@@ -75,6 +76,7 @@ export class AutoItemizePage {
   readonly retryButton: Locator;
 
   // Metadata form inputs
+  readonly invoiceNumberInput: Locator;
   readonly totalAmountInput: Locator;
   readonly invoiceDateInput: Locator;
   readonly dueDateInput: Locator;
@@ -205,6 +207,7 @@ export class AutoItemizePage {
     this.retryButton = page.getByRole('button', { name: /^Retry$/i });
 
     // Metadata inputs
+    this.invoiceNumberInput = page.locator('#invoice-number');
     this.totalAmountInput = page.locator('#amount');
     this.invoiceDateInput = page.locator('#date');
     this.dueDateInput = page.locator('#due-date');
@@ -313,12 +316,21 @@ export class AutoItemizePage {
    * We locate via the SuggestionBadge component's className which uses CSS Modules.
    *
    * Supported fields:
-   *   'amount'  → scoped to the #amount field's parent container
-   *   'date'    → scoped to the #date field's parent container
-   *   'dueDate' → scoped to the #due-date field's parent container
+   *   'amount'        → scoped to the #amount field's parent container
+   *   'date'          → scoped to the #date field's parent container
+   *   'dueDate'       → scoped to the #due-date field's parent container
+   *   'invoiceNumber' → scoped to the #invoice-number field's parent container
+   *   'notes'         → scoped to the #notes field's parent container
    */
-  suggestionBadge(field: 'amount' | 'date' | 'dueDate'): Locator {
-    const inputId = field === 'dueDate' ? 'due-date' : field;
+  suggestionBadge(field: 'amount' | 'date' | 'dueDate' | 'invoiceNumber' | 'notes'): Locator {
+    let inputId: string;
+    if (field === 'dueDate') {
+      inputId = 'due-date';
+    } else if (field === 'invoiceNumber') {
+      inputId = 'invoice-number';
+    } else {
+      inputId = field;
+    }
     // The badge is a sibling of the input, inside a field-control wrapper div.
     // Use ancestor traversal: input → parent div (fieldControl) → parent div → badge span.
     return this.page
@@ -330,9 +342,17 @@ export class AutoItemizePage {
 
   /**
    * Returns the Apply button inside a SuggestionBadge for a given field.
+   * Accepts the same field names as suggestionBadge().
    */
-  applyBadgeButton(field: 'amount' | 'date' | 'dueDate'): Locator {
-    const inputId = field === 'dueDate' ? 'due-date' : field;
+  applyBadgeButton(field: 'amount' | 'date' | 'dueDate' | 'invoiceNumber' | 'notes'): Locator {
+    let inputId: string;
+    if (field === 'dueDate') {
+      inputId = 'due-date';
+    } else if (field === 'invoiceNumber') {
+      inputId = 'invoice-number';
+    } else {
+      inputId = field;
+    }
     return this.page
       .locator(`#${inputId}`)
       .locator('xpath=ancestor::div[contains(@class,"fieldRow") or contains(@class,"field")]')
diff --git a/e2e/tests/invoices/invoice-auto-itemize-page.spec.ts b/e2e/tests/invoices/invoice-auto-itemize-page.spec.ts
index 5900bd910..5387bf028 100644
--- a/e2e/tests/invoices/invoice-auto-itemize-page.spec.ts
+++ b/e2e/tests/invoices/invoice-auto-itemize-page.spec.ts
@@ -30,6 +30,7 @@
  *   15. Extracted date suggestion: extractedInvoiceDate → SuggestionBadge → Apply → field updates
  *   16. PDF iframe smoke: iframe present, src contains preview URL
  *   17. VAT applies checkbox: present; vatRate input NOT in DOM
+ *   20. SuggestionBadge for invoiceNumber and notes (parallel to Scenario 15)
  *
  * Mocking strategy:
  *   - GET /api/config: intercepted to inject autoItemizeEnabled: true/false
@@ -264,7 +265,7 @@ async function mockPaperlessDocument(page: Page, docId: number, title: string):
 
 /**
  * Intercept POST /api/invoices/:id/auto-itemize (dry-run call triggered on mount).
- * Returns the given lines + warnings + optional extracted dates.
+ * Returns the given lines + warnings + optional extracted metadata fields.
  */
 async function mockAutoItemizeDryRun(
   page: Page,
@@ -274,6 +275,8 @@ async function mockAutoItemizeDryRun(
     warnings?: object[];
     extractedInvoiceDate?: string;
     extractedDueDate?: string;
+    extractedInvoiceNumber?: string;
+    extractedNotes?: string;
     status?: number;
     errorBody?: object;
     delayMs?: number;
@@ -308,6 +311,10 @@ async function mockAutoItemizeDryRun(
         warnings,
         ...(opts.extractedInvoiceDate ? { extractedInvoiceDate: opts.extractedInvoiceDate } : {}),
         ...(opts.extractedDueDate ? { extractedDueDate: opts.extractedDueDate } : {}),
+        ...(opts.extractedInvoiceNumber
+          ? { extractedInvoiceNumber: opts.extractedInvoiceNumber }
+          : {}),
+        ...(opts.extractedNotes ? { extractedNotes: opts.extractedNotes } : {}),
       }),
     });
   });
@@ -1790,3 +1797,97 @@ test.describe('Scenario 17 — VAT applies checkbox and no vatRate input', () =>
     }
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scenario 20 — SuggestionBadge for invoiceNumber and notes (parallel to Scenario 15)
+// (New in bug fix #1581 — LLM now extracts invoiceNumber and notes at document level)
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.describe('Scenario 20 — Extracted invoiceNumber and notes SuggestionBadges (Bug #1581)', () => {
+  test('SuggestionBadges appear for invoiceNumber and notes when LLM returns extracted values; Apply updates each field', async ({
+    page,
+    testPrefix,
+  }) => {
+    const vw = page.viewportSize()?.width ?? 1440;
+    if (vw < 600) {
+      test.skip(true, 'Functional test — skip on very narrow mobile');
+      return;
+    }
+
+    const autoItemizePage = new AutoItemizePage(page);
+    let vendorId = '';
+    let invoiceId = '';
+
+    try {
+      // Invoice has stored invoiceNumber 'INV-STORED' and no notes (null).
+      // LLM returns extractedInvoiceNumber: 'INV-LLM-042' (differs → badge shows)
+      // LLM returns extractedNotes: 'Facade cladding, April 2024' (differs from null → badge shows)
+      vendorId = await createVendorViaApi(page, `${testPrefix} AI-Num-Notes Vendor`);
+      invoiceId = await createInvoiceViaApi(page, vendorId, {
+        amount: 900,
+        date: '2026-06-01',
+        invoiceNumber: 'INV-STORED',
+      });
+
+      const docId = 77001;
+      await mockPaperlessDocument(page, docId, 'InvoiceNumber Notes Suggestion Doc');
+      await mockAutoItemizeDryRun(page, invoiceId, {
+        lines: THREE_LINES,
+        warnings: [],
+        extractedInvoiceNumber: 'INV-LLM-042',
+        extractedNotes: 'Facade cladding, April 2024',
+      });
+
+      await autoItemizePage.goto(invoiceId, docId);
+      await autoItemizePage.waitForAnalyzingDone();
+
+      // ── invoiceNumber input should have the stored value ──────────────────
+      await expect(autoItemizePage.invoiceNumberInput).toHaveValue('INV-STORED');
+
+      // ── notes textarea should be empty (stored notes = null) ──────────────
+      await expect(autoItemizePage.notesInput).toHaveValue('');
+
+      // ── SuggestionBadge appears adjacent to the invoiceNumber input ───────
+      const invoiceNumberBadge = autoItemizePage.suggestionBadge('invoiceNumber');
+      await expect(invoiceNumberBadge).toBeVisible();
+
+      // Badge text should contain the suggested invoice number
+      await expect(invoiceNumberBadge).toContainText('INV-LLM-042');
+
+      // ── SuggestionBadge appears adjacent to the notes textarea ────────────
+      const notesBadge = autoItemizePage.suggestionBadge('notes');
+      await expect(notesBadge).toBeVisible();
+
+      // Badge text should contain the suggested notes value
+      await expect(notesBadge).toContainText('Facade cladding, April 2024');
+
+      // ── Click Apply on the invoiceNumber badge ────────────────────────────
+      const invoiceNumberApplyBtn = invoiceNumberBadge.getByRole('button', { name: /Apply/i });
+      await expect(invoiceNumberApplyBtn).toBeVisible();
+      await invoiceNumberApplyBtn.click();
+
+      // ── invoiceNumber input should update to the LLM-extracted value ──────
+      await expect(autoItemizePage.invoiceNumberInput).toHaveValue('INV-LLM-042');
+
+      // ── invoiceNumber badge should disappear (suggestion == field value) ──
+      await expect(invoiceNumberBadge).not.toBeVisible();
+
+      // ── notes badge should still be visible (not yet applied) ────────────
+      await expect(notesBadge).toBeVisible();
+
+      // ── Click Apply on the notes badge ────────────────────────────────────
+      const notesApplyBtn = notesBadge.getByRole('button', { name: /Apply/i });
+      await expect(notesApplyBtn).toBeVisible();
+      await notesApplyBtn.click();
+
+      // ── notes textarea should update to the LLM-extracted value ──────────
+      await expect(autoItemizePage.notesInput).toHaveValue('Facade cladding, April 2024');
+
+      // ── notes badge should disappear (suggestion == field value now) ──────
+      await expect(notesBadge).not.toBeVisible();
+    } finally {
+      if (invoiceId && vendorId) await deleteInvoiceViaApi(page, vendorId, invoiceId);
+      if (vendorId) await deleteVendorViaApi(page, vendorId);
+    }
+  });
+});
diff --git a/server/src/services/budgetExtraction/openAICompatibleProvider.test.ts b/server/src/services/budgetExtraction/openAICompatibleProvider.test.ts
index 2abd8a785..c43b657cd 100644
--- a/server/src/services/budgetExtraction/openAICompatibleProvider.test.ts
+++ b/server/src/services/budgetExtraction/openAICompatibleProvider.test.ts
@@ -1016,6 +1016,88 @@ describe('validateExtractedLines()', () => {
       expect(result.lines).toHaveLength(2);
     });
   });
+
+  // ─── Story #1581 — invoiceNumber and notes on ExtractionResult ───────────────
+
+  describe('invoiceNumber and notes fields on ExtractionResult (Story #1581)', () => {
+    it('returns invoiceNumber when present as non-empty string', () => {
+      const result = validateExtractedLines({
+        invoiceNumber: 'RE-2024-001',
+        lines: [],
+      });
+
+      expect(result.invoiceNumber).toBe('RE-2024-001');
+    });
+
+    it('strips invoiceNumber: null → undefined', () => {
+      const result = validateExtractedLines({
+        invoiceNumber: null,
+        lines: [],
+      });
+
+      expect(result.invoiceNumber).toBeUndefined();
+    });
+
+    it('strips invoiceNumber with only whitespace → undefined', () => {
+      const result = validateExtractedLines({
+        invoiceNumber: '   ',
+        lines: [],
+      });
+
+      expect(result.invoiceNumber).toBeUndefined();
+    });
+
+    it('truncates invoiceNumber longer than 255 chars to exactly 255', () => {
+      const longInvoiceNumber = 'A'.repeat(300);
+      const result = validateExtractedLines({
+        invoiceNumber: longInvoiceNumber,
+        lines: [],
+      });
+
+      expect(result.invoiceNumber).toHaveLength(255);
+      expect(result.invoiceNumber).toBe('A'.repeat(255));
+    });
+
+    it('returns notes when present as non-empty string', () => {
+      const result = validateExtractedLines({
+        notes: 'This invoice covers labor for the kitchen renovation.',
+        lines: [],
+      });
+
+      expect(result.notes).toBe('This invoice covers labor for the kitchen renovation.');
+    });
+
+    it('strips notes: null → undefined', () => {
+      const result = validateExtractedLines({
+        notes: null,
+        lines: [],
+      });
+
+      expect(result.notes).toBeUndefined();
+    });
+
+    it('truncates notes longer than 1000 chars to exactly 1000', () => {
+      const longNotes = 'B'.repeat(1200);
+      const result = validateExtractedLines({
+        notes: longNotes,
+        lines: [],
+      });
+
+      expect(result.notes).toHaveLength(1000);
+      expect(result.notes).toBe('B'.repeat(1000));
+    });
+
+    it('backward compat: response with only { lines: [...] } returns invoiceNumber and notes as undefined', () => {
+      const result = validateExtractedLines({
+        lines: [{ description: 'Item A', totalAmount: 100, confidence: 0.9 }],
+      });
+
+      expect(result.invoiceNumber).toBeUndefined();
+      expect(result.notes).toBeUndefined();
+      // Core fields still work
+      expect(result.lines).toHaveLength(1);
+    });
+  });
 });
 
 // ─── Fixture-driven validate tests ───────────────────────────────────────────
diff --git a/server/src/services/budgetExtraction/openAICompatibleProvider.ts b/server/src/services/budgetExtraction/openAICompatibleProvider.ts
index 55c4c54ec..09750ec41 100644
--- a/server/src/services/budgetExtraction/openAICompatibleProvider.ts
+++ b/server/src/services/budgetExtraction/openAICompatibleProvider.ts
@@ -54,6 +54,18 @@ export function validateExtractedLines(body: unknown): ExtractionResult {
     dueDate = obj.dueDate;
   }
 
+  let invoiceNumber: string | undefined;
+  if (typeof obj.invoiceNumber === 'string' && obj.invoiceNumber.trim() !== '') {
+    const trimmed = obj.invoiceNumber.trim();
+    invoiceNumber = trimmed.length <= 255 ? trimmed : trimmed.slice(0, 255);
+  }
+
+  let notes: string | undefined;
+  if (typeof obj.notes === 'string' && obj.notes.trim() !== '') {
+    const trimmed = obj.notes.trim();
+    notes = trimmed.length > 1000 ? trimmed.slice(0, 1000) : trimmed;
+  }
+
   const lines: ExtractedLine[] = [];
 
   for (let i = 0; i < obj.lines.length; i++) {
@@ -184,7 +196,7 @@ export function validateExtractedLines(body: unknown): ExtractionResult {
     });
   }
 
-  return { invoiceDate, dueDate, lines };
+  return { invoiceDate, dueDate, invoiceNumber, notes, lines };
 }
 
 /**
diff --git a/server/src/services/budgetExtraction/prompts.ts b/server/src/services/budgetExtraction/prompts.ts
index 419b8ac68..45785a219 100644
--- a/server/src/services/budgetExtraction/prompts.ts
+++ b/server/src/services/budgetExtraction/prompts.ts
@@ -6,10 +6,12 @@ import type { ExtractionHints } from './types.js';
 
 export const SYSTEM_PROMPT = `You are an expert at extracting structured line items from German construction-trade invoices.
 
-Your task is to extract line items AND document-level date fields from the provided OCR text and return a JSON object with this exact schema:
+Your task is to extract line items AND document-level metadata fields from the provided OCR text and return a JSON object with this exact schema:
 {
   "invoiceDate": "YYYY-MM-DD" | null,
   "dueDate": "YYYY-MM-DD" | null,
+  "invoiceNumber": string | null,
+  "notes": string | null,
   "lines": [
     {
       "description": string,
@@ -33,8 +35,10 @@ IMPORTANT RULES:
    - < 0.3 = uncertain extraction, treat as guess
 4. totalAmount must always be present and should be the gross (VAT-inclusive) amount when available.
 5. invoiceDate and dueDate: extract as ISO 8601 YYYY-MM-DD strings if clearly present in the document header/footer. Output null if not found.
-6. If no line items can be reliably extracted, return { "invoiceDate": null, "dueDate": null, "lines": [] }.
-7. Output ONLY valid JSON, no markdown, no comments.`;
+6. invoiceNumber: extract the vendor's printed invoice identifier (e.g., "INV-2024-0123", "RE 2024-042") if clearly present. Output null if not found.
+7. notes: write ONE short sentence (≤120 chars) summarizing what this invoice covers (e.g., "Bathroom tile installation, March 2024"). Keep it factual and brief. Output null if you cannot determine the content.
+8. If no line items can be reliably extracted, return { "invoiceDate": null, "dueDate": null, "invoiceNumber": null, "notes": null, "lines": [] }.
+9. Output ONLY valid JSON, no markdown, no comments.`;
 
 export function buildUserPrompt(ocrText: string, hints: ExtractionHints): string {
   const vendorName = hints.vendorName ?? 'unknown';
@@ -53,5 +57,5 @@ Locale: ${locale}
 ${ocrText}
 ---
 
-Return the extracted data as a JSON object with schema { "invoiceDate": "YYYY-MM-DD" | null, "dueDate": "YYYY-MM-DD" | null, "lines": ExtractedLine[] }.`;
+Return the extracted data as a JSON object with schema { "invoiceDate": "YYYY-MM-DD" | null, "dueDate": "YYYY-MM-DD" | null, "invoiceNumber": string | null, "notes": string | null, "lines": ExtractedLine[] }.`;
 }
diff --git a/server/src/services/budgetExtraction/providerProfiles.test.ts b/server/src/services/budgetExtraction/providerProfiles.test.ts
index 43772f717..5416c37e0 100644
--- a/server/src/services/budgetExtraction/providerProfiles.test.ts
+++ b/server/src/services/budgetExtraction/providerProfiles.test.ts
@@ -109,7 +109,7 @@ describe('buildRequestBody', () => {
           type: string;
           required: string[];
           additionalProperties: boolean;
-          properties: {
+          properties: Record<string, unknown> & {
             lines: {
               type: string;
               items: {
@@ -130,8 +130,21 @@ describe('buildRequestBody', () => {
     // strict mode requires additionalProperties: false on every object node.
     expect(rf.json_schema.schema.additionalProperties).toBe(false);
     expect(rf.json_schema.schema.properties.lines.items.additionalProperties).toBe(false);
+
+    // Story #1581: top-level schema now includes invoiceDate, dueDate, invoiceNumber, notes.
+    expect(rf.json_schema.schema.required).toEqual(
+      expect.arrayContaining(['invoiceDate', 'dueDate', 'invoiceNumber', 'notes', 'lines']),
+    );
+
+    // Top-level properties include all four document-level fields.
+    const topLevelProps = Object.keys(rf.json_schema.schema.properties);
+    expect(topLevelProps).toContain('invoiceDate');
+    expect(topLevelProps).toContain('dueDate');
+    expect(topLevelProps).toContain('invoiceNumber');
+    expect(topLevelProps).toContain('notes');
+
     // strict mode requires EVERY property to be listed in `required` (optional
-    // fields use union-typed nulls).
+    // fields use union-typed nulls). vatRate was REMOVED from the line schema in #1581.
     expect(rf.json_schema.schema.properties.lines.items.required).toEqual(
       expect.arrayContaining([
         'description',
@@ -140,11 +153,16 @@ describe('buildRequestBody', () => {
         'unitPrice',
         'totalAmount',
         'includesVat',
-        'vatRate',
         'vendorName',
         'confidence',
       ]),
     );
+
+    // vatRate must NOT be in the line items required array (Story #1581 removal).
+    expect(rf.json_schema.schema.properties.lines.items.required).not.toContain('vatRate');
+
+    // vatRate must NOT be in the line items properties (Story #1581 removal).
+    expect(rf.json_schema.schema.properties.lines.items.properties).not.toHaveProperty('vatRate');
   });
 
   it('generic → no response_format hint', () => {
diff --git a/server/src/services/budgetExtraction/providerProfiles.ts b/server/src/services/budgetExtraction/providerProfiles.ts
index 6b16fb321..376d0bb8f 100644
--- a/server/src/services/budgetExtraction/providerProfiles.ts
+++ b/server/src/services/budgetExtraction/providerProfiles.ts
@@ -29,7 +29,7 @@ export const LLM_PROVIDERS: readonly LlmProvider[] = [
 
 /**
  * JSON schema for the response Anthropic must conform to. Mirrors the
- * `ExtractedLine[]` shape validated at parse time by `validateExtractedLines`.
+ * `ExtractionResult` shape validated at parse time by `validateExtractedLines`.
  * Anthropic's OpenAI-compat layer requires this when `response_format.type`
  * is `'json_schema'`.
  */
@@ -47,6 +47,10 @@ const EXTRACTED_LINES_SCHEMA = {
   schema: {
     type: 'object',
     properties: {
+      invoiceDate: { type: ['string', 'null'] },
+      dueDate: { type: ['string', 'null'] },
+      invoiceNumber: { type: ['string', 'null'] },
+      notes: { type: ['string', 'null'] },
       lines: {
         type: 'array',
         items: {
@@ -58,7 +62,6 @@ const EXTRACTED_LINES_SCHEMA = {
             unitPrice: { type: ['number', 'null'] },
             totalAmount: { type: 'number' },
             includesVat: { type: ['boolean', 'null'] },
-            vatRate: { type: ['number', 'null'] },
             vendorName: { type: ['string', 'null'] },
             confidence: { type: 'number' },
           },
@@ -69,7 +72,6 @@ const EXTRACTED_LINES_SCHEMA = {
             'unitPrice',
             'totalAmount',
             'includesVat',
-            'vatRate',
             'vendorName',
             'confidence',
           ],
@@ -77,7 +79,7 @@ const EXTRACTED_LINES_SCHEMA = {
         },
       },
     },
-    required: ['lines'],
+    required: ['invoiceDate', 'dueDate', 'invoiceNumber', 'notes', 'lines'],
     additionalProperties: false,
   },
 } as const;
diff --git a/server/src/services/invoiceAutoItemizeService.test.ts b/server/src/services/invoiceAutoItemizeService.test.ts
index 05591214b..c171e5e23 100644
--- a/server/src/services/invoiceAutoItemizeService.test.ts
+++ b/server/src/services/invoiceAutoItemizeService.test.ts
@@ -1594,4 +1594,111 @@ describe('invoiceAutoItemizeService', () => {
       expect(mockFetch).not.toHaveBeenCalled();
     });
   });
+
+  // ─── Story #1581 — dry-run propagates invoiceNumber + notes fields ────────────
+
+  describe('dry-run response includes extractedInvoiceNumber and extractedNotes (Story #1581)', () => {
+    /**
+     * Build an LLM response that includes all four top-level metadata fields
+     * (invoiceDate, dueDate, invoiceNumber, notes) alongside the lines array.
+     */
+    function makeLlmResponseWithMetadata(
+      metadata: {
+        invoiceDate?: string;
+        dueDate?: string;
+        invoiceNumber?: string;
+        notes?: string;
+      },
+      lines: Array<{ description: string; totalAmount: number; confidence: number }>,
+    ): object {
+      const content: Record<string, unknown> = { lines };
+      if (metadata.invoiceDate !== undefined) content.invoiceDate = metadata.invoiceDate;
+      if (metadata.dueDate !== undefined) content.dueDate = metadata.dueDate;
+      if (metadata.invoiceNumber !== undefined) content.invoiceNumber = metadata.invoiceNumber;
+      if (metadata.notes !== undefined) content.notes = metadata.notes;
+      return {
+        choices: [
+          {
+            message: {
+              content: JSON.stringify(content),
+            },
+          },
+        ],
+      };
+    }
+
+    it('returns extractedInvoiceNumber and extractedNotes when LLM provides both', async () => {
+      const vendorId = insertVendor(db);
+      const invoiceId = insertInvoice(db, vendorId, 200);
+      linkDocument(db, invoiceId, 42);
+
+      mockFetch
+        .mockResolvedValueOnce(makeOkFetch(makePaperlessRawDoc()))
+        .mockResolvedValueOnce(makeOkFetch(PAPERLESS_TAGS_RESPONSE))
+        .mockResolvedValueOnce(
+          makeOkFetch(
+            makeLlmResponseWithMetadata(
+              {
+                invoiceDate: '2024-01-15',
+                dueDate: '2024-02-15',
+                invoiceNumber: 'RE-2024-001',
+                notes: 'Kitchen renovation materials',
+              },
+              [{ description: 'Item A', totalAmount: 100, confidence: 0.9 }],
+            ),
+          ),
+        );
+
+      const config = makeConfig();
+      const result = (await autoItemize(
+        db,
+        config,
+        invoiceId,
+        'user-1',
+        { paperlessDocumentId: 42, mode: 'append', dryRun: true },
+        PAPERLESS_AUTH,
+      )) as {
+        lines: unknown[];
+        warnings: unknown[];
+        extractedInvoiceDate?: string;
+        extractedDueDate?: string;
+        extractedInvoiceNumber?: string;
+        extractedNotes?: string;
+      };
+
+      expect(result.extractedInvoiceNumber).toBe('RE-2024-001');
+      expect(result.extractedNotes).toBe('Kitchen renovation materials');
+      // Also verify the date fields still work alongside the new fields
+      expect(result.extractedInvoiceDate).toBe('2024-01-15');
+      expect(result.extractedDueDate).toBe('2024-02-15');
+      expect(Array.isArray(result.lines)).toBe(true);
+    });
+
+    it('omits extractedInvoiceNumber and extractedNotes when LLM provides neither', async () => {
+      const vendorId = insertVendor(db);
+      const invoiceId = insertInvoice(db, vendorId, 200);
+      linkDocument(db, invoiceId, 42);
+
+      // LLM response with no invoice-number or notes fields (only lines)
+      setupDryRunFetch([{ description: 'Item A', totalAmount: 100, confidence: 0.9 }]);
+
+      const config = makeConfig();
+      const result = (await autoItemize(
+        db,
+        config,
+        invoiceId,
+        'user-1',
+        { paperlessDocumentId: 42, mode: 'append', dryRun: true },
+        PAPERLESS_AUTH,
+      )) as {
+        lines: unknown[];
+        warnings: unknown[];
+        extractedInvoiceNumber?: string;
+        extractedNotes?: string;
+      };
+
+      expect(result.extractedInvoiceNumber).toBeUndefined();
+      expect(result.extractedNotes).toBeUndefined();
+    });
+  });
 });
diff --git a/server/src/services/invoiceAutoItemizeService.ts b/server/src/services/invoiceAutoItemizeService.ts
index e283ea706..0b34617cb 100644
--- a/server/src/services/invoiceAutoItemizeService.ts
+++ b/server/src/services/invoiceAutoItemizeService.ts
@@ -153,6 +153,8 @@ export async function autoItemize(
       warnings,
       ...(result.invoiceDate !== undefined ? { extractedInvoiceDate: result.invoiceDate } : {}),
       ...(result.dueDate !== undefined ? { extractedDueDate: result.dueDate } : {}),
+      ...(result.invoiceNumber !== undefined ? { extractedInvoiceNumber: result.invoiceNumber } : {}),
+      ...(result.notes !== undefined ? { extractedNotes: result.notes } : {}),
     };
   }
 
diff --git a/shared/src/types/budgetExtraction.ts b/shared/src/types/budgetExtraction.ts
index b3c89719b..6c0aa92bf 100644
--- a/shared/src/types/budgetExtraction.ts
+++ b/shared/src/types/budgetExtraction.ts
@@ -38,7 +38,7 @@ export interface ExtractionHints {
 
 /**
  * Top-level extraction result from the LLM provider.
- * Carries document-level extracted fields (invoiceDate, dueDate) alongside line items.
+ * Carries document-level extracted fields (invoiceDate, dueDate, invoiceNumber, notes) alongside line items.
  * Introduced in story #1576.
  */
 export interface ExtractionResult {
@@ -46,5 +46,9 @@ export interface ExtractionResult {
   invoiceDate?: string;
   /** ISO 8601 date (YYYY-MM-DD) if the LLM extracted a due date, else absent. */
   dueDate?: string;
+  /** Vendor's invoice identifier (max 255 chars) if extracted, else absent. */
+  invoiceNumber?: string;
+  /** One-sentence summary (max 1000 chars) if extracted, else absent. */
+  notes?: string;
   lines: ExtractedLine[];
 }
diff --git a/shared/src/types/invoiceAutoItemize.ts b/shared/src/types/invoiceAutoItemize.ts
index fcf574c89..eb2151167 100644
--- a/shared/src/types/invoiceAutoItemize.ts
+++ b/shared/src/types/invoiceAutoItemize.ts
@@ -48,6 +48,10 @@ export interface AutoItemizeDryRunResponse {
   extractedInvoiceDate?: string;
   /** ISO 8601 due date extracted by the LLM, if available. */
   extractedDueDate?: string;
+  /** Vendor's invoice identifier extracted by the LLM, if available. */
+  extractedInvoiceNumber?: string;
+  /** One-sentence summary extracted by the LLM, if available. */
+  extractedNotes?: string;
 }
 
 // Commit response re-uses InvoiceBudgetLineListDetailResponse from invoiceBudgetLine