# AI Image Captioning

## Objective

Describe images so they can carry a visible caption and be found by search.

A generated description stored per image, offered as a draft caption and indexed for search.

## 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. Store the generated description in its own field and decide explicitly whether each surface shows it, indexes it, or both. Do not write it into the alt attribute, which belongs to AI Image Alt Text and answers a different question.
2. Offer the description as a draft caption the user can accept or rewrite, and leave any caption a human already wrote untouched unless they explicitly ask for a replacement.
3. Index the description alongside the image's existing metadata so images become findable by what is in them, and reuse the app's existing search infrastructure rather than adding a parallel one.
4. Have the model report what it could not determine, and render uncertainty plainly in the draft. A description that hedges is useful; one that confidently names the wrong object poisons search results.
5. Run generation through the app's existing background-job system with a per-image and per-account cost ceiling, and make it resumable so a large library can be processed across multiple runs.

## 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 caption and an alt attribute are different artifacts. A caption adds context a sighted viewer cannot infer; alt text substitutes for the image entirely. Storing one in the other's field degrades both.
- Real people must not be named or identified from an image alone. Allow a description of what a person is doing without asserting who they are, and do not infer relationships or affiliations.
- Uncertain objects and unreadable text must be flagged as uncertain rather than resolved into a confident guess, and the draft must show that flag to the reviewer.
- A user-written caption is authoritative. Regeneration must not replace it, and a bulk pass must skip images that already have human text.
- Unsupported formats, images too small to describe, corrupt files, and images the account has marked private must be skipped cleanly with a recorded reason, not retried forever.
- Decide before shipping whether images may be sent to the provider at all for a given account, and honour a workspace setting that forbids it rather than exempting the feature.
- A refused, timed-out, or truncated response must leave the image with no description and a retryable status, and the surrounding page must render normally without one.
- Regenerating descriptions across a library must not multiply cost invisibly; show the estimated volume and require confirmation before a bulk run starts.

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

- [ ] Generated descriptions are stored in a dedicated field, separate from alt text.
- [ ] Drafts are offered for approval and existing human captions are never overwritten.
- [ ] Descriptions are indexed and images become findable by their content through the app's existing search.
- [ ] Uncertain objects and unreadable text are marked as uncertain rather than guessed.
- [ ] Real people are not identified by name from an image alone.
- [ ] Unsupported, corrupt, or excluded images are skipped with a recorded reason and no retry loop.
- [ ] Bulk generation runs in the background under a stated cost ceiling and is resumable.
- [ ] 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.