docs(api): document the response envelope (JSDoc + Swagger @ApiOkResponse examples)

[dorisadams]

Summary

Follow-up to #488 and #489. Adds developer-facing documentation so consumers learn the { apiversion, result, data } envelope shape from the source and from the OpenAPI spec at /api instead of discovering it at runtime.

What this PR adds

1. JSDoc on the interceptor (src/common/interceptors/data-response.interceptor.ts)

• Class-level docblock explaining the global contract and the issue Fix DataResponseInterceptor for Non-Array Responses in meridian-api folder #426 history.
• @returns + four @example blocks on transform() covering array, single-object, primitive, and null payloads.
• @throws {never} on both intercept() and transform() to make the no-throw contract machine-discoverable.

2. Swagger @ApiOkResponse examples (src/common/decorators/api-envelope-response.decorator.ts + src/common/dto/envelope.dto.ts)

• New EnvelopeDto Swagger model with @ApiProperty decorators matching the runtime DataResponseEnvelope<T> interface (data is described via oneOf over object / array / string / number / integer / boolean / null).
• New @ApiEnvelopeResponse({ dataExample, status, description }) decorator that drops in for @ApiOkResponse on every controller method that returns success. It:
  • Always emits @ApiExtraModels(EnvelopeDto) so the $ref resolves on first use.
  • References the envelope via getSchemaPath(EnvelopeDto) (idiomatic NestJS, honors custom OpenAPI prefixes).
  • Augments the schema with an example payload whose result is derived from dataExample using the same rule the interceptor applies at runtime — so docs and code cannot drift.

3. Application per controller (users, post, tweets, auth)

• Every success @ApiResponse decorator was replaced with @ApiEnvelopeResponse(...) carrying a representative dataExample for that route.
• Error @ApiResponse decorators (4xx) are kept as-is.
• Pre-existing unused imports in these controllers were cleaned up to keep the diff ESLint-clean.

4. Site-wide mention in Swagger description (src/main.ts)

• DocumentBuilder().setDescription() now opens with a "## Response envelope" Markdown section explaining apiversion, result, and data so consumers see the contract at the top of /api even before drilling into a tag.

5. Test-suite plumbing (jest.setup.ts)

• Adds a virtual jest.mock for the new envelope decorator module (alias path only — the relative-path variant that no spec ever uses was dropped per code-review feedback) so existing specs can keep loading controller modules without pulling in the real Swagger metadata machinery.

Out of scope

• src/tag/tag.controller.ts has no Swagger decorators — added as a follow-up.
• src/app.controller.ts is the trivial / hello-world route.
• src/health/health.controller.ts returns a Terminus HealthCheckResult shape that is not wrapped in the envelope, so documenting it as envelope-wrapped would be a contract lie.

Verification

• tsc -p tsconfig.build.json --noEmit -> clean.
• eslint on every touched file -> clean.
• jest src/auth/auth.controller.spec.ts -> 6/6 pass (the spec exercises the new envelope decorator import chain via the controller).

Follow-up chain

• fix(api): harden DataResponseInterceptor for non-array responses (closes #426) #488 — fix interceptor ({apiversion, result, data} envelope).
• test(api): fix 3 pre-existing failing test suites #489 — bring the 3 pre-existing failing test suites up to date with that envelope.
• This PR — publish the envelope contract as documentation.

Fixes the user request from the dorisadams follow-up flow.