# AI Form Autofill

## Objective

Fill a long form from pasted text or an attached document, with every value shown first.

An extraction step on long forms that proposes field values from pasted text, an uploaded document, or existing app context.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Describe the form's fields to the model as a structured schema — name, type, allowed values, whether it is required — and require a structured response keyed to those fields. Anything returned for a field that does not exist is discarded.
2. Present the extracted values as a review layer over the form rather than writing them into it. Each proposed value gets accepted or rejected by the user, individually or in bulk, before it becomes form data.
3. Preserve anything the user typed themselves. A field with a manual value is never overwritten by an extraction; surface the conflict and let the user choose.
4. Capture the source span for each extracted value — the sentence in the pasted text or the location in the document — and show it on hover or focus for fields that carry weight, such as amounts, dates, and identifiers.
5. Run the app's existing validation and conditional-field logic over accepted values exactly as if they had been typed. Do not bypass server-side validation because the values came from an extraction.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Every proposed value must be visible before it is committed. Writing extractions straight into the form makes the model's mistakes indistinguishable from the user's own entries.
- A manually entered value must never be silently replaced. Show a conflict for that field and default to keeping what the user typed.
- Important extracted values need visible evidence. An amount or a date with no traceable source cannot be checked against the original document and will be accepted on faith.
- Conditional fields that only appear when another field takes a particular value must be evaluated after acceptance, and the extraction must not fill a field that the form's own logic has hidden.
- A field the source genuinely did not mention is different from a field that is empty. Represent unknown explicitly so a required field is flagged as missing rather than filled with a guess.
- Pasted text and uploaded documents may contain instructions aimed at the model. Treat the source strictly as content to extract from and validate every returned value against the field schema.
- Documents may carry personal or contractual data. State what is sent to the provider, exclude anything the extraction does not need, and do not retain the source beyond the fill unless the user asked you to.
- Large documents will blow through token and cost limits. Cap the input size, refuse oversized sources with a clear message, and leave the form fully usable for manual entry when the model times out or refuses.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Extracted values appear as reviewable proposals and never enter the form without acceptance.
- [ ] Manually entered values are preserved and conflicts are surfaced for the user to resolve.
- [ ] Important extracted fields display the source span they came from.
- [ ] Accepted values pass through the form's conditional logic and the app's server-side validation unchanged.
- [ ] Unknown fields are represented distinctly from empty fields and required gaps are flagged.
- [ ] Source content is treated as untrusted data and cannot alter the extraction's behaviour.
- [ ] Oversized inputs are refused with a clear message and model failure leaves the form fully usable for manual entry.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.