feat(reports): add source report data, mark-claimed, and Paperless upload endpoints

.claude/agent-memory/e2e-test-engineer/known-flakes-and-regressions.md

@@ -20,12 +20,15 @@ metadata:
 
 ## Resolved / fixed
 
+- **`orientations.spec.ts:389` "ManagePage now has 5 tabs" (2026-07-29, full-matrix shards 6/11/15, all viewports)**: stale tab-count assertion — Story #1877 (merged to `beta`) added the Household tab as the first ManagePage tab, making 6, but this spec's tab-count test wasn't updated when `settings-manage.spec.ts`'s equivalent assertion was. Fixed: `toHaveCount(5)` → `toHaveCount(6)`, test title updated to list Household first. No per-tab-name iteration array existed elsewhere in this file needing updates — the only per-tab-name check is the separate "Clicking Orientations tab..." test, unaffected by the count change.
+  **IMPORTANT — ManagePage tab-count assertions live in TWO spec files that must both be updated whenever ManagePage tabs change**: `e2e/tests/navigation/settings-manage.spec.ts` (line ~895, `toHaveCount(6)`, the authoritative/comprehensive one — already correct) and `e2e/tests/orientations.spec.ts` (line ~389, a secondary/narrower assertion added when the Orientations tab was introduced, tag `@responsive`, comment says "extends settings-manage.spec.ts coverage"). Grep both for `toHaveCount(` + tab-count when adding/removing a ManagePage tab.
+
 - **PR #1883 full-E2E matrix (2026-07-29, shards 5/6/11/15 of run 30467895559)**: 4 distinct test-bug fixes, all test-only (no production regression):
   1. `settings-manage.spec.ts` lines 162, 250, 917 — `getByRole('tab', { name: 'Household' })` (default substring match) also matched "Household Item Categories" → strict-mode violation on `.click()`/`toHaveAttribute()`. Fixed with `{ name: 'Household', exact: true }`. Confirmed via CI logs across desktop/tablet/mobile shards — same 3 tests (line 156, 247, 904) failed identically on all three viewports. The 6-tab count assertion (line 895, `toHaveCount(6)`) was speculated as possibly-wrong in the initial diagnosis but was NOT actually failing in CI and is correct in `ManagePage.tsx` (Household/Areas/Trades/Orientations/Budget Categories/HI Categories, all unconditional — `isAdmin` only gates the separate `SubNav` links, not these `role="tab"` buttons) — no change needed.
   2. `invoices.spec.ts:395` "Clicking an invoice row navigates to the invoice detail page" — `invoicesPage.goto()` (unfiltered) + filter-by-text on `[class*="invoiceLink"]:visible` can miss the row: default sort is `date desc` with `pageSize=25`, and with parallel workers all creating invoices concurrently, this test's fixed `date: '2026-01-10'` can rank past page 1. Fixed by using `invoicesPage.search(`${testPrefix}-ROW-001`)` (server-side `invoiceNumber` LIKE match) instead of `goto()`, scoping the table to just this test's own row regardless of concurrent invoice volume.
   3. `invoices.spec.ts:841` "Effective Amount"/"Remaining Amount" column toggle test — root cause is `table.invoices.columns` being a per-user **server-side singleton preference** (`useColumnPreferences`/`usePreferences`, debounced 500ms save + optimistic re-sync effect), not per-test-entity state. Attempt 1 failed with `getColumnCellText` unable to find "Remaining Amount" header milliseconds after a `toBeVisible()` assertion on that same header passed (transient re-render from the debounce/resync effect landing mid-test); the retry then failed immediately because attempt 1's debounced save had persisted "Effective Amount"=visible to the DB before teardown, and retries share the same app/DB (only the browser context resets). Fixed two ways: (a) delete the preference via `page.request.delete('/api/users/me/preferences/table.invoices.columns')` both defensively-before (right before the baseline "not visible" assertions) and in `finally` (so it never leaks into a retry or into a later test); (b) made `InvoicesPage.getColumnCellText()`'s header-scan retry via `expect(async () => {...}).toPass({ timeout: 3_000 })` so a transient render race self-heals instead of throwing on a single unretried read. Same class of bug as the WebKit post-click-read races already documented above ("read immediately post-click on WebKit") — general lesson: never do a single unretried DOM read immediately after a state-changing click when the state is persisted through a debounced/async side-channel.
-  Dashboard `dashboard.spec.ts:566` "Customize button appears when card dismissed" also failed in the same run (shard 5) — this is the **already-documented** preferences-race known flake (see entry below, originally "fixed" PR #1445 but still recurs) — left untouched per existing triage, no new action.
-  Note: `invoices.spec.ts` itself has **zero diff vs `origin/beta`** — these are pre-existing latent bugs from an earlier story (#1876), not introduced by #1877; they just happened to surface in PR #1883's E2E run because full E2E runs on every PR regardless of which files changed.
+     Dashboard `dashboard.spec.ts:566` "Customize button appears when card dismissed" also failed in the same run (shard 5) — this is the **already-documented** preferences-race known flake (see entry below, originally "fixed" PR #1445 but still recurs) — left untouched per existing triage, no new action.
+     Note: `invoices.spec.ts` itself has **zero diff vs `origin/beta`** — these are pre-existing latent bugs from an earlier story (#1876), not introduced by #1877; they just happened to surface in PR #1883's E2E run because full E2E runs on every PR regardless of which files changed.
 
 - **Issue #1829 (2026-07-08)** shard-3 diary flakes on main-targeted PRs: `diary-drafts.spec.ts:854` (Scenario 14) was genuinely failing on both attempt + retry — `test.slow()`'s 45s total test budget was being exhausted by 4 oversized nested step timeouts (30-45s each) before reaching cleanup, surfacing as `apiRequestContext.delete: Test timeout exceeded`. Fixed via `test.setTimeout(60_000)` + proportionate 15s step ceilings + `testInfo.setTimeout(testInfo.timeout + 15_000)` guaranteed-cleanup-time pattern in `finally`. `diary-r2-uat.spec.ts:599` (Scenario 10) had a genuine secondary race (always-empty mock defeats `waitForLoaded()`, letting a stale prior response satisfy the next `waitForResponse`) — fixed by awaiting each transition's own response explicitly and reading straight off the resolved `Response` object. `document-linking.spec.ts:369` was NOT an independent bug — confirmed via job logs it was cancelled mid-flight (1.6s runtime) as `maxFailures:1` collateral once drafts:854 exhausted its retries; no test-logic fix needed, just added the guaranteed-cleanup-time pattern defensively. Full root cause + `maxFailures`/retry-accounting proof (Playwright source citation) in [bug-1829-shard3-flakes.md](bug-1829-shard3-flakes.md). AC #3 (fail-fast retry tolerance) was already satisfied by Playwright's built-in behavior — no config change needed, only documented.
 - Diary Scenario 14 (`diary-drafts.spec.ts` draft-card-click-navigates) — was a persistent flake even after an earlier partial fix (PR #1671); root-caused and properly fixed via `fix/diary-scenario14-e2e-flake` (register `waitForResponse` before the click, not after). Recurred 2026-07-07 with a DIFFERENT failure signature (teardown-timeout, not nav-timing) — see #1829 entry above for the follow-up fix.

.claude/agent-memory/qa-integration-tester/environment-setup.md

@@ -70,3 +70,22 @@ NODE_PATH=/path/to/cornerstone/server/node_modules:/path/to/cornerstone/client/n
   → After changing `shared/src/types/`, rebuild main project's dist OR copy worktree dist files:
   `cp -r /worktree/shared/dist /path/to/cornerstone/shared/`
 - Server tests (better-sqlite3 native binary) may SIGKILL on ARM64 sandbox — validate via CI if needed
+
+## Haste Map Collision When Running Jest From the Main Repo Dir (Not a Worktree Issue)
+
+When running Jest from the **main project directory** (not a worktree) and `.claude/worktrees/` contains
+several stale worktrees, jest-haste-map scans them too and throws `The name '@cornerstone/shared' was
+looked up in the Haste module map... several different files... provide a module for that particular
+name` — because each worktree has its own `shared/package.json`. This is intermittent/order-dependent:
+one test file in a multi-file jest invocation may fail this way while another in the same run succeeds.
+
+**Fix**: add `--modulePathIgnorePatterns='<rootDir>/\.claude/worktrees'` to the jest CLI invocation:
+
+```bash
+NODE_OPTIONS=--experimental-vm-modules npx jest <test files> --maxWorkers=1 \
+  --modulePathIgnorePatterns='<rootDir>/\.claude/worktrees'
+```
+
+Confirmed working on Story #1878 follow-up (2026-07-29): `sourceReports.test.ts` failed with the haste
+error until this flag was added; `sourceReportService.test.ts` (run first in the same invocation) was
+unaffected. Not a jest.config.ts change — CLI flag only, keeps other suites unaffected.