docs/src/app/api-embed/layout.tsx (1)

1-16: Same embed-layout nits as docs-embed.

Mirror the dvh change and verify EmbeddedLinkInterceptor is a client component as noted in docs-embed/layout.tsx.

docs/templates-dashboard/permissions.mdx (1)

48-57: Add a brief best-practices note and link the Companion.

Strengthen the “Permission Validation” section with least-privilege guidance and make “Stack Companion” a clickable link to its entry point.

Apply:

 ## Permission Validation
 Ensure proper access control by:
 - Testing permission assignments
 - Reviewing access logs
 - Validating permission logic
+
+### Best Practices
+- Prefer least-privilege roles; avoid granting broad project-wide permissions by default.
+- Review effective permissions after team/role changes.
+- Periodically audit dormant users and stale teams.
 
 ## Need Help?
 
-Use the Stack Companion for detailed permission configuration guidance.
+Use the [Stack Companion](</dashboard-embed/companion>) for detailed permission configuration guidance.

docs/templates-dashboard/settings.mdx (1)

28-48: Clarify duplicated “Rate limiting” bullets.

“Rate limiting” appears under both Security Settings and API Configuration; clarify scope or deduplicate to avoid confusion.

Option A (clarify scopes):

 ### Security Settings
 Configure security policies:
 - Password requirements
 - Multi-factor authentication
 - Session management
-- Rate limiting
+- Authentication rate limiting (login/signup, OTP attempts)

 ### API Configuration
 Manage API access:
 - API keys
 - Webhook endpoints
 - CORS settings
-- Rate limiting
+- API rate limiting (per-key/per-route quotas)

Option B (deduplicate to Security Settings only and replace API bullet):

- - Rate limiting
+ - SDK configuration (environments, base URLs)

docs/templates-dashboard/users.mdx (2)

2-7: Name consistency: prefer “User Management”.

Use singular form to align with common docs conventions and sidebar patterns (“User Management”).

-title: Users Management
+title: User Management
@@
-# Users Management
+# User Management

---

29-35: Add privacy/audit guidance when editing user data.

A short caution helps set expectations around PII and compliance.

 ### Managing User Data
 You can update user information including:
 - Profile details
 - Custom metadata
 - Contact preferences
 - Account status
+> Note: Limit access to PII to authorized roles only. Changes should be auditable (record who changed what and when).

docs/templates-dashboard/teams.mdx (1)

2-7: Name consistency: prefer “Team Management”.

Match singular form used elsewhere.

-title: Teams Management
+title: Team Management
@@
-# Teams Management
+# Team Management

docs/templates-dashboard/auth-providers.mdx (5)

21-26: Name the provider consistently as “X (formerly Twitter)”.

Minor branding nit for clarity.

-- **Twitter/X**: Social media integration
+- **X (formerly Twitter)**: Social media integration

---

27-31: Clarify SAML is a protocol and mention common IdPs.

Prevents confusion vs. OAuth “providers.”

-### Enterprise Providers
-- **Microsoft**: Azure AD and Office 365 integration
-- **SAML**: Enterprise single sign-on
-- **LinkedIn**: Professional network integration
+### Enterprise Providers
+- **Microsoft Entra ID (Azure AD)**: Enterprise Microsoft login
+- **SAML (via IdPs like Okta, OneLogin, Entra ID, Auth0)**: Enterprise single sign‑on
+- **LinkedIn**: Professional network integration

---

32-38: Add critical OAuth setup steps (security + reliability).

PKCE, exact redirect URIs, and environment-specific callbacks are easy to miss.

  ### Configuration Steps
-1. **Create OAuth Application**: Set up your app with the provider
-2. **Configure Credentials**: Add client ID and secret to Stack Auth
-3. **Set Callback URLs**: Configure redirect URLs for your application
-4. **Test Integration**: Verify the authentication flow works correctly
+1. **Create OAuth Application**: Set up your app with the provider
+2. **Configure Credentials**: Add client ID and secret to Stack Auth (store secrets server-side only)
+3. **Set Callback URLs**: Add exact authorized redirect URIs per environment (e.g., dev, staging, prod)
+4. **Enable PKCE** (recommended) and required grant types per provider
+5. (If supported) **Set post‑logout redirect URIs**
+6. **Test Integration**: Verify success, error, and cancel flows

---

41-47: Call out post‑logout URIs and least‑privilege scopes.

Keeps deployments secure by default.

  ### OAuth Configuration
  Each provider requires:
  - Client ID
  - Client Secret
  - Authorized redirect URIs
- - Scope permissions
+ - (If supported) Post‑logout redirect URIs
+ - Scope permissions (use least privilege; request only what you need)

---

54-57: Link to provider‑specific runbooks from Companion.

If you have deep links (Google/GitHub/etc.), adding them here reduces bounce.

I can add Companion deeplinks for top providers if you share their slugs.

docs/src/components/mdx/embedded-link.tsx (3)

9-26: Harden path rewriting and handle “/docs” root, queries, and hashes.

Current replace() misses “/docs” without trailing slash and query/hash forms; also guard against re‑rewriting embedded routes.

-const getEmbeddedUrl = (href: string): string => {
+const getEmbeddedUrl = (href: string): string => {
   // Handle relative links
   if (href.startsWith('/')) {
-    // Convert regular doc routes to embedded routes
-    if (href.startsWith('/docs/')) {
-      return href.replace('/docs/', '/docs-embed/');
-    }
-    if (href.startsWith('/api/')) {
-      return href.replace('/api/', '/api-embed/');
-    }
-    if (href.startsWith('/dashboard/')) {
-      return href.replace('/dashboard/', '/dashboard-embed/');
-    }
+    // Skip if already embedded
+    if (href.startsWith('/docs-embed/') || href.startsWith('/api-embed/') || href.startsWith('/dashboard-embed/')) {
+      return href;
+    }
+    // Convert regular routes to embedded routes (match with or without trailing slash)
+    if (href === '/docs' || href.startsWith('/docs/') || href.startsWith('/docs?') || href.startsWith('/docs#')) {
+      return href.replace(/^\/docs(?=\/|$)/, '/docs-embed');
+    }
+    if (href === '/api' || href.startsWith('/api/') || href.startsWith('/api?') || href.startsWith('/api#')) {
+      return href.replace(/^\/api(?=\/|$)/, '/api-embed');
+    }
+    if (href === '/dashboard' || href.startsWith('/dashboard/') || href.startsWith('/dashboard?') || href.startsWith('/dashboard#')) {
+      return href.replace(/^\/dashboard(?=\/|$)/, '/dashboard-embed');
+    }
   }
   // Return unchanged for external links or already embedded links
   return href;
 };

---

45-47: Protect target=_blank links against reverse‑tabnabbing.

Add rel when opening new tabs.

-  // For external links, use regular anchor tag
-  return <a href={embeddedHref} {...props}>{children}</a>;
+  // For external links, use regular anchor tag
+  const rel = props.target === '_blank'
+    ? [props.rel, 'noopener', 'noreferrer'].filter(Boolean).join(' ')
+    : props.rel;
+  return <a href={embeddedHref} {...props} rel={rel}>{children}</a>;

---

8-26: Deduplicate getEmbeddedUrl across the codebase.

If a similar helper exists in embedded-link-interceptor.tsx, consider exporting a shared util to avoid drift.

Would you like me to extract a shared helper (e.g., docs/src/lib/embedded-url.ts) and update both call sites?

docs/templates-dashboard/analytics.mdx (2)

46-51: Verify feature availability (“CSV export”, “PDF generation”, “API access”, “Custom dashboard”).

If any are roadmap-only, mark as “coming soon” or scope by plan to avoid overpromising.

I can update copy once you confirm which features ship today vs. later.

---

21-37: Tighten metric definitions (time windows, filters).

Add brief definitions (e.g., DAU/MAU timezones, sign‑in “success” criteria) to reduce ambiguity.

docs/src/app/global.css (3)

198-205: Be cautious hiding scrollbars (a11y).

Hidden scrollbars can hurt discoverability and keyboard users. Limit usage to the embed container only, and ensure visible focus/scroll affordances.

Do all elements with .scrollbar-hide still meet WCAG 2.2 focus visibility?

---

241-249: Avoid aggressive word-break on links/code.

word-break: break-all can shatter readable text. Prefer overflow-wrap:anywhere for long tokens/URLs.

-.prose a[href*="://"] {
-  word-break: break-all;
-}
+.prose a[href*="://"] {
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
 
 /* Break very long strings that have no spaces (like tokens, hashes, etc.) */
-.prose code:not(pre code) {
-  word-break: break-all;
-}
+.prose code:not(pre code) {
+  overflow-wrap: anywhere;
+  word-break: break-word;
+  hyphens: auto;
+}

---

227-233: Consider momentum scrolling on narrow tables.

Improves mobile UX inside embeds.

 .prose table {
   /* Make tables responsive */
   display: block;
   overflow-x: auto;
   white-space: nowrap;
   max-width: 100%;
+  -webkit-overflow-scrolling: touch;
 }

apps/dashboard/src/components/stack-companion/dashboard-docs-widget.tsx (7)

16-26: Remove unused ROUTE_TO_DOC_MAP and prefer ES6 Map per guidelines

This constant isn’t referenced; drop it to avoid drift. Also, for future lookups, prefer Map over Record.

-// Map dashboard routes to documentation pages
-const ROUTE_TO_DOC_MAP: Record<string, string> = {
-  '/users': 'users',
-  '/teams': 'teams',
-  '/permissions': 'permissions',
-  '/settings': 'settings',
-  '/auth-providers': 'auth-providers',
-  '/analytics': 'analytics',
-  '/': 'overview',
-  '': 'overview',
-};
+// (removed) Unused; route resolution happens via DASHBOARD_ROUTE_PATTERNS.

---

29-37: Switch TITLE_MAP to ES6 Map

Aligns with repo guideline and avoids accidental key collisions.

-// Title mapping for pages
-const TITLE_MAP: Record<string, string> = {
-  'overview': 'Dashboard Overview',
-  'users': 'Users Management',
-  'teams': 'Teams Management',
-  'permissions': 'Permissions Management',
-  'settings': 'Project Settings',
-  'auth-providers': 'Authentication Providers',
-  'analytics': 'Analytics & Insights',
-};
+// Title mapping for pages
+const TITLE_MAP = new Map<string, string>([
+  ['overview', 'Dashboard Overview'],
+  ['users', 'Users Management'],
+  ['teams', 'Teams Management'],
+  ['permissions', 'Permissions Management'],
+  ['settings', 'Project Settings'],
+  ['auth-providers', 'Authentication Providers'],
+  ['analytics', 'Analytics & Insights'],
+]);

Follow-ups needed where the map is read; see lines 75 and 212.

---

39-48: Auth route mapping: handle both /auth-methods and /auth-providers

If the app ever routes to /auth-providers directly, we’ll miss it. Add an explicit pattern.

   { pattern: /\/settings(?:\/.*)?$/, docPage: 'settings' },
   { pattern: /\/auth-methods(?:\/.*)?$/, docPage: 'auth-providers' }, // Route is auth-methods but docs are auth-providers
+  { pattern: /\/auth-providers(?:\/.*)?$/, docPage: 'auth-providers' },
   { pattern: /\/analytics(?:\/.*)?$/, docPage: 'analytics' },

Please confirm actual dashboard paths.

---

191-199: Harden iframe attrs and improve UX

Add lazy loading, referrer policy, and popup allowances (if embedded links open windows).

-            <iframe
+            <iframe
               src={docContent.url}
               className="w-full h-full border-0 rounded-md bg-white dark:bg-gray-900"
               onLoad={handleIframeLoad}
               onError={handleIframeError}
               title={`Documentation: ${docContent.title}`}
-              sandbox="allow-scripts allow-same-origin"
+              sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
+              referrerPolicy="strict-origin-when-cross-origin"
+              loading="lazy"
             />

If popups aren’t desired from inside the embed, drop the allow-popups flags.

---

75-75: Update title access for Map

Follow-up to Map switch.

-  const title = TITLE_MAP[page] || `Dashboard ${page}`;
+  const title = TITLE_MAP.get(page) ?? `Dashboard ${page}`;

---

212-213: Update prompt title access for Map

Follow-up to Map switch.

-                    Switch to <span className="font-medium">{TITLE_MAP[getDashboardPage(pathname)] || 'current page'}</span>?
+                    Switch to <span className="font-medium">{TITLE_MAP.get(getDashboardPage(pathname)) ?? 'current page'}</span>?

---

90-116: Simplify effect logic to avoid extra runs

Current deps (docContent/currentPageDoc) can retrigger the effect; splitting “initial load” and “route change while active” into two effects will reduce state juggling.

I can provide a small refactor if you want it applied here.

apps/dashboard/src/components/stack-companion.tsx (2)

12-12: Lazy-load UnifiedDocsWidget to cut initial bundle

Avoid pulling the docs embed code until the Docs tab is opened.

Example:

import dynamic from 'next/dynamic';
// …
const UnifiedDocsWidget = dynamic(
  () => import('./stack-companion/unified-docs-widget').then(m => m.UnifiedDocsWidget),
  { ssr: false }
);

---

366-366: Render condition is fine; consider passing isActive=activeItem==='docs' for clarity

No behavior change; slightly clearer intent and future-proof if reused.

-  <UnifiedDocsWidget isActive={true} />
+  <UnifiedDocsWidget isActive={activeItem === 'docs'} />

docs/lib/source.ts (1)

42-50: Confirm /dashboard-embed loader exists (or add it here)

Embeds point to /dashboard-embed/. If that route isn’t defined elsewhere, add a companion loader to mirror /dashboard with embedded components.

Example (add alongside):

export const dashboardEmbedSource = loader({
  baseUrl: '/dashboard-embed',
  source: dashboard.toFumadocsSource(),
  pageTree: { attachFile },
  icon: createIconResolver(),
});

docs/templates-dashboard/overview.mdx (1)

14-19: Link the quick navigation items to their pages

Improves discoverability and verifies routes.

- - **Users**: Manage user accounts, view user details, and handle user-related operations
+ - **[Users](/dashboard/users)**: Manage user accounts, view user details, and handle user-related operations
- - **Teams**: Create and manage teams, handle team memberships and permissions  
+ - **[Teams](/dashboard/teams)**: Create and manage teams, handle team memberships and permissions  
- - **Permissions**: Configure role-based access control and user permissions
+ - **[Permissions](/dashboard/permissions)**: Configure role-based access control and user permissions
- - **Settings**: Configure your project settings, authentication providers, and integrations
+ - **[Settings](/dashboard/settings)**: Configure your project settings, authentication providers, and integrations
- - **Analytics**: View authentication metrics and user engagement data
+ - **[Analytics](/dashboard/analytics)**: View authentication metrics and user engagement data

If the embed uses a custom link component, swap for it as appropriate.

docs/src/app/docs-embed/[[...slug]]/page.tsx (2)

5-11: Fix params typing; Next.js App Router does not pass a Promise for params

params should be a plain object. You don't need await params. This also improves type-safety and consistency with Next types.

-export default async function DocsEmbedPage({
+export default async function DocsEmbedPage({
   params,
 }: {
-  params: Promise<{ slug?: string[] }>,
+  params: { slug?: string[] },
 }) {
-  const { slug } = await params;
+  const { slug } = params;

---

3-3: Prefer notFound() over redirect("/") for missing pages

Use notFound() to return a proper 404 and avoid unexpected cross-origin redirects inside embeds.

-import { redirect } from 'next/navigation';
+import { notFound } from 'next/navigation';
...
-  if (!page) redirect("/");
+  if (!page) notFound();

Also applies to: 13-13

docs/src/app/api-embed/[[...slug]]/page.tsx (2)

5-11: Align params typing with Next.js conventions

Same as docs-embed: params should not be a Promise; drop await.

-export default async function ApiEmbedPage({
+export default async function ApiEmbedPage({
   params,
 }: {
-  params: Promise<{ slug?: string[] }>,
+  params: { slug?: string[] },
 }) {
-  const { slug } = await params;
+  const { slug } = params;

---

3-3: Return 404 instead of redirect for missing pages

Prefer notFound() for correct HTTP semantics in embeds.

-import { redirect } from 'next/navigation';
+import { notFound } from 'next/navigation';
...
-  if (!page) redirect("/");
+  if (!page) notFound();

Also applies to: 13-13

docs/src/app/dashboard-embed/layout.tsx (1)

6-14: Use dynamic viewport units to avoid mobile "100vh" issues

Replace h-screen/min-h-screen with 100dvh to prevent overflow under mobile browser UI.

-    <div className="min-h-screen bg-fd-background">
+    <div className="min-h-[100dvh] bg-fd-background">
...
-      <main className="h-screen overflow-hidden">
+      <main className="h-[100dvh] overflow-hidden">

docs/src/app/docs-embed/layout.tsx (1)

9-11: Use dvh to avoid mobile viewport bugs.

Replace h-screen/h-full with h-dvh (and keep the inner overflow-y-auto) to avoid iOS Safari 100vh issues in iframes.

Apply:

-      <main className="h-screen overflow-hidden">
-        <div className="h-full overflow-y-auto overflow-x-hidden scrollbar-hide">
+      <main className="h-dvh overflow-hidden">
+        <div className="h-dvh overflow-y-auto overflow-x-hidden scrollbar-hide">

docs/scripts/generate-docs.js (1)

368-417: Include dashboard static assets (images) alongside MDX.

generateDashboardDocs() copies only .mdx and optional meta.json. If dashboard docs reference images (e.g., imgs), they’ll 404.

Append inside generateDashboardDocs() after writing meta.json:

   console.log('Dashboard documentation generation complete!');
 }
 
+// Copy dashboard asset dirs if present (parity with copyAssets())
+const DASHBOARD_ASSET_DIRS = ['imgs'];
+for (const dir of DASHBOARD_ASSET_DIRS) {
+  const srcDir = path.join(DASHBOARD_TEMPLATE_DIR, dir);
+  if (fs.existsSync(srcDir)) {
+    const files = glob.sync('**/*', { cwd: srcDir, nodir: true });
+    for (const file of files) {
+      const srcFile = path.join(srcDir, file);
+      const destFile = path.join(DASHBOARD_OUTPUT_DIR, dir, file);
+      fs.mkdirSync(path.dirname(destFile), { recursive: true });
+      fs.copyFileSync(srcFile, destFile);
+      console.log(`Copied dashboard asset: ${srcFile} -> ${destFile}`);
+    }
+  }
+}

apps/dashboard/src/components/stack-companion/unified-docs-widget.tsx (2)

20-29: Prefer ES6 Map over Record for title map (per repo guideline).

Use Map for key lookups; adjust call site accordingly.

Apply:

-const DASHBOARD_TITLE_MAP: Record<string, string> = {
-  'overview': 'Dashboard Overview',
-  'users': 'Users Management',
-  'teams': 'Teams Management',
-  'permissions': 'Permissions Management',
-  'settings': 'Project Settings',
-  'auth-providers': 'Authentication Providers',
-  'analytics': 'Analytics & Insights',
-};
+const DASHBOARD_TITLE_MAP = new Map<string, string>([
+  ['overview', 'Dashboard Overview'],
+  ['users', 'Users Management'],
+  ['teams', 'Teams Management'],
+  ['permissions', 'Permissions Management'],
+  ['settings', 'Project Settings'],
+  ['auth-providers', 'Authentication Providers'],
+  ['analytics', 'Analytics & Insights'],
+]);

-      const title = DASHBOARD_TITLE_MAP[page] || `Dashboard ${page}`;
+      const title = DASHBOARD_TITLE_MAP.get(page) ?? `Dashboard ${page}`;

Also applies to: 88-89

---

58-75: Remove unused DOC_TYPE_OPTIONS or wire it to UI.

It’s currently unused; trim to reduce dead code or integrate into a selector.

Apply:

-// Navigation options for different doc types
-const DOC_TYPE_OPTIONS: Array<{ type: DocType, label: string, description: string }> = [
-  {
-    type: 'dashboard',
-    label: 'Dashboard Docs',
-    description: 'Documentation for this dashboard page'
-  },
-  {
-    type: 'docs',
-    label: 'Main Docs',
-    description: 'Complete Stack Auth documentation'
-  },
-  {
-    type: 'api',
-    label: 'API Reference',
-    description: 'API endpoints and reference'
-  },
-];

docs/src/components/embedded-link-interceptor.tsx (4)

80-86: Remove unused navigation history state.

setNavigationHistory is write-only and not rendered. Trim for clarity.

-  const [, setNavigationHistory] = useState<string[]>([]);
-
-  // Initialize navigation history with current URL
-  useEffect(() => {
-    setNavigationHistory([window.location.pathname]);
-  }, []);
+  // (removed) navigation history state

-            // Add to navigation history
-            setNavigationHistory(prev => [...prev, embeddedHref]);
+            // navigation history removed

Also applies to: 140-142

---

127-133: Guard console logging or remove.

Avoid noisy logs in production.

-        // Debug logging
-        console.log('Link Debug:', {
-          originalHref: href,
-          currentPath,
-          resolvedHref: embeddedHref
-        });
+        // Debug logging (guarded)
+        if (process.env.NEXT_PUBLIC_EMBED_DEBUG === '1') {
+          console.debug('Link Debug:', { originalHref: href, currentPath, resolvedHref: embeddedHref });
+        }

---

171-181: Hide the debug UI behind an env flag to avoid exposing it to end users.

Gate the toggle/window with NEXT_PUBLIC_EMBED_DEBUG === '1'.

-      {/* Debug Toggle Button */}
-      <div className="fixed top-4 right-4 z-50">
+      {process.env.NEXT_PUBLIC_EMBED_DEBUG === '1' && (
+      {/* Debug Toggle Button */}
+      <div className="fixed top-4 right-4 z-50">
         <button
           onClick={() => setShowDebug(!showDebug)}
           className="px-3 py-2 bg-gray-800 hover:bg-gray-700 text-white text-xs font-medium rounded-md shadow-lg transition-colors"
           title="Toggle debug window"
         >
           Debug {showDebug ? '▼' : '▲'}
         </button>
       </div>
 
-      {/* Debug Window */}
-      {showDebug && (
+      {/* Debug Window */}
+      {showDebug && (
         <div className="fixed top-16 right-4 w-96 max-h-96 bg-gray-900 text-white text-xs rounded-lg shadow-2xl z-50 overflow-hidden">
           ...
         </div>
-      )}
+      )}
+      )}

Also applies to: 183-257

---

5-67: Extract shared URL‐rewriting helper. Both embedded-link-interceptor.tsx and mdx/embedded-link.tsx duplicate the /docs/, /api/, and /dashboard/→-embed/ mappings—pull that logic into a common util to keep them in sync.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

apps/dashboard/src/components/stack-companion/unified-docs-widget.tsx (2)

99-113: Remove hardcoded localhost; parameterize docs origin (avoids mixed-content and non-prod breakage).

Build embed URLs from a configurable origin (e.g., NEXT_PUBLIC_DOCS_ORIGIN) or current origin; stop hardcoding http://localhost:8104.

Apply:

-      const url = `http://localhost:8104/docs-embed/${docMapping.path}`;
+      const url = joinDocUrl(`/docs-embed/${docMapping.path}`);

-      const url = `http://localhost:8104/docs-embed/${platform}/getting-started/setup`;
+      const url = joinDocUrl(`/docs-embed/${platform}/getting-started/setup`);

-      const url = `http://localhost:8104/api-embed/overview`;
+      const url = joinDocUrl(`/api-embed/overview`);

Add near the top (after types):

+const DOCS_ORIGIN = process.env.NEXT_PUBLIC_DOCS_ORIGIN ?? '';
+const joinDocUrl = (p: string) => {
+  const base =
+    DOCS_ORIGIN.trim() ||
+    (typeof window !== 'undefined' ? window.location.origin : '');
+  return `${base.replace(/\/$/, '')}${p.startsWith('/') ? p : `/${p}`}`;
+};

---

241-255: Fix iframe reload fallback (no-op self-assign + Biome error).

Replace self-assign with cache-busting URL update to actually trigger reload.

-    } catch (error) {
-      // If we can't access iframe history, try to reload the previous page
-      // This is a fallback that at least resets the iframe
-      console.warn('Cannot access iframe history, reloading current page');
-      if (iframeRef) {
-        iframeRef.src = iframeRef.src;
-      }
-    }
+    } catch (error) {
+      console.warn('Cannot access iframe history, forcing reload via cache-buster');
+      if (iframeRef?.src) {
+        try {
+          const u = new URL(iframeRef.src, window.location.origin);
+          u.searchParams.set('_r', Date.now().toString());
+          setDocContent(prev => (prev ? { ...prev, url: u.toString() } : prev));
+        } catch {
+          setDocContent(prev => (prev ? { ...prev } : prev)); // react remount fallback
+        }
+      }
+    }

docs/src/components/layouts/docs.tsx (3)

110-124: Use Map accessors in the hook; expose stable tuple

If you adopt Map in the provider, read via get().

Apply this diff:

-export function useAccordionState(key: string, defaultValue: boolean) {
+export function useAccordionState(key: string, defaultValue: boolean) {
@@
-  const { accordionState, setAccordionState } = context;
-  const isOpen = accordionState[key] ?? defaultValue;
+  const { accordionState, setAccordionState } = context;
+  const isOpen = (accordionState instanceof Map
+    ? accordionState.get(key)
+    : // backward-compat if context not yet migrated
+      (accordionState as Record<string, boolean>)[key]) ?? defaultValue;

---

297-344: Use stable React keys; avoid index to prevent reorder bugs

Keys using index can cause state leakage on reordering. Prefer semantic keys.

Apply this diff:

-          {item.children.map((child, index) => (
-            <PageTreeItem key={child.type === 'page' ? child.url : index} item={child} currentPlatform={currentPlatform} />
-          ))}
+          {item.children.map((child) => (
+            <PageTreeItem
+              key={`${child.type}:${child.type === 'page' ? child.url : String(child.name ?? '')}`}
+              item={child}
+              currentPlatform={currentPlatform}
+            />
+          ))}
@@
-        {item.children.map((child, index) => (
-          <PageTreeItem key={child.type === 'page' ? child.url : index} item={child} currentPlatform={currentPlatform} />
-        ))}
+        {item.children.map((child) => (
+          <PageTreeItem
+            key={`${child.type}:${child.type === 'page' ? child.url : String(child.name ?? '')}`}
+            item={child}
+            currentPlatform={currentPlatform}
+          />
+        ))}

---

346-376: LGTM on making renderSidebarContent public; just one key nit

Approach looks good. Mirror the stable-key change here too.

Apply this diff:

-      {tree.children.map((item, index) => (
-        <PageTreeItem key={item.type === 'page' ? item.url : index} item={item} currentPlatform={currentPlatform} />
-      ))}
+      {tree.children.map((item) => (
+        <PageTreeItem
+          key={`${item.type}:${item.type === 'page' ? item.url : String(item.name ?? '')}`}
+          item={item}
+          currentPlatform={currentPlatform}
+        />
+      ))}

docs/src/app/docs-embed/[[...slug]]/page.tsx (1)

18-23: Consider 404 for unknown pages (optional)

Redirecting unknown slugs to overview can mask broken links. Using notFound() yields a proper 404.

Apply this diff:

-  if (!page) {
-    // Try to redirect to a sensible default if page not found
-    redirect('/docs-embed/next/overview');
-  }
+  if (!page) {
+    // Unknown page → 404 (keeps bad links visible)
+    // import { notFound } from 'next/navigation'
+    // notFound();
+    redirect('/docs-embed/next/overview');
+  }

docs/src/components/embedded-docs-with-sidebar.tsx (3)

24-34: Harden postMessage handling with a simple channel guard

Anyone can postMessage into the iframe; add a shared “source” token check (keeps cross-origin support without origin allowlists).

Apply this diff:

-  useEffect(() => {
+  useEffect(() => {
     const handleMessage = (event: MessageEvent) => {
-      if (event.data?.type === 'TOGGLE_SIDEBAR') {
+      if (event.data?.source === 'STACK_EMBED' && event.data?.type === 'TOGGLE_SIDEBAR') {
         setIsSidebarVisible(event.data.visible);
       }
     };

Parent should send: window.postMessage({ source: 'STACK_EMBED', type: 'TOGGLE_SIDEBAR', visible: true }, '*').

---

56-74: Add dialog semantics for accessibility on the Drawer

Mark the drawer as a modal dialog for AT users.

Apply this diff:

-                <div className="fixed left-0 top-0 bottom-0 w-[268px] z-50 bg-fd-background/95 backdrop-blur-md border-r border-fd-border shadow-lg">
+                <div
+                  className="fixed left-0 top-0 bottom-0 w-[268px] z-50 bg-fd-background/95 backdrop-blur-md border-r border-fd-border shadow-lg"
+                  role="dialog"
+                  aria-modal="true"
+                  aria-label="Documentation navigation"
+                >

---

11-15: Remove unused currentSlug prop (keeps API tight)

The prop isn’t used; drop it here and at the call site.

Apply this diff:

 type EmbeddedDocsWithSidebarProps = {
   pageTree: PageTree.Root,
-  currentSlug: string[],
   children: React.ReactNode,
 }
 
-export function EmbeddedDocsWithSidebar({ pageTree, currentSlug, children }: EmbeddedDocsWithSidebarProps) {
+export function EmbeddedDocsWithSidebar({ pageTree, children }: EmbeddedDocsWithSidebarProps) {

And in docs/src/app/docs-embed/[[...slug]]/page.tsx remove the prop:

-    <EmbeddedDocsWithSidebar
-      pageTree={source.pageTree}
-      currentSlug={slug}
-    >
+    <EmbeddedDocsWithSidebar pageTree={source.pageTree}>

Also applies to: 17-18

apps/dashboard/src/components/stack-companion/unified-docs-widget.tsx (5)

85-101: Prefer Map over Record for key–value collections (repo guideline).

Use Map and safe fallback for unknown pages.

-      const dashboardToDocsMap: Record<string, { path: string, title: string }> = {
-        'overview': { path: `${platform}/overview`, title: 'Stack Auth Overview' },
-        'users': { path: `${platform}/getting-started/users`, title: 'User Management' },
-        'auth-methods': { path: `${platform}/concepts/auth-providers`, title: 'Authentication Providers' },
-        'orgs-and-teams': { path: `${platform}/concepts/orgs-and-teams`, title: 'Teams & Organizations' },
-        'team-permissions': { path: `${platform}/concepts/permissions#team-permissions`, title: 'Team Permissions' },
-        'emails': { path: `${platform}/concepts/emails`, title: 'Emails' },
-        'domains': { path: `${platform}/getting-started/production#domains`, title: 'Domains' },
-        'webhooks': { path: `${platform}/concepts/webhooks`, title: 'Webhooks' },
-        'stack-auth-keys': { path: `${platform}/getting-started/setup#update-api-keys`, title: 'Stack Auth Keys' },
-        'project-settings': { path: `${platform}/getting-started/production#enabling-production-mode`, title: 'Project Configuration' },
-      };
-
-      const docMapping = dashboardToDocsMap[page];
+      const dashboardToDocsMap = new Map<string, { path: string; title: string }>([
+        ['overview', { path: `${platform}/overview`, title: 'Stack Auth Overview' }],
+        ['users', { path: `${platform}/getting-started/users`, title: 'User Management' }],
+        ['auth-methods', { path: `${platform}/concepts/auth-providers`, title: 'Authentication Providers' }],
+        ['orgs-and-teams', { path: `${platform}/concepts/orgs-and-teams`, title: 'Teams & Organizations' }],
+        ['team-permissions', { path: `${platform}/concepts/permissions#team-permissions`, title: 'Team Permissions' }],
+        ['emails', { path: `${platform}/concepts/emails`, title: 'Emails' }],
+        ['domains', { path: `${platform}/getting-started/production#domains`, title: 'Domains' }],
+        ['webhooks', { path: `${platform}/concepts/webhooks`, title: 'Webhooks' }],
+        ['stack-auth-keys', { path: `${platform}/getting-started/setup#update-api-keys`, title: 'Stack Auth Keys' }],
+        ['project-settings', { path: `${platform}/getting-started/production#enabling-production-mode`, title: 'Project Configuration' }],
+      ]);
+
+      const docMapping =
+        dashboardToDocsMap.get(page) ?? dashboardToDocsMap.get('overview')!;

---

136-147: Reset back-button state on new loads.

Avoid stale “Back” visibility after reloads.

         setLoading(true);
         setError(null);
         setIframeLoaded(false);
+        setCanGoBack(false);
         setCurrentPageDoc(newPageDoc);

---

149-158: Guard debug logs for production.

Keep console noise out of prod.

-          console.log('Debug mapping:', {
+          if (process.env.NODE_ENV !== 'production') console.log('Debug mapping:', {
             pathname,
             normalizedPath: pathname.replace(/^\/projects\/[^/]+/, ''),
             detectedPage: page,
             platform: selectedPlatform
           });
-          const content = getDocContentForPath(pathname, selectedDocType, selectedPlatform);
-          console.log('Loading docs:', { page, platform: selectedPlatform, url: content.url });
+          const content = getDocContentForPath(pathname, selectedDocType, selectedPlatform);
+          if (process.env.NODE_ENV !== 'production') console.log('Loading docs:', { page, platform: selectedPlatform, url: content.url });

---

149-149: Avoid recomputing getDashboardPage.

Use the already computed value.

-          const page = getDashboardPage(pathname);
+          const page = newPageDoc;

---

224-230: Hide sidebar in the embed when switching doc types.

Mirror local state to the iframe.

       setSelectedDocType(docType);
       setShowSwitchPrompt(false);
       setIsSidebarVisible(false); // Hide sidebar when switching doc types
+      if (iframeRef) toggleEmbeddedSidebar(iframeRef, false);

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

docs/src/components/embedded-link-interceptor.tsx (2)

92-99: Consider making URL existence check optional via feature flag.

The checkUrlExists HEAD request is now non-blocking (navigation proceeds regardless), but still adds latency and can fail on hosts that return 405/308 for HEAD. Since multiple previous reviewers flagged HEAD requests as unreliable and the check is purely advisory, consider gating it behind an environment variable (e.g., NEXT_PUBLIC_ENABLE_LINK_VALIDATION) or removing it entirely.

Apply this diff to gate the check behind a feature flag:

+const ENABLE_LINK_VALIDATION = process.env.NEXT_PUBLIC_ENABLE_LINK_VALIDATION === 'true';
+
 export function EmbeddedLinkInterceptor() {
   const router = useRouter();
 
   // Function to check if a URL exists
   const checkUrlExists = useCallback(async (url: string): Promise<boolean> => {
+    if (!ENABLE_LINK_VALIDATION) return true;
     try {
       const response = await fetch(url, { method: 'HEAD' });
       return response.ok;

---

131-144: Optionally prevent duplicate in-flight navigations.

Rapid repeated clicks on the same link will queue multiple navigations. While router.push should handle this gracefully, you could add deduplication by tracking in-flight URLs to improve UX consistency.

Apply this diff to add deduplication:

   useEffect(() => {
+    const inFlightUrls = new Set<string>();
+
     const handleClick = (event: MouseEvent) => {
       if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
         return;
       }
 
       const target = event.target as HTMLElement;
 
       // Find the closest anchor tag
       const anchor = target.closest('a');
       if (!anchor) return;
 
       const href = anchor.getAttribute('href');
       if (!href) return;
 
       if (anchor.target === '_blank' || anchor.hasAttribute('download')) {
         return;
       }
 
       if (href.startsWith('javascript:') || href.startsWith('data:') || href.startsWith('blob:')) {
         return;
       }
 
       // Intercept internal links that need to be rewritten OR relative links
       if (
         href.startsWith('/docs/') ||
         href.startsWith('/api/') ||
         href.startsWith('/dashboard/') ||
         (!/^[a-zA-Z][a-zA-Z+\-.]*:/.test(href) && !href.startsWith('#'))
       ) {
         event.preventDefault();
 
         const currentPath = window.location.pathname;
         const embeddedHref = getEmbeddedUrl(href, currentPath);
+        
+        if (inFlightUrls.has(embeddedHref)) {
+          return; // Skip if already navigating to this URL
+        }
+        
         const navigate = () => router.push(embeddedHref);
 
         // Check if the URL exists before navigating (async operation)
         runAsynchronously(async () => {
+          inFlightUrls.add(embeddedHref);
+          try {
             const urlExists = await checkUrlExists(embeddedHref);
             if (!urlExists) {
               console.warn(`Embedded link not found, navigating anyway: ${embeddedHref}`);
             }
             navigate();
+          } finally {
+            inFlightUrls.delete(embeddedHref);
+          }
         });
       }
     };

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: stack-auth/stack-auth#0
File: AGENTS.md:0-0
Timestamp: 2025-10-20T22:25:40.427Z
Learning: Applies to apps/{dashboard,dev-launchpad}/**/*.{css,tsx,jsx} : Animations: keep hover/click transitions snappy; do not delay actions with pre-hover transitions; apply transitions after the action (e.g., fade-out on hover end)