# Discussion Forum

## Objective

Give users a public place to ask questions and answer each other.

Topic boards containing user-created threads with replies, moderation controls, and permalinks.

## 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. Ship boards, threads, replies, and a single level of nesting. Resist arbitrary-depth reply trees, reputation scores, badges, and private subforums until people are actually posting; each of those is a feature in its own right.
2. Reuse Comments and Mentions for the reply composer, mention parsing, and content rendering rather than writing a second editor with its own escaping rules.
3. Route reported and held posts into the existing Moderation Queue and reuse AI Text Content Moderation and Content Reporting if present. Do not build a forum-specific moderation inbox alongside the one the app already has.
4. Give every thread and every post a stable permalink that survives being pinned, locked, moved between boards, or merged into another thread.
5. Do not send an email for every reply. Route notifications through the existing Notification Digests so a busy thread produces one summary rather than forty separate messages.

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

- Deep reply chains become unreadable when each level indents further. Cap the visible nesting depth and show deeper replies as flat with a quoted parent reference instead of running off the right edge on a phone.
- Moderator actions must not break links. Pinning, locking, moving, and merging threads all need to leave old permalinks resolving, redirecting where necessary rather than returning a not-found.
- A user posting five threads a minute is either a bot or a problem. Throttle rapid repeat posting per account and per address, and detect near-identical bodies posted repeatedly.
- Deleting a parent post must not take its replies with it. Replace the body with a tombstone so the conversation still reads, and keep the child replies attached.
- Notifying every participant on every reply drives people to mute the forum entirely. Batch notifications, respect per-thread mute, and let a user unsubscribe from a thread they started.
- Public user-generated content is a spam and abuse target from day one. Require an account with a confirmed email to post, hold first posts from new accounts for review, and strip links from unverified authors.
- Threads grow past what one page can show. Paginate deterministically so a permalink to reply four hundred lands on the right page even after earlier replies are deleted.
- Forum content will be indexed by search engines. Decide whether that is wanted, and make sure locked, hidden, and moderated posts are excluded from both the sitemap and the app's own Global Search.

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

- [ ] Users can create threads on a board and reply to each other, with replies rendered readably on a phone.
- [ ] Visible nesting is capped and deeper replies remain legible without horizontal scrolling.
- [ ] Pinning, locking, moving, and merging a thread leave every existing permalink resolving.
- [ ] Deleting a post preserves its replies and leaves a tombstone in place.
- [ ] Rapid repeat posting is throttled and near-duplicate posts are detected.
- [ ] Participants receive batched notifications and can mute a thread.
- [ ] Moderated and hidden posts are excluded from search and from public indexing.
- [ ] 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.