docs(api): add typedoc reference generation

apps/bot/packages/auth/src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * Authentication and request-boundary helpers shared by bot microservices.
+ *
+ * Exports HMAC service-to-service signatures, signed Telegram user identity,
+ * OAuth state signing, request body readers, audit helpers, and traceparent
+ * utilities.
+ *
+ * @packageDocumentation
+ */
+
 export { audit } from './audit.js'
 export { readBody, readJsonBody } from './body.js'
 export { MAX_BODY_BYTES, MAX_DRIFT_MS } from './constants.js'

apps/bot/packages/contracts/src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * Shared runtime contract types for bot-facing services.
+ *
+ * The package groups booking, payment, calendar, analytics, reporting, and
+ * stream payload contracts so service implementations and tests can agree on
+ * the same TypeScript shapes.
+ *
+ * @packageDocumentation
+ */
+
 export * from './analytics.js'
 export * from './booking.js'
 export * from './calendar.js'

docs/code-documentation.md

@@ -0,0 +1,18 @@
+# Code documentation
+
+Metrix uses TypeDoc to generate markdown API reference pages from TypeScript
+exports and JSDoc comments.
+
+## Commands
+
+- `npm run docs:typedoc` regenerates `docs/api-reference`.
+
+## Scope
+
+The current TypeDoc config documents the root API facade plus shared bot
+packages for auth, contracts, observability, and tracing. Add new entry points
+to `typedoc.json` when a package becomes part of the public service contract.
+
+Prefer JSDoc on exported modules, classes, functions, and domain types. Internal
+helpers should be marked with `@internal` when they are not intended for the
+generated reference.

docs/typedoc-readme.md

@@ -0,0 +1,6 @@
+# Metrix API Reference
+
+This reference is generated from TypeScript exports and JSDoc comments.
+
+Run `npm run docs:typedoc` from the repository root to refresh the markdown
+files in `docs/api-reference`.