Initial commit

2025-10-11 08:41:36 +01:00
commit b324ff09ef
276 changed files with 55220 additions and 0 deletions
--- a/Journeys.md
+++ b/Journeys.md
@@ -0,0 +1,927 @@
+# AI Tax Agent — UX Spec & Journey Catalog (v1)
+
+> Audience: Product, Design, Frontend & QA. This document defines **all user interactions** and **end‑to‑end journeys** across personas (Individual, Accountant/Firm, Admin/Ops, RPA Operator, Cross‑Border/Expat). It aligns with the architecture: **Neo4j graph (completeness/lineage)** + **Qdrant vector search (guidance/fields/evidence)** + **RPA**.
+
+---
+
+## 0) Design Tenets
+
+- **Explainable by design**: Every decision references a rule/field/guidance citation. Lineage is one click away.
+- **Guided, not gated**: Wizard with a live “Completeness checklist”. Users can skip and return.
+- **Draft‑safe**: Everything is autosaved, idempotent, and recoverable.
+- **Privacy‑first**: PII masked by default; reveal is explicit and audited.
+- **Jurisdiction‑aware**: UI adapts labels, formats (en‑GB / el‑GR), deadlines, and required pages.
+- **Low‑friction evidence**: Upload anywhere; extraction & mapping run in the background with visible status.
+- **Keyboard & screen‑reader friendly**: WCAG 2.1 AA.
+
+---
+
+## 1) Personas & Primary Goals
+
+- **Individual (B2C)**: File accurately with minimal effort; understand what’s missing and why.
+- **Accountant / Firm (B2B)**: Triage portfolio, automate routine, keep audit trail, file at scale.
+- **Admin / Ops**: Configure jurisdictions, monitor health, manage catalogs/flags, ensure compliance.
+- **RPA Operator / Support**: Orchestrate robot sessions, handle MFA/DOM drift, capture artifacts.
+- **Cross‑Border / Expat**: Manage multi‑jurisdiction obligations in one place.
+
+---
+
+## 2) Information Architecture & Navigation
+
+**Top‑level navigation (role‑aware):** Dashboard · Profiles/Clients · Documents · Reconciliation · Build & QA · Submissions · Guidance · Admin (role gated)
+
+**Context switchers:**
+
+- **Firm selector** (Accountant)
+- **Jurisdiction & Tax Year** per profile
+
+**Global elements:**
+
+- Search bar (fields + guidance powered by vector search)
+- Notifications (jobs: OCR/extract/index/RPA)
+- Profile switcher
+- Help & audit log links
+
+---
+
+## 3) UI Patterns & Key Components
+
+- **Wizard** (Profile → Bank → State Data → Upload → Reconcile → Build → QA → Submit → Archive)
+- **Completeness checklist** (Graph): Required pages & missing fields, deep links.
+- **Lineage panel**: Field → Calculation → Rule → Guidance citation; copy citation.
+- **Document Inbox**: Upload, progress, OCR status, extraction results, evidence links.
+- **Reconciliation dashboard**: Rents vs deposits; interest deltas; exceptions with CTAs.
+- **Semantic search** (Vector): Results for fields/rules/guidance with facet chips (jurisdiction, year, form/page).
+- **Masking controls**: AFM/UTR/NINO hidden by default; “Reveal” with audit.
+- **Toasts & job status chips**: queued · running · succeeded · failed.
+
+---
+
+## 4) Journeys by Persona
+
+### 4.1 Individual (B2C)
+
+#### I‑1 Sign‑in & Locale
+
+**Entry**: Landing → “Sign in”
+**Steps**: OIDC (PKCE) → consent → pick language (en‑GB/el‑GR)
+**System**: Session established; locale persisted
+**Exit**: Dashboard with “Start your {Jurisdiction} {Tax Year} filing”
+
+#### I‑2 Create/Select Profile
+
+**Entry**: Dashboard → “New filing”
+**Steps**: Choose Jurisdiction (UK/GR), Tax Year; add identifiers (AFM/UTR/NINO); save
+**System**: Creates `TaxpayerProfile`; graph completeness bootstraps
+**Exit**: Wizard step 1 with checklist
+
+#### I‑3 Connect Bank (optional)
+
+**Entry**: Wizard → “Connect bank”
+**Steps**: Redirect to bank consent → approve → back
+**System**: Accounts/transactions synced; recon pre‑computed
+**Exit**: Bank tiles; recon hints show
+
+#### I‑4 Fetch State Data (optional)
+
+**Entry**: Wizard → “Fetch from portal”
+**Steps**: Start RPA → MFA if needed → retrieve PDFs
+**System**: Files saved; OCR/extract jobs launched; lineage recorded
+**Exit**: Documents tab shows new items with status
+
+#### I‑5 Upload Documents
+
+**Entry**: Documents → “Upload”
+**Steps**: Drag & drop → progress → OCR → Extract
+**System**: Entities validated; `PROVIDED` edges to fields; evidence chunks indexed
+**Exit**: Completeness updates; toasts show results
+
+#### I‑6 Guidance & Field Search
+
+**Entry**: Global search
+**Steps**: Query “rental income” or “bank interest”
+**System**: Vector top‑k → mapped to fields/rules; open lineage/guidance
+**Exit**: User navigates directly to the correct field
+
+#### I‑7 Completeness & Fix‑ups
+
+**Entry**: Checklist panel
+**Steps**: Click missing item → form field view → enter value
+**System**: `provide` call; re‑run completeness
+**Exit**: Item disappears; checklist can reach “All set”
+
+#### I‑8 Build & QA
+
+**Entry**: Build page
+**Steps**: Click “Build return” → Review payload summary → “Run QA”
+**System**: Blocking vs warnings; deep link to issues
+**Exit**: QA green or remaining warnings acknowledged
+
+#### I‑9 Submission (Dry → Live)
+
+**Entry**: Submit
+**Steps**: Dry run (RPA) → review screenshots → confirm Live (if enabled)
+**System**: Archive bundle; receipt
+**Exit**: Success screen with download links
+
+#### I‑10 Archive & Support
+
+**Entry**: Submissions
+**Steps**: Download receipt; open lineage; contact support
+**System**: Audit log entries
+**Exit**: Filing closed
+
+**Edge cases**: Bank revoked; OCR low confidence; rule ambiguity → show explainers & next‑best action.
+
+---
+
+### 4.2 Accountant / Firm (B2B)
+
+#### F‑1 Login & Firm Context
+
+**Entry**: OIDC login
+**Steps**: Select Firm (if multi‑firm)
+**System**: `X‑Firm‑Id` header set
+**Exit**: Firm dashboard
+
+#### F‑2 Bulk Client Onboarding
+
+**Entry**: Clients → “Import CSV”
+**Steps**: Upload template; map columns (AFM/UTR, name, year)
+**System**: Profiles created/updated; errors inline
+**Exit**: Worklist populated
+
+#### F‑3 Portfolio Triage
+
+**Entry**: Dashboard
+**Steps**: Filters (jurisdiction/year/status); sort by due date/exception count
+**System**: Saved views; counts; SLA badges
+**Exit**: Prioritized queue
+
+#### F‑4 Document Intake at Scale
+
+**Entry**: Client detail → Documents
+**Steps**: Multi‑upload; run OCR/extract; monitor jobs
+**System**: Batch tasks; progress per client
+**Exit**: Completeness shrinks across profiles
+
+#### F‑5 State Data Fetch (Bulk RPA)
+
+**Entry**: Actions → “Fetch”
+**Steps**: Select clients; schedule; monitor
+**System**: Rate‑limited sessions; screenshots; retries
+**Exit**: Evidence attached for many clients
+
+#### F‑6 Reconciliation Dashboards
+
+**Entry**: Recon tab
+**Steps**: Rents vs deposits; interest deltas; export CSV
+**System**: Exceptions with direct CTAs to fields
+**Exit**: Reduced exception backlog
+
+#### F‑7 Completeness & NBA (Bulk)
+
+**Entry**: Worklist
+**Steps**: Open completeness per client; batch provide (defaults)
+**System**: Idempotent provides; audit trail
+**Exit**: Many files move to “Ready to build”
+
+#### F‑8 Build/QA/Submit (Per client or Bulk)
+
+**Entry**: Actions
+**Steps**: Build → QA → dry submit → (optionally) live submit
+**System**: Archive receipts; prevent duplicates via Idempotency‑Key
+**Exit**: Filed returns with artifacts
+
+#### F‑9 Audit & Explainability
+
+**Entry**: Client page
+**Steps**: Open lineage for totals; copy citations
+**System**: Graph traversal with guidance
+**Exit**: Audit‑ready documentation
+
+#### F‑10 Reporting & KPIs
+
+**Entry**: Analytics
+**Steps**: Throughput; auto‑complete %; exception rate
+**System**: Grafana panels embedded links
+**Exit**: Operational insights
+
+**Edge cases**: Conflicting docs; mismatched identifiers; consent expiry; rate limits.
+
+---
+
+### 4.3 Admin / Ops
+
+#### A‑1 Jurisdiction & Catalog Config
+
+**Entry**: Admin → Catalog
+**Steps**: Enable/disable forms; set tax‑year visibility; upload new schema versions
+**System**: Flags stored; migration checks
+**Exit**: UI reflects new scope
+
+#### A‑2 Health & Observability
+
+**Entry**: Admin → Health
+**Steps**: View /health, /metrics; error rates; queue lag
+**System**: Alerts linked; runbook links
+**Exit**: Acknowledged incidents
+
+#### A‑3 Access & Audit
+
+**Entry**: Admin → Security
+**Steps**: Roles; access logs; export audits
+**System**: PII redaction enforced
+**Exit**: Compliance evidence generated
+
+#### A‑4 Webhooks & Integrations
+
+**Entry**: Admin → Integrations
+**Steps**: Configure webhooks (upload, consent); test delivery
+**System**: Signed events; retries
+**Exit**: Integrations online
+
+---
+
+### 4.4 RPA Operator / Support
+
+#### R‑1 Session Control
+
+**Entry**: RPA Control Room
+**Steps**: Start session; observe steps; MFA pause → resume
+**System**: Screenshots, DOM selectors
+**Exit**: Jobs succeed or re‑queued
+
+#### R‑2 DOM Drift Recovery
+
+**Entry**: On error
+**Steps**: Edit selectors; retry step; file incident
+**System**: Config updated; audit trail
+**Exit**: Flow unblocked
+
+---
+
+### 4.5 Cross‑Border / Expat
+
+#### X‑1 Dual Profile Setup
+
+**Entry**: Profile → “Add jurisdiction”
+**Steps**: Add UK & GR profiles; link identifiers
+**System**: `Taxpayer` → `HAS_PROFILE` (UK, GR)
+**Exit**: Two scoped profiles
+
+#### X‑2 Foreign Income & Credits
+
+**Entry**: Income panel
+**Steps**: Declare foreign income; upload proof; run completeness both sides
+**System**: Rules trigger correct pages; lineage cites treaties/guidance
+**Exit**: Correct forms required
+
+#### X‑3 Dual Build & Submission
+
+**Entry**: Build/QA per jurisdiction
+**Steps**: Build UK + GR; QA; (dry) submit; archive both
+**System**: Two receipts; one evidence bundle
+**Exit**: Fully compliant filing
+
+---
+
+## 5) Screen Inventory & States
+
+- **Dashboard**: Cards by status; due dates; resume buttons; empty state with CTA.
+- **Profile Editor**: Identifiers (masked), jurisdiction/year pickers; validation errors inline.
+- **Documents Inbox**: Upload area; list with statuses; filters; preview with OCR text & entities; lineage tab.
+- **Evidence Browser** _(new)_: Global list of documents/evidence; filters (kind, source, year, linked/unlinked); batch attach to fields.
+- **Transaction Detail** _(new)_: View single transaction; related documents; link/unlink to fields.
+- **Search Results**: Tabs for Fields · Rules · Guidance; chips for jurisdiction/year/form; result actions: “Go to field”, “Open guidance”, “Copy citation”.
+- **Completeness Panel**: Required pages list; missing fields; “Provide” inline; progress meter.
+- **Form Builder**: Collapsible sections per page; computed fields badge; “Show lineage”.
+- **QA Report**: Blocking vs Warnings; deep links to fields; export.
+- **Submission**: Dry‑run gallery; confirm dialog; success screen with receipt links.
+- **Recon Dashboard**: Exceptions table; “Fix” CTAs; CSV export.
+- **Admin Panels**: Catalog, Health, Integrations, Security.
+- **RPA Control Room**: Job list; live viewer; pause/resume; step logs.
+
+**State management**: loading, empty, partial (draft), error; offline fallback where possible.
+
+---
+
+## 6) Interaction Details & Microcopy
+
+- **Mask toggle**: “Reveal for 30s” (tooltip: “AFM/UTR is sensitive. We log this event.”)
+- **Completeness empty**: “All set — you can build your return now.”
+- **QA blocking**: “You must resolve these before submission.”
+- **Retry UI**: “We’ll retry automatically in 30s” with timer on 429.
+- **Evidence chips**: “From: Bank_2024_May.pdf (p.3)” → opens preview at the exact chunk highlight.
+- **Lineage**: “Calculated via E2_NET from A1 and A2 — See guidance (Section 2).”
+
+---
+
+## 7) Accessibility & Internationalization
+
+- Keyboard access (tab order, skip‑to‑content, visible focus)
+- Labels/aria for dynamic panels (completeness, lineage)
+- Color contrast ≥ 4.5:1; no color‑only cues
+- Date, currency, and number formats per jurisdiction; translated microcopy (en‑GB/el‑GR)
+
+---
+
+## 8) Telemetry & KPIs (per journey)
+
+- **Funnel**: Upload → OCR → Extract → Provide → Build → QA → Submit
+- **Search**: query → click‑through → success (did they navigate to a field?)
+- **Completeness**: time to green; # of missing fields when user first opens
+- **RPA**: success rate; avg steps; DOM drift incidents
+- **Recon**: exceptions resolved per week
+
+All events include: `user_role`, `jurisdiction`, `tax_year`, `profile_id` (hashed), `correlation_id`.
+
+---
+
+## 9) Acceptance Criteria (UX)
+
+- Every journey above has a **happy path** that is keyboard‑accessible and screen‑reader friendly.
+- Each screen has **empty / loading / error** states and helpful recovery.
+- Completeness always matches graph results; lineage opens within 1s and shows rule + guidance.
+- Vector search returns actionable results with jurisdiction filters visible.
+- Sensitive identifiers masked by default; reveal audited.
+- i18n covers 100% of visible strings for en‑GB and el‑GR.
+
+---
+
+## 10) Mobile & Responsive
+
+- Breakpoints: sm (mobile), md (tablet), lg (desktop)
+- Documents inbox and wizard optimized for one‑column flow on mobile
+- Tables become stacked cards with key actions as primary buttons
+
+---
+
+## 11) Handoff Artifacts
+
+- Component library (shadcn/ui + Tailwind), tokens for spacing/typography
+- Figma (or equivalent) pages: Dashboard, Profile, Documents, Search, Completeness, Form Builder, QA, Submission, Recon, Admin, RPA
+- Copy deck for both locales; glossary for tax terms
+
+---
+
+## 12) Risks & Mitigations (UX)
+
+- **Overwhelm in completeness** → progressive disclosure, quick filters (page/mandatory/has evidence)
+- **Trust in automation** → surface citations + screenshots; allow explicit user confirmation before live submit
+- **Jurisdiction confusion** → consistent badge + sticky selector; scoped search and guidance
+
+## 13) Detail Screens — Form Field, Page, and Form (UI Specs)
+
+### 13.1 Form Field Detail View
+
+**Route:** `/profiles/:profileId/fields/:fieldId`
+**Purpose:** Single source of truth to **view/edit a field**, with **lineage, evidence, rules, validation, history**.
+
+**Layout (desktop):**
+
+- **Header bar:** Breadcrumbs (Profile → Form → Page → Field) · Jurisdiction/Year pills · Status chip (Missing / Provided / Computed / Overridden / N/A).
+- **Two‑column body:**
+
+  - **Left (≈60%) — Value & Context**
+
+    1. **Field summary card** — `field_id`, box number, label/description, data type, mandatory badge, form/page IDs.
+    2. **Value editor** — component by type:
+
+       - Currency/Number: locale formatting (en‑GB/£, el‑GR/€), thousand separators, min/max, negative allowed?
+       - Date: datepicker with mask; timezone‑free.
+       - Boolean: switch with Yes/No labels.
+       - String: single line or textarea; max length.
+       - **Computed fields**: read‑only pill; **Override** toggle (requires reason) → audit.
+       - **N/A** toggle (where allowed by rule) → requires reason.
+       - **Save** (primary), **Revert** (to last saved), inline validation messages.
+
+    3. **Validation & QA messages** — live validators + QA blockers/warnings relevant to this field.
+    4. **History & Audit** — timeline: created/updated, source (manual, OCR, RPA), actor, old→new values.
+
+  - **Right (≈40%) — Explainability & Evidence**
+
+    1. **Lineage panel** — `Calculation` preview: formula, inputs (with current values & links), producing this field; recompute button.
+    2. **Governing rules** — list of `TaxRule` items with badges (Requirement/Eligibility/Exclusion); each has **Open guidance** (new tab) + **Copy citation**.
+    3. **Evidence** — linked `Document` chunks (title, page, snippet). Actions: _Attach existing_, _Find evidence_ (opens semantic search modal), _Preview_ (right‑side drawer with highlight), _Detach_.
+
+**Interactions & States**
+
+- Load: skeletons → data fetched; optimistic updates on save; toasts with correlation ID.
+- **Provide from Evidence**: select a snippet → auto‑parse value (LLM) → user confirms → value + lineage `(Document)-[:DERIVES]->(FormField)` persisted.
+- **Override computed**: require reason, show warning banner; audit entry created; can **Reset to computed**.
+- **Mark as N/A**: only if a governing rule allows exclusion; stores reason; removes from completeness.
+- **Keyboard**: all inputs tabbable; `Enter` to save; `Esc` to cancel edits.
+
+**API Contracts (used)**
+
+- `GET /catalog/fields/{field_id}` _(or)_ `GET /graph/field?field_id=&profile_id=` (metadata)\*
+- `POST /graph/provide` `{ profile_id, field_id, value, source, ts }`
+- `GET /graph/lineage?profile_id=&field_id=` → `{ calc, inputs[], rules[], guidance[] }`
+- `GET /search/guidance?q=&jurisdiction=&year=&field_id=`
+- `GET /files/{doc_id}` + signed download; evidence index via vector search
+
+> \*If `/graph/field` doesn’t exist yet, add a thin endpoint that returns field metadata joined with page/form labels for the header/breadcrumbs.
+
+**Acceptance Criteria (Field Detail)**
+
+- Mandatory field shows red badge; saving valid value removes it from completeness within 1s.
+- Computed field displays formula and input links; _Reset to computed_ restores derived value.
+- Evidence attach creates lineage link; preview opens at the correct page and highlights the chunk.
+- Audit timeline reflects user, timestamp, source; copy action logs a “reveal” only for identifiers.
+- i18n formatting for currency & date respects jurisdiction; screen reader labels present.
+
+#### 13.1.a Evidence Model & States
+
+**Graph/Data model**
+
+- `(:Document {doc_id, kind, year, source:'RPA'|'Upload'|'Webhook', s3_uri, checksum})`
+- `(:Transaction {txn_id, date, amount, currency, narrative, account_ref})`
+- `(:Document)-[:DERIVES {chunk_ref, extractor_id, confidence}]->(:FormField)` _(direct evidence)_
+- `(:Document)-[:DERIVES]->(:Transaction)` and `(:Transaction)-[:SUPPORTS]->(:FormField)` _(indirect evidence → roll‑up)_
+- `(:TaxpayerProfile)-[:PROVIDED {value, source:'manual'|'ocr'|'rpa'|'calc', confidence, ts, evidence_doc_id?, tx_ids?}]->(:FormField)` _(accepted value)_
+
+**Evidence states**
+
+- **Attached (Accepted)** – currently backing the saved value (has lineage edge and is referenced in `PROVIDED`).
+- **Suggested** – candidate evidence with parsed value; not yet accepted.
+- **Conflicting** – multiple candidates disagree; show diff.
+- **Stale** – evidence outside tax year or superseded by newer doc.
+- **Official** badge – source = `RPA` (HMRC/AADE portal) vs `Upload`.
+
+**UI in Field Detail (Right column → Evidence card)**
+
+- Tabs: **Attached** · **Suggested** · **Upstream** · **Portal**
+
+  - **Attached**: list of currently linked docs/transactions; badge (Official/Upload); quick actions: _Preview_, _Detach_, _Open in inbox_.
+  - **Suggested**: ranked by confidence; each row → _Attach & Fill_ (writes value + lineage) or _Ignore_.
+  - **Upstream**: when field is computed → shows inputs and their own attached evidence; when field is fed by transactions → shows aggregation group (e.g., “6 tx across 2 accounts → £412.50”).
+  - **Portal**: latest HMRC/AADE downloads relevant to this field/page with scrape step & screenshot link.
+
+**Actions**
+
+- _Attach & Fill_: sets the editor value; persists `PROVIDED` + `DERIVES` edges; marks others as candidates.
+- _Attach (no fill)_: link evidence without updating value (for audit only).
+- _Preview_: right drawer → PDF page at `chunk_ref` or transaction list → click to view transaction detail.
+- _Find evidence_: opens semantic search modal scoped to page/field.
+
+#### 13.1.b Drill‑downs
+
+From a field you can:
+
+1. **Open Document preview** → displays page with highlighted snippet; toolbar: zoom, copy citation, open original.
+2. **Open Transaction detail** → `/transactions/:txn_id` modal or page: date, amount, account, categorization, source doc links.
+3. **Open Portal session** → step timeline with screenshots; highlights the DOM region used for extraction.
+
+#### 13.1.c Auto‑provision from HMRC/AADE PDFs
+
+1. R**PA fetch → store PDF (source=**`RPA`).
+2. OCR/extract parses values → creates **Suggested** evidence with parsed values and confidence.
+3. If confidence ≥ threshold AND rule marks field **auto‑fillable**, system performs _Attach & Fill_ automatically; otherwise it surfaces as **Suggested** for user approval.
+4. Any auto‑fill is flagged with _Official_ badge and appears in History with extractor id.
+
+#### 13.1.d Conflicts & Versioning
+
+- If two **Suggested** values disagree (± tolerance), show **Conflicting** state with a diff (value, source, date).
+- Accepting one **Supersedes** others (kept for audit, marked inactive).
+- Newer portal downloads mark older **Attached** evidence **Stale** and propose an update.
+
+---
+
+### 13.2 Page Detail (SupplementaryPage)
+
+**Route:** `/profiles/:profileId/pages/:pageId`
+**Purpose:** Operate on a **coherent section** (e.g., SA105, E2) with progress and bulk actions.
+
+**Layout:**
+
+- Header: Page name/ID, form link, mandatory count, progress ring (completed/total), **Status** (Required/Optional/Excluded).
+- Tabs: **Fields** · **Calculated** · **Guidance** · **Evidence**
+- **Fields tab:**
+
+  - Table (or cards on mobile): Field label, box no., status, current value, last source, actions (Edit, Lineage, Attach evidence).
+  - Filters: Missing only · Mandatory only · Has evidence · Overridden.
+  - Bulk: _Provide defaults_ (pre‑approved safe defaults), _Import CSV_ (for repeating groups), _Clear overrides_.
+
+- **Calculated tab:** lists computed outputs and their inputs with quick links.
+- **Guidance tab:** embedded results from `/search/guidance` scoped to page; open in new tab.
+- **Evidence tab:** documents linked to this page; unmatched chunks suggestions.
+
+**Interactions**
+
+- Clicking a field opens **Form Field Detail** (same view as 13.1).
+- “Mark page as N/A” only if all governing rules allow exclusion → confirmation modal with reason.
+
+**AC (Page Detail)**
+
+- Progress updates live when fields are saved.
+- Filters persist in URL params; back/forward browser works.
+- Bulk actions show diff modal before committing.
+
+---
+
+### 13.3 Form Detail (TaxForm)
+
+**Route:** `/profiles/:profileId/forms/:formId`
+**Purpose:** Overview for the entire return form; entry point to pages.
+
+**Layout:**
+
+- Header: Form name/ID, jurisdiction/year badges, due dates, filing mode (paper/online), status chips.
+- Sections:
+
+  - **Required pages** (from completeness) with % complete.
+  - **Optional/suggested pages** (based on rules).
+  - **Summary**: totals & computed highlights; warnings (if any).
+  - **Actions**: Build draft payload · Run QA · View QA report.
+
+**Interactions & AC**
+
+- Build runs `/forms/build`; shows summary diff vs last build.
+- QA runs `/forms/qa`; blocking items deep‑link to the specific field detail.
+- Required pages accordions reflect completeness counts.
+
+---
+
+### 13.4 Completeness Panel (Deep‑link behaviors)
+
+- From **Completeness**, clicking an item navigates to **Field Detail** with `?from=completeness` (so back action returns to checklist and scrolls to the item).
+- If a field is **computed**, the CTA becomes **“Review calculation”** and anchors the Lineage panel.
+
+---
+
+### 13.5 Mobile Variants
+
+- Single column; sticky footer with **Save** / **Reset** / **Find evidence**.
+- Page Detail fields render as stacked cards with quick actions.
+
+---
+
+## 14) UI API Mapping (Detail Pages)
+
+| UI Element            | Endpoint                                                                     | Notes                                                           |
+| --------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Field header metadata | `GET /catalog/fields/{field_id}` or `GET /graph/field?field_id=&profile_id=` | Include form/page labels, data type, mandatory flag             |
+| Save value            | `POST /graph/provide`                                                        | Idempotency‑Key header; returns new edge & updated completeness |
+| Lineage load          | `GET /graph/lineage?profile_id=&field_id=`                                   | Returns calculation + inputs + rules + citations                |
+| Evidence search       | `GET /search/guidance` + vector index of evidence                            | Scope by `jurisdiction`, `tax_year`, `field_id`                 |
+| Evidence attach       | `POST /graph/link-evidence`                                                  | Create `(Document)-[:DERIVES]->(FormField)` (if not present)    |
+| Page completeness     | `GET /graph/completeness?profile_id=&page_id=`                               | Filtered to page context                                        |
+| Build/QA              | `/forms/build`, `/forms/qa`                                                  | For Form Detail actions                                         |
+
+> If `link-evidence` is not yet defined, expose a small endpoint that creates the lineage edge with `{doc_id, profile_id, field_id, chunk_ref?, note?}`.
+
+---
+
+## 15) Test Cases (Field/Page/Form Detail)
+
+**T‑FD‑01 Save valid value (mandatory)** → Completeness decrements; toast success; audit entry added.
+**T‑FD‑02 Computed field reset** → Override → Reset to computed restores derived value.
+**T‑FD‑03 Provide from Evidence** → Pick chunk → parsed value filled → lineage edge created.
+**T‑FD‑04 N/A toggle** → Only enabled if allowed; requires reason; completeness updated.
+**T‑FD‑05 Guidance open/copy** → Opens HMRC/AADE page; copy puts citation on clipboard.
+**T‑PD‑01 Filter “Missing only”** → Only missing rows displayed; URL param persists on reload.
+**T‑FoD‑01 Build & QA from Form Detail** → Runs, renders results, deep‑links into field detail for blockers.
+
+---
+
+## 16) Component Inventory (Field Detail)
+
+- `FieldSummaryCard`
+- `FieldValueEditor` (Currency/Number/Date/Boolean/String variants)
+- `ComputedBadge` + `OverrideToggle`
+- `ValidationList` (live + QA)
+- `HistoryTimeline`
+- `LineagePanel`
+- `RulesList` (+Citation chips)
+- `EvidenceList` (+Preview drawer)
+
+---
+
+## 17) Analytics (Field/Page/Form Detail)
+
+- `field_view` (profile_id, field_id, jurisdiction, year)
+- `field_save` (source, value_hash, duration_ms)
+- `field_override_toggle` (on/off, reason_len)
+- `evidence_attach` (doc_id, chunk_ref)
+- `page_filter_change` (filter_set)
+- `form_build`, `form_qa`
+
+---
+
+## 18) Accessibility Notes (Detail Pages)
+
+- Announce validation errors via `aria-live` polite.
+- Associate inputs with labels and help text; include box number in label for screen readers.
+- Keyboard shortcuts: `g` to open Guidance list, `l` to focus Lineage.
+
+---
+
+## 19) Open Questions / TODOs
+
+- Should **N/A** be reversible without audit approver? (policy)
+- Do we allow **bulk overrides** on a page? (dangerous — likely flag‑guarded)
+- Add `/graph/field` and `/graph/link-evidence` if not present.
+
+## 20) API Contracts — Evidence, Transactions, Field Metadata, Auto‑Provision Policies
+
+> All endpoints are under `/api/v1`. Auth via OIDC (Bearer). Firm scoping via `X‑Firm‑Id` (Accountant/Firm). Responses use **RFC7807 Problem+JSON** on errors.
+
+### 20.1 Attach Evidence to a Field
+
+**POST** `/graph/link-evidence`
+
+**Purpose**: Link a document chunk and/or transactions as evidence for a field. Optionally **fill** the field value (and create lineage).
+
+**Headers**
+
+- `Authorization: Bearer <token>`
+- `Idempotency-Key: <uuid>` _(required)_
+
+**Request (JSON)**
+
+```json
+{
+  "profile_id": "UK_PROFILE_001",
+  "field_id": "SA105_b5",
+  "doc_id": "HMRC-SA105-2024-PDF-001",
+  "chunk_ref": "p12#bbox(120,340,510,420)",
+  "txn_ids": ["txn_8a1", "txn_8a2"],
+  "parsed_value": 6420.75,
+  "source": "rpa",
+  "confidence": 0.93,
+  "attach_only": false,
+  "note": "Official HMRC PDF May 2025"
+}
+```
+
+**Behavior**
+
+- Creates `(Document)-[:DERIVES {chunk_ref, extractor_id?, confidence}]->(FormField)` if `doc_id` present.
+- Creates `(Transaction)-[:SUPPORTS]->(FormField)` for each `txn_id`.
+- If `attach_only=false` and `parsed_value` present → upserts `(TaxpayerProfile)-[:PROVIDED {...}]->(FormField)` and re‑runs completeness.
+- Marks prior evidence **Superseded** if overwriting an attached value.
+
+**Response 200 (JSON)**
+
+```json
+{
+  "status": "attached",
+  "field_id": "SA105_b5",
+  "provided": true,
+  "value": 6420.75,
+  "evidence": {
+    "doc_id": "HMRC-SA105-2024-PDF-001",
+    "chunk_ref": "p12#bbox(120,340,510,420)",
+    "txn_ids": ["txn_8a1", "txn_8a2"],
+    "confidence": 0.93,
+    "source": "rpa"
+  },
+  "completeness": { "missing_count": 3 }
+}
+```
+
+**Errors**
+
+- `400` invalid payload (missing `profile_id`/`field_id`)
+- `403` forbidden (role/firm scope)
+- `404` profile/field/doc/txn not found or not owned by profile
+- `409` conflict (stale year, superseded doc, or field locked)
+- `422` validation (type mismatch for `parsed_value`)
+
+---
+
+### 20.2 List Evidence (with filters)
+
+**GET** `/evidence`
+
+**Query params**
+
+- `profile_id` _(required)_
+- `field_id` | `page_id` _(optional scope)_
+- `source` = `upload|rpa|webhook` _(optional)_
+- `kind` = `document|transaction` _(optional)_
+- `linked` = `true|false` _(optional)_
+- `year` _(optional)_
+- `q` _(optional search over doc title/snippet)_
+- `limit` _(default 25)_, `cursor`
+
+**Response 200**
+
+```json
+{
+  "items": [
+    {
+      "type": "document",
+      "doc_id": "HMRC-SA105-2024-PDF-001",
+      "title": "SA105 Notes 2024",
+      "source": "rpa",
+      "year": "2024-25",
+      "linked_fields": ["SA105_b5"],
+      "chunk_ref": "p12#bbox(120,340,510,420)",
+      "parsed_value": 6420.75,
+      "confidence": 0.93,
+      "created_at": "2025-05-16T09:21:37Z"
+    },
+    {
+      "type": "transaction",
+      "txn_id": "txn_8a1",
+      "date": "2025-04-03",
+      "amount": 412.5,
+      "currency": "GBP",
+      "narrative": "Rent April",
+      "linked_fields": ["SA105_b5"],
+      "doc_ids": ["BANK-STATEMENT-APRIL"],
+      "created_at": "2025-04-04T12:10:00Z"
+    }
+  ],
+  "next_cursor": null
+}
+```
+
+---
+
+### 20.3 Transaction Detail
+
+**GET** `/transactions/{txn_id}`
+
+**Response 200**
+
+```json
+{
+  "txn_id": "txn_8a1",
+  "profile_id": "UK_PROFILE_001",
+  "date": "2025-04-03",
+  "amount": 412.5,
+  "currency": "GBP",
+  "account_ref": "uk_hsbc_main",
+  "narrative": "Rent April",
+  "doc_ids": ["BANK-STATEMENT-APRIL"],
+  "linked_fields": [{ "field_id": "SA105_b5", "relation": "SUPPORTS" }],
+  "year": "2024-25",
+  "created_at": "2025-04-04T12:10:00Z"
+}
+```
+
+**Errors**: `404` if not visible under caller’s scope.
+
+---
+
+### 20.4 Field Metadata (for detail header)
+
+**GET** `/graph/field?profile_id={pid}&field_id={fid}`
+
+**Response 200**
+
+```json
+{
+  "field": {
+    "field_id": "SA105_b5",
+    "form_id": "SA100",
+    "page_id": "SA105",
+    "box_number": "5",
+    "description": "Total rents and other income",
+    "data_type": "Currency",
+    "mandatory": true
+  },
+  "profile": {
+    "profile_id": "UK_PROFILE_001",
+    "jurisdiction": "UK",
+    "tax_year": "2024-25"
+  },
+  "status": "missing|provided|computed|overridden|na",
+  "current_value": 6420.75,
+  "source": "rpa|manual|ocr|calc",
+  "last_updated": "2025-05-16T09:22:01Z"
+}
+```
+
+---
+
+### 20.5 Auto‑Provision Policies
+
+**GET** `/policies/autoprovision`
+
+**Response 200**
+
+```json
+{
+  "defaults": {
+    "confidence_threshold": 0.85,
+    "numeric_tolerance": 0.01,
+    "allow_auto_fill": false
+  },
+  "overrides": {
+    "SA105_b5": { "allow_auto_fill": true, "confidence_threshold": 0.9 },
+    "E2_A1": { "allow_auto_fill": true }
+  },
+  "rules": {
+    "UK_PROP_NEEDS_SA105": { "auto_attach_only": true }
+  }
+}
+```
+
+**PUT** `/policies/autoprovision` _(Admin required)_
+
+**Request**
+
+```json
+{
+  "defaults": { "confidence_threshold": 0.88, "allow_auto_fill": true },
+  "overrides": { "SA105_b7": { "allow_auto_fill": false } },
+  "rules": { "GR_E2_NET_GOVERN": { "auto_attach_only": true } }
+}
+```
+
+**Response 200**
+
+```json
+{ "status": "updated", "version": "2025-08-19T10:00:00Z" }
+```
+
+**Notes**
+
+- Policies are versioned; changes are logged to audit.
+- Worker reads latest policy snapshot before extraction/auto‑provision.
+
+---
+
+### 20.6 Problem+JSON Error Shape
+
+```json
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Unprocessable Entity",
+  "status": 422,
+  "detail": "parsed_value must be a number for Currency fields",
+  "instance": "/graph/link-evidence",
+  "errors": { "parsed_value": "not a number" }
+}
+```
+
+---
+
+### 20.7 Security, Idempotency, Rate Limits
+
+- **RBAC**: roles `individual`, `accountant`, `admin`. Firm scope required for accountant via `X‑Firm‑Id`.
+- **Idempotency**: `POST /graph/link-evidence` and `POST /graph/provide` require `Idempotency-Key`.
+- **Rate limits**: `GET /evidence` and `GET /transactions/:id` 60 rpm/user; bursts allowed via token bucket.
+- **Audit**: Every attach/fill/override emits audit events with before/after diffs and evidence references.
+
+---
+
+## 21) cURL Examples
+
+**Attach & Fill from portal PDF**
+
+```bash
+curl -X POST "$API/graph/link-evidence" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Idempotency-Key: $(uuidgen)" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "profile_id":"UK_PROFILE_001",
+    "field_id":"SA105_b5",
+    "doc_id":"HMRC-SA105-2024-PDF-001",
+    "chunk_ref":"p12#bbox(120,340,510,420)",
+    "parsed_value":6420.75,
+    "source":"rpa",
+    "confidence":0.93,
+    "attach_only":false
+  }'
+```
+
+**List suggested evidence for a page**
+
+```bash
+curl "$API/evidence?profile_id=UK_PROFILE_001&page_id=SA105&linked=false&source=rpa&limit=50" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+**Transaction detail**
+
+```bash
+curl "$API/transactions/txn_8a1" -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## 22) Acceptance Criteria — APIs
+
+- `POST /graph/link-evidence` creates lineage edges and (optionally) provided value; idempotent retry returns same result.
+- `GET /evidence` filters work in combination; pagination stable via cursor; performance p95 < 300ms.
+- `GET /transactions/{id}` includes related docs and linked fields; 404 on cross‑tenant access.
+- Policy GET/PUT round‑trips; worker consumes updated policies within 60s.
+
+---
+
+## 23) QA Test Matrix — Evidence & Transactions
+
+- **E1** Attach‑only (no fill) → evidence listed as Attached; field value unchanged.
+- **E2** Attach & Fill (manual upload) → value saved; completeness decremented; lineage present.
+- **E3** Attach & Fill (RPA) with low confidence → remains Suggested; no auto‑fill.
+- **E4** Conflict: two values disagree → Conflicting state shown; accept one supersedes other.
+- **E5** Transaction roll‑up supports field → Upstream tab shows group; unlink removes support edge.
+- **E6** Policy change → enabling auto‑fill for SA105_b5 leads to automatic fill on next extraction.
+
+— End —