stack-auth · madster456 · Jan 27, 2026 · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -1,46 +1,90 @@
-# stack-docs
+# Stack Auth Documentation
 
-This is a Next.js application generated with
-[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+This is the documentation site for Stack Auth, built with [Next.js](https://nextjs.org) and [Fumadocs](https://fumadocs.dev).
 
-Run development server:
+## Development
 
 ```bash
-npm run dev
-# or
 pnpm dev
-# or
-yarn dev
 ```
 
-Open http://localhost:3000 with your browser to see the result.
+The docs server runs on port `8104` by default (or `${NEXT_PUBLIC_STACK_PORT_PREFIX}04`).
 
-## Explore
+## Project Structure
 
-In the project, you can see:
+### Content (`/content`)
 
-- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
-- `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.
+| Directory | Description |
+|-----------|-------------|
+| `content/docs/` | Main documentation (guides, SDK reference, components) |
+| `content/api/` | REST API reference documentation |
 
-| Route                     | Description                                            |
-| ------------------------- | ------------------------------------------------------ |
-| `app/(home)`              | The route group for your landing page and other pages. |
-| `app/docs`                | The documentation layout and pages.                    |
-| `app/api`                 | The documentation for API pages.                       |
-| `app/api/search/route.ts` | The Route Handler for search.                          |
+### App Routes (`/src/app`)
 
-### Fumadocs MDX
+| Route | Description |
+|-------|-------------|
+| `/docs` | Main documentation pages |
+| `/api` | API reference pages (rendered from OpenAPI specs) |
+| `/docs-embed` | Embedded docs for dashboard companion widget |
+| `/api-embed` | Embedded API docs for dashboard companion widget |
+| `/mcp-browser` | MCP documentation browser |
+| `/handler/[...stack]` | Stack Auth handler route |
+| `/api/search` | Search API endpoint |
+| `/api/chat` | AI documentation chat endpoint |
+| `/llms.txt` | LLM-friendly documentation (plain text) |
+| `/llms.mdx` | LLM-friendly documentation (MDX format) |
 
-A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
+### SDK Route Handlers
 
-Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
+These routes serve SDK-specific documentation:
 
-## Learn More
+- `/js/[...path]` - JavaScript SDK
+- `/next/[...path]` - Next.js SDK
+- `/react/[...path]` - React SDK
+- `/python/[...path]` - Python SDK
+- `/rest-api/[...path]` - REST API
+
+### Key Files
+
+| File | Description |
+|------|-------------|
+| `lib/source.ts` | Content source adapter using Fumadocs `loader()` |
+| `source.config.ts` | Fumadocs MDX configuration (frontmatter schema, etc.) |
+| `app/layout.config.tsx` | Shared layout options |
+| `lib/platform-config.ts` | Platform/framework configuration for code examples |
+
+### Components (`/src/components`)
+
+| Directory | Description |
+|-----------|-------------|
+| `api/` | API playground components |
+| `chat/` | AI chat interface |
+| `layout/` | Layout UI components (search, navigation) |
+| `layouts/` | Page layouts (docs, API) |
+| `mdx/` | Custom MDX components |
+| `stack-auth/` | Stack Auth demo components |
+| `ui/` | Base UI components (button, etc.) |
+
+### OpenAPI Specs (`/openapi`)
+
+Contains OpenAPI JSON specifications organized by access level:
+- `client-*.json` - Client-side API endpoints
+- `server-*.json` - Server-side API endpoints
+- `admin-*.json` - Admin API endpoints
+- `webhooks-*.json` - Webhook event schemas
 
-To learn more about Next.js and Fumadocs, take a look at the following
-resources:
+## Scripts
+
+```bash
+# Generate API docs from OpenAPI specs
+pnpm generate-openapi-docs
+
+# Clear generated docs
+pnpm clear-docs
+```
+
+## Learn More
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
-  features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs
+- [Fumadocs Documentation](https://fumadocs.dev)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Stack Auth Documentation](https://docs.stack-auth.com)
diff --git a/docs/content/docs/(guides)/concepts/auth-providers/apple.mdx b/docs/content/docs/(guides)/concepts/auth-providers/apple.mdx
@@ -48,14 +48,15 @@ You will need to create an Apple Developer account, and generate an Apple Servic
   <Step>
   ### Generate Your Client Secret
 
-  1. Navigate to the [Supabase Apple Secret Generator](https://supabase.com/docs/guides/auth/social-login/auth-apple#generating-a-client_secret) page.
-  2. Fill in the required fields:
-     - **Account ID**: Your Apple Developer account ID found at the top-right of the portal
-     - **Service ID**: The identifier of your Service ID (found in Identifiers > Service IDs)
-     - **Key ID**: The ID of the private key you just created
-     - **Choose File**: Upload the .p8 private key file you downloaded
-  3. Click **Generate Secret Key**.
-  4. Copy the generated secret immediately - you'll need it for the next step.
+  Use the tool below to generate your Apple Client Secret. You'll need:
+  - **Team ID**: Your Apple Developer account ID found at the top-right of the portal
+  - **Service ID**: The identifier of your Service ID (found in Identifiers > Service IDs)
+  - **Key ID**: The ID of the private key you just created
+  - **Private Key File**: Upload the .p8 private key file you downloaded
+
+  <AppleSecretGenerator />
+
+  Copy the generated secret immediately - you'll need it for the next step.
   </Step>
   <Step>
   ### Enable Apple OAuth in Stack Auth

diff --git a/docs/lib/source.ts b/docs/lib/source.ts
@@ -1,4 +1,4 @@
-import { api, dashboard, docs } from '@/.source';
+import { api, docs } from '@/.source';
 import { loader } from 'fumadocs-core/source';
 import { attachFile } from 'fumadocs-openapi/server';
 import { icons } from 'lucide-react';
@@ -38,13 +38,3 @@ export const apiSource = loader({
   },
   icon: createIconResolver(),
 });
-
-// Dashboard source for /dashboard routes
-export const dashboardSource = loader({
-  baseUrl: '/dashboard',
-  source: dashboard.toFumadocsSource(),
-  pageTree: {
-    attachFile,
-  },
-  icon: createIconResolver(),
-});
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
@@ -13,8 +13,8 @@ const config = {
   async headers() {
     return [
       {
-        // Allow CORS for dashboard routes to be accessed by the dashboard app
-        source: '/dashboard/:path*',
+        // Allow CORS for docs-embed routes to be accessed by the dashboard app
+        source: '/docs-embed/:path*',
         headers: [
           {
             key: 'Access-Control-Allow-Origin',
@@ -31,8 +31,8 @@ const config = {
         ],
       },
       {
-        // Allow CORS for embedded dashboard routes to be accessed by the dashboard app
-        source: '/dashboard-embed/:path*',
+        // Allow CORS for api-embed routes to be accessed by the dashboard app
+        source: '/api-embed/:path*',
         headers: [
           {
             key: 'Access-Control-Allow-Origin',

diff --git a/docs/package.json b/docs/package.json
@@ -15,7 +15,6 @@
     "lint:fix": "next lint --fix",
     "postinstall": "fumadocs-mdx",
     "generate-openapi-docs": "node scripts/generate-functional-api-docs.mjs",
-    "setup-openapi": "node scripts/setup-openapi.mjs",
     "clear-docs": "node scripts/clear-docs.js"
   },
   "dependencies": {
@@ -33,7 +32,6 @@
     "@stackframe/stack": "workspace:^",
     "@stackframe/stack-shared": "workspace:^",
     "@vercel/mcp-adapter": "^1.0.0",
-    "@xyflow/react": "^12.6.4",
     "ai": "^4.3.17",
     "class-variance-authority": "^0.7.1",
     "fumadocs-core": "15.3.3",

diff --git a/docs/source.config.ts b/docs/source.config.ts
@@ -33,17 +33,6 @@ export const api = defineDocs({
   },
 });
 
-// Separate collection for Dashboard content
-export const dashboard = defineDocs({
-  dir: './content/dashboard',
-  docs: {
-    schema: extendedFrontmatterSchema,
-  },
-  meta: {
-    schema: metaSchema,
-  },
-});
-
 export default defineConfig({
   mdxOptions: {
     // MDX options

diff --git a/docs/src/app/(home)/layout.tsx b/docs/src/app/(home)/layout.tsx
diff --git a/docs/src/app/(home)/page.tsx b/docs/src/app/(home)/page.tsx
diff --git a/docs/src/app/dashboard-embed/[[...slug]]/page.tsx b/docs/src/app/dashboard-embed/[[...slug]]/page.tsx
diff --git a/docs/src/app/dashboard-embed/layout.tsx b/docs/src/app/dashboard-embed/layout.tsx
diff --git a/docs/src/components/api/auth-panel.tsx b/docs/src/components/api/auth-panel.tsx
@@ -6,8 +6,8 @@ import { stringCompare } from '@stackframe/stack-shared/dist/utils/strings';
 import { AlertTriangle, ChevronDown, Key, X } from 'lucide-react';
 import { useEffect, useMemo, useState } from 'react';
 import { useSidebar } from '../layouts/sidebar-context';
+import { Button } from '../mdx/button';
 import { useAPIPageContext } from './api-page-wrapper';
-import { Button } from './button';
 
 type StackAuthHeaderKey =
   | 'X-Stack-Access-Type'

diff --git a/docs/src/components/api/button.tsx b/docs/src/components/api/button.tsx
diff --git a/docs/src/components/api/enhanced-api-page.tsx b/docs/src/components/api/enhanced-api-page.tsx
@@ -6,7 +6,7 @@ import { useCallback, useEffect, useState } from 'react';
 import type { OpenAPIOperation, OpenAPIParameter, OpenAPISchema, OpenAPISpec } from '../../lib/openapi-types';
 import { resolveSchema } from '../../lib/openapi-utils';
 import { useAPIPageContext } from './api-page-wrapper';
-import { Button } from './button';
+import { Button } from '../mdx/button';
 
 type EnhancedAPIPageProps = {
   document: string,

diff --git a/docs/src/components/api/webhooks-api-page.tsx b/docs/src/components/api/webhooks-api-page.tsx
@@ -3,7 +3,7 @@
 import { ArrowRight, Check, Code, Copy, Sparkles, Webhook } from 'lucide-react';
 import { useCallback, useEffect, useState } from 'react';
 import { codeToHtml } from 'shiki';
-import { Button } from './button';
+import { Button } from '../mdx/button';
 
 // Types for OpenAPI specification (focused on webhooks)
 type OpenAPISchema = {

diff --git a/docs/src/components/embedded-link-interceptor.tsx b/docs/src/components/embedded-link-interceptor.tsx
@@ -24,8 +24,7 @@ const getEmbeddedUrl = (href: string, currentPath: string): string => {
   // Already an embedded URL?
   if (
     cleanPath.startsWith('/docs-embed') ||
-    cleanPath.startsWith('/api-embed') ||
-    cleanPath.startsWith('/dashboard-embed')
+    cleanPath.startsWith('/api-embed')
   ) {
     return withSuffix(cleanPath);
   }
@@ -37,9 +36,6 @@ const getEmbeddedUrl = (href: string, currentPath: string): string => {
   if (cleanPath === '/api' || cleanPath.startsWith('/api/')) {
     return withSuffix(cleanPath.replace(/^\/api(?=\/|$)/, '/api-embed'));
   }
-  if (cleanPath === '/dashboard' || cleanPath.startsWith('/dashboard/')) {
-    return withSuffix(cleanPath.replace(/^\/dashboard(?=\/|$)/, '/dashboard-embed'));
-  }
 
   // Relative paths -> resolve against current embedded section (if present)
   if (!cleanPath.startsWith('/') && !cleanPath.startsWith('#')) {
@@ -125,7 +121,6 @@ export function EmbeddedLinkInterceptor() {
       if (
         href.startsWith('/docs/') ||
         href.startsWith('/api/') ||
-        href.startsWith('/dashboard/') ||
         (!/^[a-zA-Z][a-zA-Z+\-.]*:/.test(href) && !href.startsWith('#'))
       ) {
         event.preventDefault();