Streamlined site-to-site docs in new dedicated section. Removed old u… (#585)

* Streamlined site-to-site docs in new dedicated section. Removed old use-case guide and added redirects

* restructure use-cases, move network use cases to network sections

* Reorganize network routes and networks documentation structure

- Restructure use cases into by-scenario and by-configuration folders
- Reorganize images to match new doc structure (concepts, by-scenario, by-resource-type)
- Add screenshots for site-to-site guides (home, office, cloud)
- Add policy screenshots for networks use cases
- Update site-to-site docs to use two separate policies instead of bidirectional
- Fix Access Control Groups to use correct destination groups
- Move "Self-Hosted vs Cloud" page to about section
- Update navigation and add redirects for moved pages
- Add CLAUDE.md for Claude Code guidance

* cleaned up network docs/image folder structure

* Align site-to-site use case links and redirects

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update CLAUDE.md with accurate project details

Fix Next.js version (14 → 16), add React 19/Tailwind/Pages Router
details, document MDX page conventions, image paths, and note
absence of test suite.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix broken images and hydration error on networks page

- Restore 6 network index images accidentally deleted in 4116092
- Fix keycloak image filename typo (keycloack -> keycloak)
- Fix hydration mismatch by replacing invalid <p><div> nesting with <div>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix 4 broken internal links found in PR review

- Fix missing by-scenario/ segment in site-to-site-home and
  site-to-site-office Tile hrefs (network-routes use-cases index)
- Fix lazy-connections typo to lazy-connection (implement-zero-trust)
- Update stale redirect link to direct path for access-control

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3.
+
+There is no test suite in this project. Validate changes with `npm run build`.
+
+## Common Commands
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Start dev server (also runs gen:llm)
+npm run build        # Production build (also runs gen:llm)
+npm run lint         # ESLint (next/core-web-vitals) on src/
+npm run gen          # Regenerate API docs from NetBird OpenAPI spec
+npm run gen:llm      # Regenerate LLM-friendly markdown (auto-runs with dev/build)
+```
+
+## Architecture
+
+### Content Structure
+Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router (not App Router). Key directories:
+- `about-netbird/` - Conceptual docs
+- `get-started/` - Installation and quickstart guides
+- `manage/` - Feature documentation (peers, networks, DNS, access control, etc.)
+- `selfhosted/` - Self-hosting deployment guides
+- `ipa/` - API documentation (served at `/api` via rewrite)
+- `use-cases/` - Tutorials and examples
+- `client/` - Client configuration
+- `help/` - Troubleshooting
+
+### MDX Page Conventions
+- Page title comes from the first `# Heading` in the MDX file
+- Optional `export const description = '...'` for meta description
+- Import components as needed: `import {Note} from "@/components/mdx"`
+- Images go in `public/docs-static/img/<section>/` and are referenced as `/docs-static/img/<section>/filename.png`
+
+### Navigation
+`src/components/NavigationDocs.jsx` contains the `docsNavigation` array defining the sidebar. **Must be updated when adding or moving pages.** Supports nested `links` arrays for sub-navigation.
+
+### MDX Components
+Custom components available in MDX files (see `README.md` for full usage examples):
+- Alert boxes: `<Note>`, `<Warning>`, `<Success>` (from `@/components/mdx`)
+- Layout: `<Row>`, `<Col>`, `<Tiles>` (from `@/components/Tiles`), `<CodeGroup>`
+- Media: `<YouTube videoId="...">` (from `@/components/YouTube`)
+- UI: `<Button>` (from `@/components/Button`), `<Badge>`
+- API docs: `<Properties>`, `<Property>`
+
+### API Documentation Generator
+- `generator/` - TypeScript generator that creates MDX pages from the NetBird OpenAPI spec
+- `generator/templates/ApiTemplate.ts` - Template for generated pages
+- Output: `src/pages/ipa/resources/` (don't edit these files manually)
+
+### MDX Processing Pipeline
+- `mdx/remark.mjs` - Remark plugins
+- `mdx/rehype.mjs` - Rehype plugins (syntax highlighting via Shiki)
+- `mdx/recma.mjs` - Recma plugins
+
+### LLM Documentation
+- `scripts/generate-llm-docs.mjs` generates clean markdown to `public/llms/` (gitignored)
+- Runs automatically with `dev` and `build`
+
+## URL Routing
+
+- Root `/` rewrites to `/introduction`
+- `/api/*` rewrites to `/ipa/*` (API docs live in `src/pages/ipa/` but are served under `/api`)
+- Extensive legacy redirects from `/docs/*` and `/how-to/*` paths in `next.config.mjs`

next.config.mjs

@@ -58,7 +58,7 @@ const nextConfig = {
             },
             {
                 source: '/docs/how-to-guides/network-routes',
-                destination: '/manage/network-routes/routing-traffic-to-private-networks',
+                destination: '/manage/network-routes',
                 permanent: true,
             },
             {
@@ -96,6 +96,12 @@ const nextConfig = {
                 destination: '/api/:path*',
                 permanent: true
             },
+            // documentation redirects for about
+            {
+                source: '/selfhosted/self-hosted-vs-cloud-netbird',
+                destination: '/about-netbird/self-hosted-vs-cloud',
+                permanent: true,
+            },
             // documentation redirects for access control
             {
                 source: '/how-to/manage-network-access',
@@ -252,27 +258,27 @@ const nextConfig = {
             // documentation redirects for use-cases
             {
                 source: '/how-to/examples',
-                destination: '/use-cases/examples',
+                destination: '/use-cases/cloud/aws-ecs-terraform',
                 permanent: true,
             },
             {
                 source: '/how-to/netbird-on-faas',
-                destination: '/use-cases/netbird-on-faas',
+                destination: '/use-cases/cloud/netbird-on-faas',
                 permanent: true,
             },
             {
                 source: '/how-to/routing-peers-and-kubernetes',
-                destination: '/use-cases/routing-peers-and-kubernetes',
+                destination: '/use-cases/cloud/routing-peers-and-kubernetes',
                 permanent: true,
             },
             {
                 source: '/how-to/client-on-mikrotik-router',
-                destination: '/use-cases/client-on-mikrotik-router',
+                destination: '/use-cases/homelab/client-on-mikrotik-router',
                 permanent: true,
             },
             {
                 source: '/how-to/distributed-multi-cloud-ai-argocd-microk8s-vllm',
-                destination: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm',
+                destination: '/use-cases/cloud/distributed-multi-cloud-ai',
                 permanent: true,
             },
             // documentation redirects for networks
@@ -304,7 +310,7 @@ const nextConfig = {
             // documentation redirects for network-routes
             {
                 source: '/how-to/routing-traffic-to-private-networks',
-                destination: '/manage/network-routes/routing-traffic-to-private-networks',
+                destination: '/manage/network-routes',
                 permanent: true,
             },
             {
@@ -510,6 +516,126 @@ const nextConfig = {
                 destination: '/manage/dns/custom-zones',
                 permanent: true,
             },
+            // Site-to-site documentation restructure redirects
+            {
+                source: '/use-cases/setup-site-to-site-access',
+                destination: '/use-cases/site-to-site',
+                permanent: true,
+            },
+            {
+                source: '/manage/peers/site-to-site/db-workload-migration',
+                destination: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
+                permanent: true,
+            },
+            {
+                source: '/manage/network-routes/use-cases/site-to-site-cloud',
+                destination: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
+                permanent: true,
+            },
+            {
+                source: '/manage/networks/homelab/access-home-network',
+                destination: '/manage/networks/use-cases/by-scenario/access-home-devices',
+                permanent: true,
+            },
+            // Networks guides moved to use-cases
+            {
+                source: '/manage/networks/routing-traffic-to-multiple-resources',
+                destination: '/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources',
+                permanent: true,
+            },
+            {
+                source: '/manage/networks/accessing-restricted-domain-resources',
+                destination: '/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources',
+                permanent: true,
+            },
+            {
+                source: '/manage/networks/accessing-entire-domains-within-networks',
+                destination: '/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks',
+                permanent: true,
+            },
+            // Network Routes guides moved to use-cases
+            {
+                source: '/manage/network-routes/routing-traffic-to-private-networks',
+                destination: '/manage/network-routes',
+                permanent: true,
+            },
+            {
+                source: '/manage/network-routes/use-cases/routing-traffic-to-private-networks',
+                destination: '/manage/network-routes',
+                permanent: true,
+            },
+            {
+                source: '/manage/network-routes/configuring-default-routes-for-internet-traffic',
+                destination: '/manage/network-routes/use-cases/by-scenario/exit-nodes',
+                permanent: true,
+            },
+            {
+                source: '/manage/network-routes/configuring-routes-with-access-control',
+                destination: '/manage/network-routes/use-cases/by-configuration/access-control',
+                permanent: true,
+            },
+            {
+                source: '/manage/network-routes/resolve-overlapping-routes',
+                destination: '/manage/network-routes/use-cases/by-configuration/overlapping-routes',
+                permanent: true,
+            },
+            // Site-to-Site section redirects (overview and comprehensive guides)
+            {
+                source: '/manage/site-to-site',
+                destination: '/use-cases/site-to-site',
+                permanent: true,
+            },
+            {
+                source: '/manage/site-to-site/connect-home-networks',
+                destination: '/use-cases/site-to-site',
+                permanent: true,
+            },
+            {
+                source: '/manage/site-to-site/connect-office-networks',
+                destination: '/use-cases/site-to-site',
+                permanent: true,
+            },
+            {
+                source: '/manage/site-to-site/connect-cloud-environments',
+                destination: '/use-cases/site-to-site',
+                permanent: true,
+            },
+            {
+                source: '/manage/site-to-site/advanced-configuration',
+                destination: '/manage/network-routes/use-cases/by-configuration/advanced-configuration',
+                permanent: true,
+            },
+            // Use-cases flat pages -> categorized
+            {
+                source: '/use-cases/examples',
+                destination: '/use-cases/cloud/aws-ecs-terraform',
+                permanent: true,
+            },
+            {
+                source: '/use-cases/netbird-on-faas',
+                destination: '/use-cases/cloud/netbird-on-faas',
+                permanent: true,
+            },
+            {
+                source: '/use-cases/routing-peers-and-kubernetes',
+                destination: '/use-cases/cloud/routing-peers-and-kubernetes',
+                permanent: true,
+            },
+            {
+                source: '/use-cases/implement-zero-trust',
+                destination: '/use-cases/security/implement-zero-trust',
+                permanent: true,
+            },
+            {
+                source: '/use-cases/client-on-mikrotik-router',
+                destination: '/use-cases/homelab/client-on-mikrotik-router',
+                permanent: true,
+            },
+            {
+                source: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm',
+                destination: '/use-cases/cloud/distributed-multi-cloud-ai',
+                permanent: true,
+            },
         ]
     },
     rewrites: async () => {