[Docs] - Full cleanup (#1105)

<!--

Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md

-->


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Removed Features**
  * Dashboard embed functionality has been removed from the platform.
  * Python template documentation and guides have been removed.

* **Documentation**
* Documentation structure has been significantly reorganized and
simplified.
  * Extensive template content and component guides have been removed.
* Apple OAuth integration guide updated with streamlined secret
generation flow.

* **Refactor**
  * Button component styling and variant system updated.
  * Routing configuration updated with simplified path handling.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: madster456

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)

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

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(),
-});

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',

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",

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