feat: add agent API and operational analytics

scripts/generate-api-docs.ts

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { API_OPERATIONS } from '../src/web/api-catalog.js';
+
+const rows = API_OPERATIONS.map((operation) =>
+  `| \`${operation.method}\` | \`${operation.path}\` | ${operation.summary} | ${operation.access} | ${operation.mutates ? 'yes' : 'no'} |`,
+).join('\n');
+
+const document = `# RedditBot API
+
+This file is generated from \`src/web/api-catalog.ts\`. Run \`npm run docs:api\`
+after changing the HTTP surface. The live OpenAPI 3.1 document is available at
+\`GET /api/openapi.json\`, and compact agent discovery is available at
+\`GET /api/v1/capabilities\`.
+
+## Authentication
+
+The dashboard token is an administrator credential. Browser users can exchange
+it for an HttpOnly, SameSite=Strict session; API clients can send it as a bearer
+token.
+
+Optional least-privilege bearer credentials are configured with:
+
+- \`REDDIT_BOT_AGENT_READ_TOKEN\`: GET, HEAD, SSE, and private-media reads except debug routes.
+- \`REDDIT_BOT_AGENT_CONTROL_TOKEN\`: read access plus mutations under \`/api/v1\`.
+
+Control credentials cannot send messages, import sessions, activate accounts,
+or update legacy configuration endpoints. Those operations require the
+administrator dashboard token.
+
+## Agent entry points
+
+- \`GET /healthz\`: unauthenticated process liveness with no private state.
+- \`GET /api/v1/readyz\`: component readiness and authentication degradation.
+- \`GET /api/v1/overview\`: bot, account, sync, rate-limit, and recent-error snapshot.
+- \`GET /api/v1/control\`: current running state.
+- \`POST /api/v1/control/start\`, \`/stop\`, or \`POST /api/v1/control\`: explicit bot control.
+- \`POST /api/v1/jobs\`: tracked chat/media sync; poll \`GET /api/v1/jobs/:id\`.
+- \`GET /api/events/stream\`: replayable typed SSE events.
+
+## MCP server
+
+Run the stdio MCP adapter with \`npm run mcp\`. It connects to
+\`REDDIT_BOT_API_URL\` (default \`http://127.0.0.1:3000\`) and reads its bearer
+credential from \`REDDIT_BOT_AGENT_TOKEN\`, then the scoped agent variables, and
+finally \`WEB_DASHBOARD_TOKEN\`.
+
+Read tools cover overview, readiness, accounts, activity, conversations,
+errors, sync state, and performance. Control tools include \`start_bot\`,
+\`stop_bot\`, \`set_bot_running\`, \`trigger_sync\`, and \`get_job\`. External
+message tools are separately annotated as destructive/non-idempotent and need
+an administrator credential.
+
+## Operations
+
+| Method | Path | Summary | Access | Mutates |
+|---|---|---|---|---|
+${rows}
+
+## Error model
+
+Errors use JSON with an \`error\` string and optional \`detail\`. Authentication
+failures are \`401\`; recognized but insufficient agent credentials receive
+\`403\`; invalid inputs receive \`400\`; unavailable services receive \`503\`.
+Long-running agent jobs expose failure text in the job resource.
+`;
+
+const target = path.resolve(process.cwd(), 'docs/api.md');
+if (process.argv.includes('--check')) {
+  if (!fs.existsSync(target) || fs.readFileSync(target, 'utf8') !== document) {
+    process.stderr.write('docs/api.md is stale; run npm run docs:api\n');
+    process.exitCode = 1;
+  }
+} else {
+  fs.writeFileSync(target, document);
+}