feat(api): live OpenAPI docs at /api-docs (Scalar) and /api/openapi.json

Enables Nitro's experimental OpenAPI generation and serves the spec + Scalar UI from the app itself, in both dev and production. Subscribed users can now browse the REST API without leaving the site; admin endpoints are included with tags + security metadata so they render distinctly.

Adds a defineRouteMeta example to the new admin ourmoji daily endpoint as a template — future endpoints can opt in to richer request/response schema documentation by following the same pattern.

The ourmoji agent walkthrough now links to the live docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: InfantLab

app/nuxt.config.ts

@@ -157,9 +157,30 @@ export default defineNuxtConfig({
 
   // Nitro server configuration
   nitro: {
-    // Enable SQLite in production
+    // Enable SQLite in production + OpenAPI/Scalar docs
     experimental: {
       database: true,
+      openAPI: true,
+    },
+
+    // Public API documentation — served from the app itself so subscribed
+    // users can browse endpoints without leaving the site. Admin endpoints
+    // are listed but tagged so they're visually separated.
+    openAPI: {
+      route: "/api/openapi.json",
+      production: "runtime",
+      meta: {
+        title: "Ta-Da! API",
+        description:
+          "REST API for Ta-Da! — authenticate with a Bearer API key (tada_key_…). Admin endpoints require the caller's user id to be in ADMIN_USER_IDS on the server.",
+        version: pkg.version,
+      },
+      ui: {
+        scalar: {
+          route: "/api-docs",
+        },
+        swagger: false,
+      },
     },
     // Externalize native bindings - they can't be bundled, must use node_modules at runtime
     externals: {

app/server/api/v1/admin/ourmoji/daily.post.ts

@@ -14,6 +14,62 @@
 
 import { defineEventHandler, readBody, createError } from "h3";
 
+defineRouteMeta({
+  openAPI: {
+    tags: ["Ourmoji", "Admin"],
+    summary: "Ingest a daily Ourmoji on behalf of a user (admin)",
+    description:
+      "Posts a single day's Ourmoji payload for a target user. Intended " +
+      "for trusted server-to-server agents authenticated with an admin " +
+      "API key. Idempotent per (userId, date).",
+    security: [{ bearerAuth: ["admin:users:write"] }],
+    requestBody: {
+      required: true,
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            required: [
+              "userId",
+              "date",
+              "emoji",
+              "reflection",
+              "moonPhase",
+              "timezone",
+            ],
+            properties: {
+              userId: { type: "string" },
+              date: { type: "string", format: "date" },
+              emoji: { type: "string", minLength: 1, maxLength: 16 },
+              reflection: { type: "string", minLength: 1, maxLength: 5000 },
+              moonPhase: { type: "string" },
+              moonIllumination: {
+                type: "number",
+                minimum: 0,
+                maximum: 100,
+                nullable: true,
+              },
+              wheelOfYear: { type: "string", nullable: true },
+              wheelCategory: { type: "string", nullable: true },
+              timezone: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      "200": { description: "Ourmoji entry upserted" },
+      "400": {
+        description:
+          "Validation error or target user does not have ourmoji enabled",
+      },
+      "401": { description: "Missing or invalid Bearer token" },
+      "403": { description: "Caller is not an admin" },
+      "404": { description: "Target user not found" },
+    },
+  },
+});
+
 import { requireAdmin } from "~/server/utils/admin";
 import {
   notFound,

docs/modules/ourmoji-agent-setup.md

@@ -208,4 +208,14 @@ co-ordination across users.
 
 ---
 
+## Reference: live API docs
+
+Interactive docs for this endpoint (and the rest of the API) are served from
+the app itself — no local setup needed:
+
+- **Scalar UI:** https://tada.living/api-docs
+- **OpenAPI JSON:** https://tada.living/api/openapi.json
+
+---
+
 [Back to Ourmoji](./ourmoji.md)