# Internal Notes

## Objective

Give staff a place to write things the customer must never see.

Notes attached to a record that are readable only by internal roles, and that never appear in any export, feed, or API response.

## 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. Model an internal note as a distinct visibility state on the server, not a flag the client filters on. Every read path — record view, search, digest emails, exports, webhooks, API serializers — must exclude internal notes for anyone without the internal role.
2. Give internal notes a visual treatment that cannot be confused with a public comment: different surface, a persistent label, and a warning that survives collapse or truncation. If a user has to remember which box is which, this feature has failed.
3. Decide explicitly what an impersonating admin or a support session sees, and state the rule in the UI. Support staff reading internal notes is usually fine; a support session rendering them inside a screen the customer is watching is not.
4. Audit every create, edit, and delete of an internal note with actor and timestamp, and keep the audit record when the note itself is deleted.
5. Do not build a second commenting system. Threading, @-mentions, notification delivery and body sanitization are owned by Comments and Mentions; extend that rather than duplicating it.

## 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 record export, print view, or PDF must omit internal notes even when the exporter is internal — decide the rule once and apply it to every format.
- Search must not match on internal note text for external users. A zero-result search that becomes a hit is a leak.
- Changing a user's role must immediately change what they can read, including anything already cached or open in another tab.
- An @-mention of an external collaborator inside an internal note must not deliver a notification containing the note body.
- Deleting the parent record must not orphan internal notes into a state where they are still readable but no longer permission-checked.
- Copying or duplicating a record must not carry internal notes across unless the actor is internal and explicitly asks.

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

- [ ] Internal notes are filtered on the server; no client-side check is the only guard.
- [ ] No export, API response, webhook, or email contains an internal note for an external recipient.
- [ ] Internal notes are visually distinct from public comments at a glance, including on mobile.
- [ ] Impersonation and support-access behaviour is defined and documented in the UI.
- [ ] Every edit and delete is audited with actor and timestamp, and the audit survives deletion.
- [ ] Threading and mentions reuse the existing comment system rather than a parallel one.
- [ ] 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.