case-framework · kschneider84 · Mar 10, 2026 · Mar 10, 2026 · May 27, 2026 · May 27, 2026
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
@@ -0,0 +1,5 @@
+reviews:
+  path_filters:
+    - "!case-docs/content/tech-docs/management-api/api/**"
+    - "!case-docs/content/tech-docs/participant-api/api/**"
+    - "!case-docs/content/tech-docs/smtp-bridge/api/**"
diff --git a/README.md b/README.md
@@ -36,17 +36,71 @@ Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
 
 ## For API Documentation
 
-Include the openapi spec file in the `public/openapi` directory.
+OpenAPI docs are generated from profiles defined in `scripts/doc-profiles.ts`.
 
-Add a new page with the name `api.mdx` in the `content/tech-docs/[api-name]` directory with the following content:
+### 1. Add the OpenAPI spec
 
-```mdx
----
-title: My API
-description: My API Description
----
+Place your spec file in the `openapi` directory, for example:
+
+- `openapi/my-api.yaml`
+
+### 2. Add or update a docs profile
+
+In `scripts/doc-profiles.ts`, add a new profile entry:
+
+```ts
+{
+  id: 'my-api',
+  input: './openapi/my-api.yaml',
+  outputDir: 'content/tech-docs/my-api/api',
+  baseUrl: '/tech-docs/my-api/api',
+  groupByTag: true,
+}
 ```
 
+`groupByTag: true` groups endpoints by OpenAPI tags in the generated docs.
+
+Current profiles:
+
+- `management-api` (`openapi/management-api.yaml`, `groupByTag: true`)
+- `participant-api` (`openapi/participant-api.yaml`, `groupByTag: true`)
+- `smtp-bridge` (`openapi/smtp-bridge.yaml`, `groupByTag: false`)
+
+### 3. Add the Tech Docs section (only for a new API)
+
+Create `content/tech-docs/my-api` with:
+
+- `overview.mdx` (landing page)
+- `meta.json` with `"pages": ["overview", "api"]`
+
+Then add `my-api` to `content/tech-docs/meta.json` so the section appears in the sidebar.
+
+### 4. Generate the API docs
+
+List available profiles:
+
+```bash
+pnpm exec tsx --no-cache scripts/generate-docs.ts --list
+```
+
+Generate one profile:
+
+```bash
+pnpm exec tsx --no-cache scripts/generate-docs.ts my-api
+```
+
+Generate all profiles:
+
+```bash
+pnpm exec tsx --no-cache scripts/generate-docs.ts --all
+```
+
+### 5. Result
+
+Generated API pages are written to `content/tech-docs/<api-id>/api` (including `index.mdx` and `meta.json`).
+
+Note: these files are generated and should not be edited manually. Re-run the generator after spec changes.
+
 ## Learn More
 
 To learn more about Next.js and Fumadocs, take a look at the following

diff --git a/app/(home)/page.tsx b/app/(home)/page.tsx
@@ -19,7 +19,7 @@ export default function HomePage() {
           <h2 className="text-2xl font-semibold mb-6">User Guides</h2>
           <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
             <Card
-              href="/docs/survey-editor/basics/editor-overview"
+              href="/docs/survey-editor/editor-overview"
               title="Survey Editor"
               description="Documentation for using the graphical survey editor"
               icon={<PencilRuler className="w-6 h-6" />}
@@ -33,7 +33,7 @@ export default function HomePage() {
               className="[&_div:has(svg)]:shadow"
             />
             <Card
-              href="/docs/study-rules-editor/basics/editor-overview"
+              href="/docs/study-rules-editor/editor-overview"
               title="Study Rules Editor"
               description="Documentation for using the study rules editor"
               icon={<GitFork className="w-6 h-6" />}

diff --git a/app/docs/[[...slug]]/page.tsx b/app/docs/[[...slug]]/page.tsx
@@ -9,7 +9,6 @@ import { notFound } from 'next/navigation';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
 import { getMDXComponents } from '@/mdx-components';
 
-
 export default async function Page(props: {
   params: Promise<{ slug?: string[] }>;
 }) {

diff --git a/app/global.css b/app/global.css
@@ -1,8 +1,17 @@
 @import 'tailwindcss';
-@import 'fumadocs-ui/css/black.css';
+@import 'fumadocs-ui/css/solar.css';
 @import 'fumadocs-ui/css/preset.css';
+@import 'fumadocs-openapi/css/preset.css';
 
-/* Hide the scheme container for Swagger UI */
-.swagger-ui .scheme-container {
-    display: none;
+html {
+    scrollbar-gutter: stable;
+}
+
+html>body[data-scroll-locked] {
+    margin-right: 0px !important;
+    --removed-body-scroll-bar-size: 0px !important;
+}
+
+:root {
+    --fd-layout-width: 1600px;
 }
diff --git a/app/tech-docs/[[...slug]]/page.tsx b/app/tech-docs/[[...slug]]/page.tsx
@@ -8,7 +8,6 @@ import {
 import { notFound } from 'next/navigation';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
 import { getMDXComponents } from '@/mdx-components';
-import ApiDoc from '@/components/api-doc';
 
 
 const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';
@@ -20,13 +19,6 @@ export default async function Page(props: {
   const page = source.getPage(params.slug);
   if (!page) notFound();
 
-  // Use the ApiDoc component for API pages (wrapper for Swagger UI)
-  if (params.slug?.includes('api')) {
-    return (
-      <ApiDoc specUrl={`${basePath}/openapi/${params.slug[0]}.json`} />
-    )
-  }
-
   const MDXContent = page.data.body;
 
   return (

diff --git a/components/api-doc.tsx b/components/api-doc.tsx
diff --git a/components/api-page.client.tsx b/components/api-page.client.tsx
@@ -0,0 +1,6 @@
+'use client';
+import { defineClientConfig } from 'fumadocs-openapi/ui/client';
+
+export default defineClientConfig({
+    // client-side config
+});
diff --git a/components/api-page.tsx b/components/api-page.tsx
@@ -0,0 +1,7 @@
+import { openapi } from '@/lib/openapi';
+import { createAPIPage } from 'fumadocs-openapi/ui';
+import client from './api-page.client';
+
+export const APIPage = createAPIPage(openapi, {
+    client,
+});
diff --git a/content/docs/study-rules-editor/basics/meta.json b/content/docs/study-rules-editor/basics/meta.json
diff --git a/...y-rules-editor/basics/editor-overview.mdx → ...cs/study-rules-editor/editor-overview.mdx b/...y-rules-editor/basics/editor-overview.mdx → ...cs/study-rules-editor/editor-overview.mdx
@@ -1,6 +1,6 @@
 ---
-title: Study Rules Editor
-description: Overview of the study rules editor interface
+title: Editor Overview
+description: Main areas, navigation, and workflow for configuring study rules
 ---
 
 ## Introduction
@@ -15,14 +15,14 @@ description: Overview of the study rules editor interface
 
 The **Study Rules Editor** is a graphical interface that allows you to create and manage these rules. It provides tools to define event handlers, configure contexts, and automate study workflows and participant management.
 
-![Overview of study rules dashboard](../images/dashboardOverview.png)
+![Overview of study rules dashboard](./images/dashboardOverview.png)
 
 
 ### Top Navigation Bar
 
 - **"Project"**: Click here to open an existing project, save your project or export the study rules.
 - **"Context"**: The editor context provides access to study and message keys, participant flags, reports and external event handlers that can be referenced in your rules.
-You can import a context from a recent session or [create a new one](/docs/study-rules-editor/basics/editor-overview#context-editor) via the **"Open Context Editor"** button.
+You can import a context from a recent session or [create a new one](/docs/study-rules-editor/editor-overview#context-editor) via the **"Open Context Editor"** button.
 
 
 ### General
@@ -102,7 +102,7 @@ Rules defined here are applied **when a participant leaves the study** (e.g., wh
 
 The **Context Editor** is a configuration interface within the **Study Rules Editor**. It allows you to define the keys and identifiers that are used in **event handlers**, **conditions**, and **actions** throughout your study logic. These definitions ensure that all references to surveys, messages, flags, and other elements are valid and consistent.
 
-![Overview of context editor](../images/contextEditor.png)
+![Overview of context editor](./images/contextEditor.png)
 
 ### How to Access the Context Editor
 
@@ -179,4 +179,4 @@ Send data to external systems or trigger external workflows.
 
 ---
 
-For a complete list of available expressions and actions you can use in your study rules, see the [Methods of the study engine](/docs/study-rules-editor/basics/study-rules).
+For a complete list of available expressions and actions you can use in your study rules, see the [Methods of the study engine](/docs/study-rules-editor/study-rules).
diff --git a/content/docs/study-rules-editor/guide/entry-handler.mdx b/content/docs/study-rules-editor/guide/entry-handler.mdx
@@ -8,7 +8,7 @@ This example shows how to configure actions that are executed automatically when
 We’ll use the case where a **welcome message** is sent, the **intake survey** is assigned, and a **reminder message** for submitting the intake survey is scheduled.
 
 ## Prerequisite
-Before you can configure ENTRY actions, make sure the Survey keys and Message keys are already defined in the [Survey context](/docs/study-rules-editor/basics/editor-overview#context-editor).
+Before you can configure ENTRY actions, make sure the Survey keys and Message keys are already defined in the [Survey context](/docs/study-rules-editor/editor-overview#context-editor).
 
 Needed for this example:
 - Survey keys: `intake`

diff --git a/content/docs/study-rules-editor/meta.json b/content/docs/study-rules-editor/meta.json
@@ -2,5 +2,10 @@
     "title": "Study Rules Editor",
     "description": "Documentation for using the graphical study rules editor",
     "root": true,
-    "icon": "GitFork"
+    "icon": "GitFork",
+    "pages": [
+        "editor-overview",
+        "study-rules",
+        "guide"
+    ]
 }
diff --git a/...study-rules-editor/basics/study-rules.mdx → ...t/docs/study-rules-editor/study-rules.mdx b/...study-rules-editor/basics/study-rules.mdx → ...t/docs/study-rules-editor/study-rules.mdx
diff --git a/content/docs/survey-editor/basics/meta.json b/content/docs/survey-editor/basics/meta.json
diff --git a/.../docs/survey-editor/basics/conditions.mdx → content/docs/survey-editor/conditions.mdx b/.../docs/survey-editor/basics/conditions.mdx → content/docs/survey-editor/conditions.mdx
diff --git a/.../survey-editor/basics/editor-overview.mdx → ...nt/docs/survey-editor/editor-overview.mdx b/.../survey-editor/basics/editor-overview.mdx → ...nt/docs/survey-editor/editor-overview.mdx
@@ -1,18 +1,18 @@
 ---
-title: Survey Editor Overview
-description: Overview of the survey editor interface
+title: Editor Overview
+description: Main areas, navigation, and workflow for building surveys
 ---
 
 ## Survey Editor Dashboard
 
-![Screenshot of survey editor dashboard](../images/dashboardEditor.png)
+![Screenshot of survey editor dashboard](./images/dashboardEditor.png)
 
 This dashboard shows you the key content and structure of your survey.
 
 ### Top Navigation Bar
 - **Survey Editor**: displays the currently open editor.
 - **File**: Click here to generate a new survey, open an existing survey, save survey to disk or exit survey editor.
-- **View**: Click here to go to [Survey Properties](/docs/survey-editor/basics/editor-overview#survey-properties-workspace) section or Survey Simulator.
+- **View**: Click here to go to [Survey Properties](/docs/survey-editor/editor-overview#survey-properties-workspace) section or Survey Simulator.
 - **Survey Name:** Top left shows the unique key name of the current survey. Click on it to change its root key name.
 - **Survey label**: Top center displays the survey label. You can rename the survey label by clicking on it.
 - **Color Selector**: Click here to change the theme color of the survey.
@@ -24,18 +24,18 @@ This dashboard shows you the key content and structure of your survey.
 
 
 ### Survey Item List
-- **Items**: This section lists all the [items](/docs/survey-editor/basics/item-structure#survey-items) of the survey. Each item has:
+- **Items**: This section lists all the [items](/docs/survey-editor/item-structure#survey-items) of the survey. Each item has:
     - an icon symbolizing the type of question (e.g. checkmark in circle for single choice question)
     - an unique **Item Key** (e.g., `SCG1`).
     - an optional **Label** text (e.g., `Single Choice Question`).
-- Open the [item interface](/docs/survey-editor/basics/item-structure#item-interface) by clicking on the item or its icon shown in the left bar.
+- Open the [item interface](/docs/survey-editor/item-structure#item-interface) by clicking on the item or its icon shown in the left bar.
 - New items can be added by
     - Click on **+ Add new item** at the bottom of the item list
     - Click on **+** in the left sidebar.
 - Items can be ordered by
     - drag and drop them in the item list or left sidebar or
     - toggle the switch `Use random ordering` in the **Item ordering** section to random order items when the survey runs.
-- **Condition tab**: Switch to this tab to define [conditional logic](/docs/survey-editor/basics/conditions#conditions-and-expressions) that controls when items should be shown based on participant responses.
+- **Condition tab**: Switch to this tab to define [conditional logic](/docs/survey-editor/conditions#conditions-and-expressions) that controls when items should be shown based on participant responses.
 
 ---
 
@@ -44,7 +44,7 @@ This dashboard shows you the key content and structure of your survey.
 The **Survey Properties** workspace allows you to define and manage overall configuration and behavior of your survey.
 Click on **View** dropdown menu and select **Survey Properties** to open this section (shortcut **⌘ Cmd + 1**).
 
-![Screenshot of survey properties workspace basic information](../images/surveyPropertiesBasic.png)
+![Screenshot of survey properties workspace basic information](./images/surveyPropertiesBasic.png)
 
 ### Overview of Functions
 
@@ -62,7 +62,7 @@ Click on **View** dropdown menu and select **Survey Properties** to open this se
     Use the language toggle to view and edit content in different languages. This helps manage multilingual surveys efficiently.
 
 
-![Screenshot of survey properties workspace access conditions](../images/surveyPropertiesAccess.png)
+![Screenshot of survey properties workspace access conditions](./images/surveyPropertiesAccess.png)
 
 - **Access Conditions**
   Configure who is allowed to access and complete the survey.
@@ -75,7 +75,7 @@ Click on **View** dropdown menu and select **Survey Properties** to open this se
   - **Submission requires Login**
     Enable this toggle if participants must be logged in to submit their responses. If disabled, anyone with access to the survey can submit a response.
 
-![Screenshot of survey properties workspace max items per page](../images/surveyPropertiesMaxItems.png)
+![Screenshot of survey properties workspace max items per page](./images/surveyPropertiesMaxItems.png)
 
 - **Max Items per Page**
   Set the maximum number of question or content items that should appear on a single survey page for small and large screens.
@@ -90,7 +90,7 @@ The simulator allows you to preview and test your survey questions under differe
 Below are the key components visible in the interface:
 
 
-![Screenshot of survey simulator](../images/surveySimulator.png)
+![Screenshot of survey simulator](./images/surveySimulator.png)
 
 
 ### Survey Items

diff --git a/content/docs/survey-editor/guides/add-conditional-question.mdx b/content/docs/survey-editor/guides/add-conditional-question.mdx
@@ -22,7 +22,7 @@ Select the option **"Question or Info item"**.
 Select the option **"Consent"**. The consent item is now shown in your item list. Click on the item to see the content item interface.
 </Step>
 <Step>
-Select the component you would like to edit by clicking on it (Read more about [item components](/docs/survey-editor/basics/item-structure#survey-items)).
+Select the component you would like to edit by clicking on it (Read more about [item components](/docs/survey-editor/item-structure#survey-items)).
 </Step>
 <Step>
 Write your title text e.g. *"Consent to Data Storage"* in the text field of the title component. Go back to consent item interface.
@@ -126,6 +126,6 @@ In the dropdown menu, scroll to the Templates section and select **“Consent qu
   ![Condition interface with consent condition template](../images/addContact3.png)
   </Step>
   <Step>
-  A response slot key is not required. Use the survey [simulator](/docs/survey-editor/basics/editor-overview#simulator) to verify that the conditional logic works as expected.
+  A response slot key is not required. Use the survey [simulator](/docs/survey-editor/editor-overview#simulator) to verify that the conditional logic works as expected.
 </Step>
 </Steps>