Docs Site

apps/docs is the standalone documentation application for SterlingIndex. It is a Next.js App Router app built on Fumadocs, deployed on the dedicated docs host, and intentionally kept separate from the marketing site even though both are public, unauthenticated surfaces.

The app is documentation-heavy and runtime-light. It renders mostly static MDX content, keeps its own shell and metadata contract, and now exposes the same shared dashboard sign-in handoff used by the marketing surface.

System Role

• Primary purpose: publish engineering-facing architecture, deployment, and contract documentation at docs.<domain>.
• Runtime boundary: the app owns the docs shell, page tree, metadata, and search route, but defers authenticated product access to the shared dashboard sign-in handoff from @sterling/auth.
• Deployment assumption: the app deploys independently on Vercel, serves https://docs.<domain>/docs, and does not inherit the marketing site's route tree or shell primitives.

docs.<domain>/
  -> src/app/layout.tsx
      -> Fumadocs RootProvider
      -> docs route tree
      -> top-nav login button
      -> sidebar login CTA

Route Structure

Shell and Layout Model

The global shell lives in apps/docs/src/app/layout.tsx.

• It publishes the docs metadataBase, title template, Open Graph metadata, and Twitter metadata through apps/docs/src/lib/site.ts.
• It injects Google-hosted Mona Sans and Inter, matching the rest of the repo's public surfaces.
• It mounts RootProvider from fumadocs-ui/provider/next, not the marketing shell from apps/www.

The docs section layout lives in apps/docs/src/app/docs/layout.tsx.

• It renders DocsLayout from fumadocs-ui/layouts/docs.
• It sources the page tree from apps/docs/src/lib/source.ts.
• It applies repo-specific layout options from apps/docs/src/lib/layout-options.tsx.

Shared Login Handoff

The docs app now uses the same shared auth contract as the other public and operator-facing surfaces.

• apps/docs/src/lib/layout-options.tsx imports normalizeBaseUrl() and buildDashboardLoginHref() from @sterling/auth.
• It derives DOCS_LOGIN_HREF from NEXT_PUBLIC_DASHBOARD_URL, with a local fallback of http://localhost:8080.
• The top navigation renders a visible Log in button through the Fumadocs links config.
• The docs sidebar renders a persistent footer CTA that points to the same dashboard sign-in handoff contract.

This means the docs app stays public and documentation-focused, but it still provides a clear escape hatch into the authenticated product.

Content and Generation Model

The content source is the MDX tree under apps/docs/content/docs.

• apps/docs/src/lib/source.ts converts the MDX collection into a Fumadocs source.
• apps/docs/src/app/docs/[[...slug]]/page.tsx reads the matching page, renders the MDX body, and exports static params for build-time generation.
• generateMetadata() attaches per-page title, description, and canonical path values.

Because the page tree is generated at build time, the docs app is mostly deterministic:

• there is no live CMS dependency,
• the route surface is tied directly to checked-in MDX files,
• the login CTA is the only notable cross-app runtime handoff in the shell.

Runtime Environment Inputs

The checked-in docs runtime contract now includes:

• NEXT_PUBLIC_DOCS_BASE_URL for the docs metadata and canonical origin
• NEXT_PUBLIC_DASHBOARD_URL for the shared dashboard-login handoff
• APP_PUBLIC_DOCS_URL as a fallback name supported by apps/docs/src/lib/site.ts

These values are documented in apps/docs/.env.example and mirrored into the shared local/prod examples under infra/.

Deployment and Verification

The docs app is expected to deploy independently on Vercel.

• package metadata: apps/docs/package.json
• Next config: apps/docs/next.config.ts
• app shell: apps/docs/src/app/layout.tsx
• layout options and shared login CTA: apps/docs/src/lib/layout-options.tsx

Verification surface:

• pnpm --dir apps/docs build
• pnpm --dir apps/docs typecheck
• pnpm --dir apps/docs lint

Manual smoke checks should confirm:

• / redirects to /docs
• the top-nav Log in button lands on the dashboard sign-in handoff URL
• the sidebar footer CTA lands on the same dashboard sign-in handoff URL
• canonicals and metadata point at docs.<domain>

Key Files

• apps/docs/package.json
• apps/docs/next.config.ts
• apps/docs/src/app/layout.tsx
• apps/docs/src/app/page.tsx
• apps/docs/src/app/docs/layout.tsx
• apps/docs/src/app/docs/[[...slug]]/page.tsx
• apps/docs/src/lib/site.ts
• apps/docs/src/lib/source.ts
• apps/docs/src/lib/layout-options.tsx
• packages/auth/src/index.ts