# AI Source Citations

## Objective

Attach every factual claim in an AI answer to the record or passage that supports it.

Inline citations on AI-generated answers, each resolving to a specific record, document, or passage inside the app.

## 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. Find the places where the app already generates answers from its own data, and capture which records were retrieved for each generation. Citations are built from the retrieval step, not reconstructed afterwards by asking the model where it got something.
2. Cite the smallest useful unit. A paragraph or a single field beats a whole document, and a whole document beats a collection, because a citation the user has to search through is barely a citation.
3. Re-check permissions at the moment a citation is opened, using the app's existing authorization rules. The set of records the generation ran over may include things the reader is not entitled to see, and the citation must fail closed rather than reveal a title or excerpt.
4. Mark statements that combine several sources as inferences, listing every source involved, and distinguish them visually from statements lifted from one place. Confidence banding and review routing belong to AI Confidence and Uncertainty; this feature owns only provenance.
5. Do not attach a citation to a statement merely because the record was in the retrieval set. An unsupported claim with a plausible-looking citation is worse than an uncited one, because the citation stops the reader checking.

## 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

- A citation must point at the smallest span that actually supports the claim. Citing an entire long document forces the reader to re-do the work and turns provenance into decoration.
- Permissions must be checked when the citation is opened, not only when the answer was produced. A user whose access was revoked, or a colleague the answer was shared with, must be refused without leaking the source's title or a preview.
- Retrieved but unused records must not be cited. The retrieval step returns candidates, and treating all of them as support attaches authority to material the answer never relied on.
- A statement synthesised across several sources must say so and name all of them, rather than picking one source and presenting the inference as a direct quotation.
- When a cited record is deleted, moved, or has its access changed, the citation must resolve to a clear unavailable state that says the source no longer exists or is no longer visible. A dead link or a silent redirect to the wrong record destroys trust in every other citation on the page.
- An answer where the model produced no supportable claims must say it could not find support, rather than shipping an uncited wall of text that looks identical to a cited one.
- Citations must survive the answer being exported, printed, or copied, at minimum as a readable reference, because an answer separated from its provenance will be quoted as fact.
- If the generation is truncated or the model returns malformed structured output, discard the partial citation mapping rather than attaching offsets that now point at the wrong text.

## 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

- [ ] Every factual statement in a generated answer either carries a citation or is visibly marked as unsupported.
- [ ] Citations resolve to a specific record or passage, not to a search result or a collection.
- [ ] Opening a citation re-checks the reader's permissions and refuses without leaking source content.
- [ ] Statements inferred across multiple sources are labelled as such and list every source involved.
- [ ] Deleted or newly restricted sources render as an explicit unavailable citation rather than a broken link.
- [ ] Records retrieved but not used to support the answer are never cited.
- [ ] 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.