docs: document the direct messaging contract

[aquie00t]

Summary

Adds docs/direct-messaging.md, the client-facing contract for the direct messaging feature merged in #257, and removes docs/media-moderation-client.md.

The new document covers the conversation lifecycle, every endpoint with its request and response shapes, the conversation and message objects, cursor semantics, the two-step media upload, realtime events, error titles and rate limits. It is written as reference material — no team-directed instructions, no narration of backend internals — because this repository is public and this is the page a client integrator lands on.

Why this document exists

Pointing an integrator at the pull request does not work well. #257 is 89 files and roughly 6,700 lines, and most of it — entities, repositories, migrations, DI wiring, the moderation worker — is not part of the client contract. The contract itself lives in four schema and route files, and several rules that break a client are not visible from an endpoint signature at all:

• POST /conversations answers 200, not 201, when the conversation already existed. Anything keyed on 201 alone misreads a no-op as a fresh thread.
• GET /conversations/unread-count excludes pending requests, so it cannot back a request-tab badge.
• conversation:request and message:new are separate events; the first must not raise the unread badge.
• In a pending conversation only the initiator may post; the recipient gets 403 until they accept.
• Message media must come from POST /messages/media. A URL from the post upload endpoint is refused with 400 MediaNotOwnedError, because the moderation channel is fixed at upload time.
• A non-participant receives 404, not 403.
• mediaPending, mediaRejected, isDeleted and isSensitive are four independent render states.

Each of these is stated explicitly, with the reasoning where the reasoning is what makes the rule stick.

Why the old document is removed

docs/media-moderation-client.md was written in Turkish as a hand-off note to one frontend team. It narrated backend internals, told the reader not to guess and not to write code before approval, and closed with a section on working method. That is a message, not documentation, and it sat in a public repository alongside an otherwise English codebase.

The part of it that message media genuinely depends on — the upload error contract, the magic-byte format detection, the tiered verdicts — is carried over into the new document's media section.

This does leave the post, article-cover, avatar and banner upload endpoints without a written client contract. If that is wanted, it belongs in its own reference page rather than in a note; happy to write one.

Verification

Documentation only — no source changes beyond a one-line pointer added to the direct messaging section of CLAUDE.md.

Every statement was checked against the merged implementation: status codes and error titles against the error classes and route schemas, field names against the mappers, limits and defaults against the TypeBox schemas, accepted media formats against detect-media-type.ts, and the realtime event names and socket envelope against chat-events.constants.ts and fastify-realtime.service.ts. No references to the removed file remain anywhere in the repository.

---

AI asistan: Opus 5