feat: document platform architecture and enhance health server dashboard with OAuth setup guides

context.md

@@ -0,0 +1,107 @@
+## HuggingPost — Full Context
+
+**What it is:** Self-hosted Postiz v2.11.3 on Hugging Face Spaces. Social media scheduler with multi-channel posting (8 platforms work immediately, 12+ need OAuth setup).
+
+**Architecture:**
+
+- HF Space: single public port 7860 (health-server.js)
+- Internal: nginx:5000 → Postiz 4 PM2 procs (backend:3000, frontend:4200, workers, cron)
+- Postgres + Redis internal
+- Optional HF Dataset backup + sync loop
+
+---
+
+## Critical Issues Fixed
+
+### 1. **Font build hang** (FIXED)
+
+**Problem:** `next build` tried to fetch fonts from `fonts.gstatic.com` → blocked/throttled on HF → timeout → build never completes → container won't start.
+
+**Solution:** Vendor 4 woff2 files + runtime patch in `start.sh`:
+
+- Fonts: `vendor/fonts/PlusJakartaSans-{500,600}-{normal,italic}.woff2`
+- Patch script: `vendor/patch-jakarta-font.js` rewrites two layout.tsx files from `next/font/google` to `next/font/local`
+- Dockerfile Stage 2: copies fonts + patch script to `/opt/vendor/`
+- start.sh: detects if patch not applied (old cached image), applies it before frontend build
+
+**Commit:** `fd4cae0` (font patch)
+
+### 2. **Blank white page at /app/** (FIXED)
+
+**Root cause:** HF Spaces reverse proxy intercepts absolute redirects to its own hostname, resolves them server-side, returns 200 (not 307). Next.js redirects to `/auth` as `https://somratpro-huggingpost.hf.space/auth` → proxy resolves it → blank 200 page.
+
+**Solution:** Two fixes in health-server.js + Dockerfile:
+
+1. `rewriteLocation()` function converts absolute URLs (internal or SPACE_HOST) to relative `/app` paths so browser does the navigation
+2. Nginx patch: fix `proxy_set_header X-Forwarded-Proto` to use HF proxy's value, not internal scheme
+
+**Commits:** `57b8b04` (Location rewrite + nginx fix), `245f89d` (dashboard rewrite)
+
+### 3. **OAuth `client_id=undefined`** (NOT A BUG)
+
+LinkedIn/X/etc. OAuth links show `client_id=undefined` because env vars not set as HF Space secrets. User needs to create developer apps, add keys as secrets, restart. New dashboard guides users through this.
+
+---
+
+## Files Changed
+
+### `Dockerfile`
+
+- Stage 2, after postiz-builder COPY block: copy vendor fonts + patch script to `/opt/vendor/`
+- nginx.conf patch:
+  - Add `/app` prefix when proxying to Next.js (line 160: `proxy_pass http://127.0.0.1:4200/app/;`)
+  - Fix x-forwarded-proto (line 162: use `$http_x_forwarded_proto` not `$scheme`)
+
+### `start.sh`
+
+- Lines 172–187: Runtime font patch block
+  - If layout.tsx still has `next/font/google`, copy fonts, run patch script
+  - Idempotent — skips if already patched
+  - Happens before `next build` so no network calls
+
+### `health-server.js`
+
+- `getSocialPlatforms()` (lines 51–98): Array of all channels with ready status, setup URLs, env var names
+  - 8 "works immediately" (Bluesky, Mastodon, Telegram, Dev.to, Hashnode, Nostr, Lemmy, Warpcast)
+  - 12 "needs OAuth" (LinkedIn, X, Facebook, Instagram, Threads, YouTube, TikTok, Reddit, Pinterest, Discord, Slack)
+- `rewriteLocation()` (lines 465–505): Converts Location headers from Postiz
+  - Matches internal hosts (127.0.0.1, localhost) or SPACE_HOST
+  - Converts absolute URLs to `/app`-prefixed relative paths
+- `renderDashboard()` (lines 176–446): Complete rewrite
+  - Open Postiz button (disabled during boot, auto-activates when running)
+  - Status badges: Postiz, Uptime, Backup
+  - 4-step getting-started guide
+  - "Works immediately" section (8 platforms, collapsible)
+  - "Needs API keys" section (OAuth platforms, shows count configured, direct links to dev portals)
+  - "System & Backup" section (sync status, uptime monitor)
+  - Auto-refresh JS every 30s updates button state + badge states
+  - Deep-link to HF Space settings using SPACE_ID env var
+
+**Vendor files (new):**
+
+- `vendor/fonts/PlusJakartaSans-500-normal.woff2`, `-500-italic`, `-600-normal`, `-600-italic`
+- `vendor/patch-jakarta-font.js`
+
+---
+
+## Current State
+
+✅ **Working:**
+
+- Font patch applied at build time (Dockerfile) + runtime fallback (start.sh)
+- Next.js frontend builds successfully (~5 min first boot, <1 min with cached .next from backup)
+- Blank `/app/` screen fixed — middleware redirects work, browser navigates correctly
+- nginx routes work: /api → backend, /uploads → fs, / → frontend
+- Dashboard shows platform status, guides users through setup
+- HF_TOKEN secret no longer leaks in startup banner
+
+---
+
+## Deployment
+
+All changes pushed to:
+
+- GitHub: `somratpro/HuggingPost` (main branch)
+- HF Space: `somratpro/HuggingPost` (auto-synced)
+
+HF rebuilds automatically when Dockerfile or start.sh changes.

health-server.js

@@ -61,43 +61,495 @@ function getSocialPlatforms() {
     { name: "Dev.to",     emoji: "💻", noOAuth: true, ready: true,  note: "API key from dev.to settings" },
     { name: "Hashnode",   emoji: "📰", noOAuth: true, ready: true,  note: "API token from Hashnode settings" },
     // ── Needs OAuth app (env vars required) ───────────────────────────────────
-    { name: "LinkedIn",   emoji: "💼", ready: !!(e.LINKEDIN_CLIENT_ID && e.LINKEDIN_CLIENT_ID !== "undefined"),
+    { id: "linkedin",  name: "LinkedIn",   emoji: "💼", ready: !!(e.LINKEDIN_CLIENT_ID && e.LINKEDIN_CLIENT_ID !== "undefined"),
       setupUrl: "https://www.linkedin.com/developers/apps/new",
       envVars: ["LINKEDIN_CLIENT_ID", "LINKEDIN_CLIENT_SECRET"] },
-    { name: "X / Twitter",emoji: "🐦", ready: !!(e.X_API_KEY),
+    { id: "x",         name: "X / Twitter",emoji: "🐦", ready: !!(e.X_API_KEY),
       setupUrl: "https://developer.twitter.com/en/portal/projects-and-apps",
       envVars: ["X_API_KEY", "X_API_SECRET"] },
-    { name: "Facebook",   emoji: "📘", ready: !!(e.FACEBOOK_APP_ID),
+    { id: "facebook",  name: "Facebook",   emoji: "📘", ready: !!(e.FACEBOOK_APP_ID),
       setupUrl: "https://developers.facebook.com/apps/create/",
       envVars: ["FACEBOOK_APP_ID", "FACEBOOK_APP_SECRET"] },
-    { name: "Instagram",  emoji: "📸", ready: !!(e.FACEBOOK_APP_ID),
+    { id: "instagram", name: "Instagram",  emoji: "📸", ready: !!(e.FACEBOOK_APP_ID),
       setupUrl: "https://developers.facebook.com/apps/create/",
       envVars: ["FACEBOOK_APP_ID", "FACEBOOK_APP_SECRET"],
       note: "Uses same app as Facebook" },
-    { name: "Threads",    emoji: "🧵", ready: !!(e.THREADS_APP_ID),
+    { id: "threads",   name: "Threads",    emoji: "🧵", ready: !!(e.THREADS_APP_ID),
       setupUrl: "https://developers.facebook.com/apps/create/",
       envVars: ["THREADS_APP_ID", "THREADS_APP_SECRET"] },
-    { name: "YouTube",    emoji: "▶️",  ready: !!(e.YOUTUBE_CLIENT_ID),
+    { id: "youtube",   name: "YouTube",    emoji: "▶️",  ready: !!(e.YOUTUBE_CLIENT_ID),
       setupUrl: "https://console.cloud.google.com/apis/credentials",
       envVars: ["YOUTUBE_CLIENT_ID", "YOUTUBE_CLIENT_SECRET"] },
-    { name: "TikTok",     emoji: "🎵", ready: !!(e.TIKTOK_CLIENT_ID),
+    { id: "tiktok",    name: "TikTok",     emoji: "🎵", ready: !!(e.TIKTOK_CLIENT_ID),
       setupUrl: "https://developers.tiktok.com/",
       envVars: ["TIKTOK_CLIENT_ID", "TIKTOK_CLIENT_SECRET"] },
-    { name: "Reddit",     emoji: "🤖", ready: !!(e.REDDIT_CLIENT_ID),
+    { id: "reddit",    name: "Reddit",     emoji: "🤖", ready: !!(e.REDDIT_CLIENT_ID),
       setupUrl: "https://www.reddit.com/prefs/apps",
       envVars: ["REDDIT_CLIENT_ID", "REDDIT_CLIENT_SECRET"] },
-    { name: "Pinterest",  emoji: "📌", ready: !!(e.PINTEREST_CLIENT_ID),
+    { id: "pinterest", name: "Pinterest",  emoji: "📌", ready: !!(e.PINTEREST_CLIENT_ID),
       setupUrl: "https://developers.pinterest.com/apps/",
       envVars: ["PINTEREST_CLIENT_ID", "PINTEREST_CLIENT_SECRET"] },
-    { name: "Discord",    emoji: "🎮", ready: !!(e.DISCORD_CLIENT_ID),
+    { id: "discord",   name: "Discord",    emoji: "🎮", ready: !!(e.DISCORD_CLIENT_ID),
       setupUrl: "https://discord.com/developers/applications",
       envVars: ["DISCORD_CLIENT_ID", "DISCORD_CLIENT_SECRET", "DISCORD_BOT_TOKEN_ID"] },
-    { name: "Slack",      emoji: "💬", ready: !!(e.SLACK_ID),
+    { id: "slack",     name: "Slack",      emoji: "💬", ready: !!(e.SLACK_ID),
       setupUrl: "https://api.slack.com/apps?new_app=1",
       envVars: ["SLACK_ID", "SLACK_SECRET", "SLACK_SIGNING_SECRET"] },
   ];
 }
 
+// Returns detailed per-platform OAuth setup guide data.
+// publicUrl: "https://somratpro-huggingpost.hf.space" (no trailing slash)
+function getOAuthPlatformDetails(publicUrl) {
+  const cb = (provider) => `${publicUrl}/app/api/auth/connect/${provider}/callback`;
+  const e = process.env;
+  return [
+    {
+      id: "linkedin",
+      name: "LinkedIn",
+      emoji: "💼",
+      setupUrl: "https://www.linkedin.com/developers/apps/new",
+      docsUrl: "https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow",
+      callbackUrl: cb("linkedin"),
+      envVars: [
+        { name: "LINKEDIN_CLIENT_ID",     desc: "Client ID",     set: !!e.LINKEDIN_CLIENT_ID },
+        { name: "LINKEDIN_CLIENT_SECRET", desc: "Client Secret", set: !!e.LINKEDIN_CLIENT_SECRET },
+      ],
+      steps: [
+        { title: "Create a LinkedIn App", body: 'Visit the developer portal. Create a new app; set <strong>App type = Web</strong>.' },
+        { title: "Add OAuth redirect URL", body: 'In the <strong>Auth</strong> tab → OAuth 2.0 settings, paste the callback URL below.' },
+        { title: "Enable products", body: 'Add <strong>Sign In with LinkedIn using OpenID Connect</strong> and <strong>Share on LinkedIn</strong> products.' },
+        { title: "Copy credentials", body: 'From the Auth tab, copy <strong>Client ID</strong> and <strong>Client Secret</strong>.' },
+        { title: "Add to Space secrets", body: 'Open your HF Space settings, add both env vars below, then restart the Space.' },
+      ],
+    },
+    {
+      id: "x",
+      name: "X / Twitter",
+      emoji: "🐦",
+      setupUrl: "https://developer.twitter.com/en/portal/projects-and-apps",
+      docsUrl: "https://developer.twitter.com/en/docs/authentication/oauth-1-0a",
+      callbackUrl: cb("x"),
+      envVars: [
+        { name: "X_API_KEY",        desc: "API Key (Consumer Key)",    set: !!e.X_API_KEY },
+        { name: "X_API_SECRET",     desc: "API Secret (Consumer Secret)", set: !!e.X_API_SECRET },
+      ],
+      steps: [
+        { title: "Create an X Developer App", body: 'Apply for a developer account if you don\'t have one. Create a new project + app.' },
+        { title: "Enable OAuth 1.0a", body: 'In <strong>User authentication settings</strong>, enable <strong>OAuth 1.0a</strong>. Set type to <strong>Web App</strong>.' },
+        { title: "Add callback URL", body: 'Under Callback URI / Redirect URL, paste the callback URL below.' },
+        { title: "Set permissions", body: 'Set app permissions to <strong>Read and Write</strong> (or Read, Write and Direct Messages).' },
+        { title: "Copy credentials", body: 'From Keys and Tokens tab, copy <strong>API Key</strong> and <strong>API Key Secret</strong>.' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "facebook",
+      name: "Facebook",
+      emoji: "📘",
+      setupUrl: "https://developers.facebook.com/apps/create/",
+      docsUrl: "https://developers.facebook.com/docs/facebook-login/web",
+      callbackUrl: cb("facebook"),
+      envVars: [
+        { name: "FACEBOOK_APP_ID",     desc: "App ID",     set: !!e.FACEBOOK_APP_ID },
+        { name: "FACEBOOK_APP_SECRET", desc: "App Secret", set: !!e.FACEBOOK_APP_SECRET },
+      ],
+      steps: [
+        { title: "Create a Meta App", body: 'Go to Meta for Developers. Create a new app with use case <strong>Authenticate and request data from users</strong>.' },
+        { title: "Add Facebook Login product", body: 'In the app dashboard, click <strong>Add Product</strong> → Facebook Login → Web.' },
+        { title: "Add callback URL", body: 'In Facebook Login settings → Valid OAuth Redirect URIs, paste the callback URL below.' },
+        { title: "Request permissions", body: 'Add <strong>pages_manage_posts</strong>, <strong>pages_read_engagement</strong>, <strong>publish_to_groups</strong> permissions.' },
+        { title: "Copy credentials", body: 'From <strong>App Settings → Basic</strong>, copy App ID and App Secret.' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "instagram",
+      name: "Instagram",
+      emoji: "📸",
+      setupUrl: "https://developers.facebook.com/apps/create/",
+      docsUrl: "https://developers.facebook.com/docs/instagram-api",
+      callbackUrl: cb("instagram"),
+      envVars: [
+        { name: "FACEBOOK_APP_ID",     desc: "App ID (same as Facebook app)", set: !!e.FACEBOOK_APP_ID },
+        { name: "FACEBOOK_APP_SECRET", desc: "App Secret (same as Facebook app)", set: !!e.FACEBOOK_APP_SECRET },
+      ],
+      steps: [
+        { title: "Use the Facebook app", body: 'Instagram uses the same Meta app as Facebook — configure Facebook first.' },
+        { title: "Add Instagram Graph API product", body: 'In your Meta app dashboard, click <strong>Add Product</strong> → Instagram Graph API.' },
+        { title: "Connect an Instagram Business account", body: 'Your Instagram account must be a <strong>Professional (Business or Creator)</strong> account linked to a Facebook Page.' },
+        { title: "Add callback URL", body: 'In Instagram Login settings → Valid OAuth Redirect URIs, paste the callback URL below.' },
+        { title: "No extra env vars needed", body: 'Instagram and Facebook share <code>FACEBOOK_APP_ID</code> and <code>FACEBOOK_APP_SECRET</code>.' },
+      ],
+    },
+    {
+      id: "threads",
+      name: "Threads",
+      emoji: "🧵",
+      setupUrl: "https://developers.facebook.com/apps/create/",
+      docsUrl: "https://developers.facebook.com/docs/threads",
+      callbackUrl: cb("threads"),
+      envVars: [
+        { name: "THREADS_APP_ID",     desc: "App ID",     set: !!e.THREADS_APP_ID },
+        { name: "THREADS_APP_SECRET", desc: "App Secret", set: !!e.THREADS_APP_SECRET },
+      ],
+      steps: [
+        { title: "Create a Meta App", body: 'Create a Meta Developer app (separate from Facebook/Instagram if you prefer clean separation).' },
+        { title: "Add Threads API product", body: 'In the app dashboard, click <strong>Add Product</strong> → Threads API.' },
+        { title: "Add callback URL", body: 'In Threads API settings → Redirect URI, paste the callback URL below.' },
+        { title: "Copy credentials", body: 'From <strong>App Settings → Basic</strong>, copy App ID and App Secret.' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "youtube",
+      name: "YouTube",
+      emoji: "▶️",
+      setupUrl: "https://console.cloud.google.com/apis/credentials",
+      docsUrl: "https://developers.google.com/youtube/v3/guides/auth/server-side-web-apps",
+      callbackUrl: cb("youtube"),
+      envVars: [
+        { name: "YOUTUBE_CLIENT_ID",     desc: "OAuth 2.0 Client ID",     set: !!e.YOUTUBE_CLIENT_ID },
+        { name: "YOUTUBE_CLIENT_SECRET", desc: "OAuth 2.0 Client Secret", set: !!e.YOUTUBE_CLIENT_SECRET },
+      ],
+      steps: [
+        { title: "Create a Google Cloud project", body: 'Go to Google Cloud Console. Create a new project (or use existing).' },
+        { title: "Enable YouTube Data API v3", body: 'In APIs & Services → Library, search for <strong>YouTube Data API v3</strong> and enable it.' },
+        { title: "Create OAuth credentials", body: 'In APIs & Services → Credentials, click <strong>Create Credentials → OAuth client ID</strong>. Set type to <strong>Web application</strong>.' },
+        { title: "Add callback URL", body: 'Under Authorized redirect URIs, paste the callback URL below.' },
+        { title: "Configure OAuth consent screen", body: 'Set up consent screen with your app name. Add <strong>YouTube</strong> scopes.' },
+        { title: "Copy credentials", body: 'Download or copy the <strong>Client ID</strong> and <strong>Client Secret</strong>.' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "tiktok",
+      name: "TikTok",
+      emoji: "🎵",
+      setupUrl: "https://developers.tiktok.com/",
+      docsUrl: "https://developers.tiktok.com/doc/login-kit-web",
+      callbackUrl: cb("tiktok"),
+      envVars: [
+        { name: "TIKTOK_CLIENT_ID",     desc: "Client Key",    set: !!e.TIKTOK_CLIENT_ID },
+        { name: "TIKTOK_CLIENT_SECRET", desc: "Client Secret", set: !!e.TIKTOK_CLIENT_SECRET },
+      ],
+      steps: [
+        { title: "Apply for TikTok Developer access", body: 'Sign in at developers.tiktok.com. Apply for developer access (may take 1-2 days).' },
+        { title: "Create an app", body: 'Create a new app. Set <strong>Platform: Web</strong>.' },
+        { title: "Add Login Kit", body: 'Add <strong>Login Kit</strong> product. This enables OAuth for your app.' },
+        { title: "Add callback URL", body: 'In Login Kit settings → Redirect domain, add your HF Space hostname. In redirect URI, paste the callback URL below.' },
+        { title: "Request Content Posting API", body: 'Add <strong>Content Posting API</strong> product for posting videos/photos.' },
+        { title: "Copy credentials", body: 'From app overview, copy <strong>Client Key</strong> (as CLIENT_ID) and <strong>Client Secret</strong>.' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "reddit",
+      name: "Reddit",
+      emoji: "🤖",
+      setupUrl: "https://www.reddit.com/prefs/apps",
+      docsUrl: "https://github.com/reddit-archive/reddit/wiki/OAuth2",
+      callbackUrl: cb("reddit"),
+      envVars: [
+        { name: "REDDIT_CLIENT_ID",     desc: "Client ID (under app name)", set: !!e.REDDIT_CLIENT_ID },
+        { name: "REDDIT_CLIENT_SECRET", desc: "Secret",                     set: !!e.REDDIT_CLIENT_SECRET },
+      ],
+      steps: [
+        { title: "Go to Reddit App Preferences", body: 'Visit reddit.com/prefs/apps while logged in.' },
+        { title: "Create a new app", body: 'Click <strong>create another app…</strong>. Set type to <strong>web app</strong>.' },
+        { title: "Add callback URL", body: 'In the <strong>redirect uri</strong> field, paste the callback URL below.' },
+        { title: "Copy credentials", body: 'The Client ID is the string below the app name. Client Secret is labelled "secret".' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "pinterest",
+      name: "Pinterest",
+      emoji: "📌",
+      setupUrl: "https://developers.pinterest.com/apps/",
+      docsUrl: "https://developers.pinterest.com/docs/getting-started/set-up-app/",
+      callbackUrl: cb("pinterest"),
+      envVars: [
+        { name: "PINTEREST_CLIENT_ID",     desc: "App ID",     set: !!e.PINTEREST_CLIENT_ID },
+        { name: "PINTEREST_CLIENT_SECRET", desc: "App Secret", set: !!e.PINTEREST_CLIENT_SECRET },
+      ],
+      steps: [
+        { title: "Create a Pinterest App", body: 'Go to Pinterest Developer Portal and create a new app.' },
+        { title: "Add redirect URI", body: 'In app settings, add the callback URL below as a redirect URI.' },
+        { title: "Request scopes", body: 'Request <strong>boards:read</strong>, <strong>pins:read</strong>, <strong>pins:write</strong> scopes.' },
+        { title: "Copy credentials", body: 'Copy App ID and App Secret from the app settings.' },
+        { title: "Add to Space secrets", body: 'Add both env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "discord",
+      name: "Discord",
+      emoji: "🎮",
+      setupUrl: "https://discord.com/developers/applications",
+      docsUrl: "https://discord.com/developers/docs/topics/oauth2",
+      callbackUrl: cb("discord"),
+      envVars: [
+        { name: "DISCORD_CLIENT_ID",     desc: "Application ID",      set: !!e.DISCORD_CLIENT_ID },
+        { name: "DISCORD_CLIENT_SECRET", desc: "Client Secret",        set: !!e.DISCORD_CLIENT_SECRET },
+        { name: "DISCORD_BOT_TOKEN_ID",  desc: "Bot Token",            set: !!e.DISCORD_BOT_TOKEN_ID },
+      ],
+      steps: [
+        { title: "Create a Discord Application", body: 'Go to Discord Developer Portal → New Application.' },
+        { title: "Add redirect URL", body: 'In <strong>OAuth2 → Redirects</strong>, paste the callback URL below.' },
+        { title: "Create a Bot", body: 'In the <strong>Bot</strong> section, create a bot. Enable <strong>Message Content Intent</strong>.' },
+        { title: "Copy credentials", body: 'Copy Client ID and Client Secret from OAuth2 tab. Copy Bot Token from Bot tab.' },
+        { title: "Add to Space secrets", body: 'Add all three env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+    {
+      id: "slack",
+      name: "Slack",
+      emoji: "💬",
+      setupUrl: "https://api.slack.com/apps?new_app=1",
+      docsUrl: "https://api.slack.com/authentication/oauth-v2",
+      callbackUrl: cb("slack"),
+      envVars: [
+        { name: "SLACK_ID",             desc: "Client ID",      set: !!e.SLACK_ID },
+        { name: "SLACK_SECRET",         desc: "Client Secret",  set: !!e.SLACK_SECRET },
+        { name: "SLACK_SIGNING_SECRET", desc: "Signing Secret", set: !!e.SLACK_SIGNING_SECRET },
+      ],
+      steps: [
+        { title: "Create a Slack App", body: 'Go to api.slack.com/apps → Create New App → From scratch.' },
+        { title: "Add OAuth redirect URL", body: 'In <strong>OAuth & Permissions → Redirect URLs</strong>, paste the callback URL below.' },
+        { title: "Add Bot Token Scopes", body: 'Under Bot Token Scopes, add: <code>channels:join</code>, <code>chat:write</code>, <code>channels:read</code>, <code>groups:read</code>.' },
+        { title: "Install to workspace", body: 'Click <strong>Install to Workspace</strong> to generate tokens.' },
+        { title: "Copy credentials", body: 'From <strong>Basic Information</strong>: App Credentials has Client ID, Client Secret, Signing Secret.' },
+        { title: "Add to Space secrets", body: 'Add all three env vars below to your HF Space settings, then restart.' },
+      ],
+    },
+  ];
+}
+
+function renderSetupPage() {
+  const spaceHost = process.env.SPACE_HOST || null;
+  const spaceId = process.env.SPACE_ID || null;
+  const publicUrl = spaceHost ? `https://${spaceHost}` : "http://localhost:7860";
+  const settingsUrl = spaceId
+    ? `https://huggingface.co/spaces/${spaceId}/settings`
+    : "https://huggingface.co/settings/spaces";
+
+  const platforms = getOAuthPlatformDetails(publicUrl);
+  const configuredCount = platforms.filter(p => p.envVars.every(v => v.set)).length;
+
+  // Build sidebar items
+  const sidebarItems = platforms.map((p, i) => {
+    const allSet = p.envVars.every(v => v.set);
+    const anySet = p.envVars.some(v => v.set);
+    const indicator = allSet ? "✅" : anySet ? "⚠️" : "⚪";
+    return `<button class="plat-tab${i === 0 ? " active" : ""}" onclick="show(${i})" id="tab-${i}">
+      <span class="tab-emoji">${p.emoji}</span>
+      <span class="tab-name">${p.name}</span>
+      <span class="tab-indicator">${indicator}</span>
+    </button>`;
+  }).join("");
+
+  // Build detail panels
+  const panels = platforms.map((p, i) => {
+    const allSet = p.envVars.every(v => v.set);
+
+    const stepsList = p.steps.map((s, si) =>
+      `<div class="step"><div class="step-num">${si + 1}</div><div><div class="step-title">${s.title}</div><div class="step-body">${s.body}</div></div></div>`
+    ).join("");
+
+    const envRows = p.envVars.map(v =>
+      `<div class="env-row">
+        <div class="env-info">
+          <code class="env-name">${v.name}</code>
+          <span class="env-desc">${v.desc}</span>
+        </div>
+        <div class="env-actions">
+          ${v.set ? '<span class="badge badge-on" style="font-size:.7rem">Set ✓</span>' : '<span class="badge badge-off" style="font-size:.7rem">Not set</span>'}
+          <button class="copy-btn" onclick="copy('${v.name}', this)">Copy name</button>
+        </div>
+      </div>`
+    ).join("");
+
+    const statusBanner = allSet
+      ? `<div class="status-banner banner-ok">✅ All credentials configured — restart Space if you just added them.</div>`
+      : p.envVars.some(v => v.set)
+      ? `<div class="status-banner banner-warn">⚠️ Partially configured — check missing env vars below.</div>`
+      : `<div class="status-banner banner-info">ℹ️ Not yet configured — follow the steps below.</div>`;
+
+    return `<div class="panel${i === 0 ? " active" : ""}" id="panel-${i}">
+      <div class="panel-header">
+        <span class="panel-emoji">${p.emoji}</span>
+        <div>
+          <h2 class="panel-title">${p.name}</h2>
+          <a class="portal-link" href="${p.setupUrl}" target="_blank" rel="noopener">Open ${p.name} Developer Portal →</a>
+          ${p.docsUrl ? `<a class="portal-link" href="${p.docsUrl}" target="_blank" rel="noopener" style="margin-left:12px">Docs →</a>` : ""}
+        </div>
+      </div>
+
+      ${statusBanner}
+
+      <h3 class="section-label">Setup Steps</h3>
+      <div class="steps-list">${stepsList}</div>
+
+      <h3 class="section-label">Callback URL</h3>
+      <div class="copy-block">
+        <span class="copy-block-text" id="cb-${i}">${p.callbackUrl}</span>
+        <button class="copy-btn copy-btn-primary" onclick="copy('${p.callbackUrl}', this)">Copy</button>
+      </div>
+      <p class="hint">Paste this URL wherever the developer portal asks for "Redirect URI", "Callback URL", or "OAuth Redirect URL".</p>
+
+      <h3 class="section-label">Space Secrets to Add</h3>
+      <div class="env-list">${envRows}</div>
+      <div class="settings-cta">
+        <a href="${settingsUrl}" target="_blank" rel="noopener" class="settings-btn">Open Space Settings → Variables &amp; Secrets</a>
+        <p class="hint">After adding secrets, click <strong>Restart Space</strong> for them to take effect.</p>
+      </div>
+    </div>`;
+  }).join("");
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Platform Setup — HuggingPost</title>
+<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;600&display=swap" rel="stylesheet">
+<style>
+:root{--bg:#0f172a;--sidebar:#0d1829;--card:rgba(30,41,59,.75);--border:rgba(255,255,255,.08);--accent:linear-gradient(135deg,#ec4899,#8b5cf6);--text:#f8fafc;--dim:#94a3b8;--ok:#10b981;--warn:#f59e0b;--err:#ef4444;--blue:#3b82f6;--pink:#f472b6}
+*{box-sizing:border-box;margin:0;padding:0}
+body{font-family:'Outfit',sans-serif;background:var(--bg);color:var(--text);height:100vh;display:flex;flex-direction:column;overflow:hidden;
+  background-image:radial-gradient(at 0% 0%,rgba(236,72,153,.12) 0,transparent 50%),radial-gradient(at 100% 100%,rgba(139,92,246,.12) 0,transparent 50%)}
+/* Top bar */
+.topbar{display:flex;align-items:center;gap:16px;padding:14px 20px;border-bottom:1px solid var(--border);background:rgba(15,23,42,.8);backdrop-filter:blur(8px);flex-shrink:0}
+.topbar a{color:var(--dim);text-decoration:none;font-size:.85rem;display:flex;align-items:center;gap:6px}
+.topbar a:hover{color:var(--text)}
+.topbar h1{font-size:1.1rem;font-weight:600;background:var(--accent);-webkit-background-clip:text;-webkit-text-fill-color:transparent}
+.topbar-right{margin-left:auto;font-size:.8rem;color:var(--dim)}
+/* Layout */
+.layout{display:flex;flex:1;overflow:hidden}
+/* Sidebar */
+.sidebar{width:220px;flex-shrink:0;background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;padding:12px 8px}
+.sidebar-label{font-size:.65rem;text-transform:uppercase;color:var(--dim);letter-spacing:.1em;padding:4px 10px 8px}
+.plat-tab{width:100%;background:none;border:none;color:var(--text);font:inherit;font-size:.88rem;display:flex;align-items:center;gap:8px;padding:9px 10px;border-radius:10px;cursor:pointer;text-align:left;transition:background .15s}
+.plat-tab:hover{background:rgba(255,255,255,.05)}
+.plat-tab.active{background:rgba(236,72,153,.12);color:var(--pink)}
+.tab-emoji{font-size:1rem;width:22px;text-align:center;flex-shrink:0}
+.tab-name{flex:1}
+.tab-indicator{font-size:.8rem}
+/* Main panel */
+.main{flex:1;overflow-y:auto;padding:28px 32px}
+.panel{display:none;animation:fadein .2s ease}
+.panel.active{display:block}
+@keyframes fadein{from{opacity:0;transform:translateY(8px)}to{opacity:1;transform:translateY(0)}}
+.panel-header{display:flex;align-items:flex-start;gap:16px;margin-bottom:20px}
+.panel-emoji{font-size:2.5rem;flex-shrink:0;margin-top:2px}
+.panel-title{font-size:1.5rem;font-weight:600;margin-bottom:4px}
+.portal-link{color:var(--pink);font-size:.82rem;text-decoration:none}
+.portal-link:hover{text-decoration:underline}
+/* Status banner */
+.status-banner{padding:10px 14px;border-radius:10px;font-size:.85rem;margin-bottom:20px}
+.banner-ok{background:rgba(16,185,129,.1);border:1px solid rgba(16,185,129,.2);color:#6ee7b7}
+.banner-warn{background:rgba(245,158,11,.1);border:1px solid rgba(245,158,11,.2);color:#fcd34d}
+.banner-info{background:rgba(59,130,246,.1);border:1px solid rgba(59,130,246,.2);color:#93c5fd}
+/* Section labels */
+.section-label{font-size:.7rem;text-transform:uppercase;letter-spacing:.1em;color:var(--dim);margin:20px 0 10px}
+/* Steps */
+.steps-list{display:flex;flex-direction:column;gap:2px}
+.step{display:flex;gap:12px;padding:10px 12px;border-radius:10px;background:rgba(255,255,255,.03);border:1px solid var(--border)}
+.step-num{width:24px;height:24px;border-radius:50%;background:var(--accent);color:#fff;font-size:.7rem;font-weight:700;display:flex;align-items:center;justify-content:center;flex-shrink:0;margin-top:1px}
+.step-title{font-size:.88rem;font-weight:600;margin-bottom:3px}
+.step-body{font-size:.82rem;color:var(--dim);line-height:1.55}
+.step-body code{background:rgba(255,255,255,.1);padding:1px 5px;border-radius:4px;font-size:.8em;color:var(--text)}
+/* Callback URL copy block */
+.copy-block{display:flex;align-items:center;gap:10px;background:rgba(0,0,0,.3);border:1px solid var(--border);border-radius:10px;padding:12px 14px;margin-bottom:6px}
+.copy-block-text{flex:1;font-size:.82rem;color:#c4b5fd;word-break:break-all;font-family:monospace}
+/* Env vars */
+.env-list{display:flex;flex-direction:column;gap:6px;margin-bottom:16px}
+.env-row{display:flex;align-items:center;gap:10px;padding:10px 14px;background:rgba(255,255,255,.03);border:1px solid var(--border);border-radius:10px}
+.env-info{flex:1;display:flex;flex-direction:column;gap:3px}
+.env-name{font-size:.82rem;color:#c4b5fd;background:rgba(139,92,246,.1);padding:2px 7px;border-radius:5px;width:fit-content}
+.env-desc{font-size:.76rem;color:var(--dim)}
+.env-actions{display:flex;align-items:center;gap:8px;flex-shrink:0}
+/* Buttons */
+.copy-btn{background:rgba(255,255,255,.07);border:1px solid var(--border);color:var(--text);font:inherit;font-size:.75rem;padding:5px 10px;border-radius:7px;cursor:pointer;transition:background .15s;flex-shrink:0}
+.copy-btn:hover{background:rgba(255,255,255,.12)}
+.copy-btn.copied{background:rgba(16,185,129,.15);border-color:rgba(16,185,129,.3);color:var(--ok)}
+.copy-btn-primary{background:rgba(236,72,153,.15);border-color:rgba(236,72,153,.3);color:var(--pink);font-size:.82rem;padding:6px 14px}
+.copy-btn-primary:hover{background:rgba(236,72,153,.25)}
+.settings-btn{display:inline-block;background:var(--accent);color:#fff;text-decoration:none;padding:11px 20px;border-radius:10px;font-size:.88rem;font-weight:600;transition:opacity .2s}
+.settings-btn:hover{opacity:.85}
+.settings-cta{margin-top:4px}
+/* Badges */
+.badge{display:inline-flex;align-items:center;gap:4px;padding:2px 8px;border-radius:20px;font-weight:600}
+.badge-on{background:rgba(16,185,129,.12);color:var(--ok)}
+.badge-off{background:rgba(239,68,68,.12);color:var(--err)}
+/* Hint */
+.hint{font-size:.78rem;color:var(--dim);margin-top:6px;line-height:1.5;margin-bottom:16px}
+/* Mobile */
+@media(max-width:700px){
+  body{overflow:auto;height:auto}
+  .layout{flex-direction:column;overflow:visible}
+  .sidebar{width:100%;border-right:none;border-bottom:1px solid var(--border);display:flex;flex-wrap:wrap;padding:8px;gap:4px}
+  .sidebar-label{display:none}
+  .plat-tab{width:auto;flex:0 0 auto;padding:6px 10px}
+  .tab-name{display:none}
+  .main{padding:16px}
+}
+</style>
+</head>
+<body>
+<div class="topbar">
+  <a href="/">← Dashboard</a>
+  <h1>Platform Setup Guide</h1>
+  <span class="topbar-right">${configuredCount}/${platforms.length} configured</span>
+</div>
+<div class="layout">
+  <nav class="sidebar">
+    <div class="sidebar-label">OAuth Platforms</div>
+    ${sidebarItems}
+  </nav>
+  <main class="main">
+    ${panels}
+  </main>
+</div>
+<script>
+const PLATFORM_IDS = ${JSON.stringify(platforms.map(p => p.id))};
+function show(i) {
+  document.querySelectorAll('.plat-tab').forEach((t,j) => t.classList.toggle('active', j===i));
+  document.querySelectorAll('.panel').forEach((p,j) => p.classList.toggle('active', j===i));
+  if (PLATFORM_IDS[i]) history.replaceState(null, '', '#' + PLATFORM_IDS[i]);
+}
+function copy(text, btn) {
+  navigator.clipboard.writeText(text).then(() => {
+    const orig = btn.textContent;
+    btn.textContent = 'Copied!';
+    btn.classList.add('copied');
+    setTimeout(() => { btn.textContent = orig; btn.classList.remove('copied'); }, 1800);
+  }).catch(() => {
+    // fallback for non-HTTPS
+    const ta = document.createElement('textarea');
+    ta.value = text; ta.style.position='fixed'; ta.style.opacity='0';
+    document.body.appendChild(ta); ta.select();
+    try { document.execCommand('copy'); } catch {}
+    document.body.removeChild(ta);
+    const orig = btn.textContent;
+    btn.textContent = 'Copied!';
+    btn.classList.add('copied');
+    setTimeout(() => { btn.textContent = orig; btn.classList.remove('copied'); }, 1800);
+  });
+}
+// Hash-based deep-linking: /setup#linkedin jumps to LinkedIn tab
+(function() {
+  const hash = location.hash.replace('#','').toLowerCase();
+  if (hash) {
+    const idx = PLATFORM_IDS.indexOf(hash);
+    if (idx !== -1) show(idx);
+  }
+})();
+</script>
+</body>
+</html>`;
+}
+
 // ============================================================================
 // URL helpers
 // ============================================================================
@@ -112,7 +564,9 @@ function isLocalRoute(pathname) {
     pathname === "/health" ||
     pathname === "/status" ||
     pathname === "/" ||
-    pathname === ""
+    pathname === "" ||
+    pathname === "/setup" ||
+    pathname === "/setup/"
   );
 }
 
@@ -206,7 +660,7 @@ function renderDashboard(initialData) {
     return `<div class="plat-row">
       <span class="plat-icon" style="filter:grayscale(1);opacity:.5">${p.emoji}</span>
       <span class="plat-name" style="color:var(--dim)">${p.name}</span>
-      <a class="setup-link" href="${p.setupUrl}" target="_blank" rel="noopener">Get API keys →</a>
+      <a class="setup-link" href="/setup#${p.id}" style="margin-right:4px">Setup guide →</a>
     </div>`;
   }).join("");
 
@@ -329,7 +783,7 @@ code{background:rgba(255,255,255,.08);padding:1px 5px;border-radius:4px;font-siz
       <li>
         <div>
           <div class="s-title">Enable LinkedIn, X, YouTube… (optional)</div>
-          <div class="s-note">These require a free API key from each platform. Go to the platform's developer portal, create an app, then add the keys as <a href="https://huggingface.co/spaces/${process.env.SPACE_ID || "your-space"}/settings" target="_blank">Space secrets</a>. See the platform list below for direct links.</div>
+          <div class="s-note">These require a free API key from each platform. Use the <a href="/setup" style="color:#f472b6">Setup Guide →</a> for step-by-step instructions per platform, then add the keys as <a href="https://huggingface.co/spaces/${process.env.SPACE_ID || "your-space"}/settings" target="_blank">Space secrets</a>.</div>
         </div>
       </li>
       <li>
@@ -364,6 +818,7 @@ code{background:rgba(255,255,255,.08);padding:1px 5px;border-radius:4px;font-siz
       <div class="sync-note" style="margin-top:10px">
         After getting API keys: go to your <a href="https://huggingface.co/spaces/${process.env.SPACE_ID || "your-space"}/settings" target="_blank" style="color:#f472b6">Space Settings → Variables & Secrets</a>, add the keys, then restart the Space.
       </div>
+      <a href="/setup" style="display:inline-block;margin-top:12px;background:linear-gradient(135deg,#ec4899,#8b5cf6);color:#fff;text-decoration:none;padding:9px 18px;border-radius:10px;font-size:.84rem;font-weight:600">📖 Full Setup Guide →</a>
     </div>
   </div>
 
@@ -602,6 +1057,13 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  // ── /setup — OAuth platform setup wizard ─────────────────────────────────
+  if (pathname === "/setup" || pathname === "/setup/") {
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(renderSetupPage());
+    return;
+  }
+
   // ── Dashboard at exact / ─────────────────────────────────────────────────
   if (pathname === "/" || pathname === "") {
     void (async () => {