Navigation cleanup: MDM deployment under Peers, purge stale tutorials, MSP portal refresh (#906)

* docs: move MDM deployment guides under Manage > Peers

The five fleet-deployment guides (GPO, macOS .pkg, Jamf Pro, Kandji,
Intune) lived under Integrations, but nothing in them integrates with
NetBird's platform — they are peer onboarding at scale, which lives
under Peers. The label also collided with Access Control's
'Integrate MDM & EDR', which uses MDM in the opposite sense.

- Move pages from /manage/integrations/mdm-deployment/ to
  /manage/peers/mdm-deployment/ with a permanent wildcard redirect
- Re-point legacy /how-to redirects directly at the new paths
- Move the nav group under Peers as 'MDM Deployment'; remove the
  now-empty Integrations group
- Update internal links

* docs: link full GPO deployment guide from MDM integration page

* docs: show setup-key secret wiring and replica naming for k8s routing peers

Fold the two verified-novel bits from the Access Infrastructure
autoscaling tutorial before purging it:

- Replace the 'use a secret' Note with the actual kubectl create
  secret + secretKeyRef wiring (matches what the NetBird operator
  injects for routing peers)
- In the HA section, note that removing the static NB_HOSTNAME lets
  each replica register under its pod name (client falls back to
  os.Hostname(), which is the pod name in Kubernetes)

* docs: purge redundant Access Infrastructure tutorials

The four pages under Manage > Peers > Access Infrastructure were
2024-era SEO tutorials that duplicated canonical feature docs and
carried outdated claims (pre-rewrite SSH model without the built-in
SSH server, a Docker section that never actually enrolls the
container with a setup key, CrowdStrike presented as the only EDR
integration, stale v0.29 output and vintage-UI screenshots).

Cross-checked each page against its canonical counterpart; nothing
novel remained (the two useful Kubernetes snippets were folded into
the routing-peers use case in the previous commit).

- Delete the four pages and their screenshot directory
- Remove the Access Infrastructure nav group
- Redirect each URL to its canonical replacement:
  secure-remote-webserver-access -> /manage/peers/ssh
  setup-keys-add-servers-to-network -> /manage/peers/register-machines-using-setup-keys
  access-internal-resources-from-autoscaled-environments -> /use-cases/kubernetes
  peer-approval-for-remote-worker-access -> /manage/peers/approve-peers
- Re-point the legacy /how-to redirects at the same targets to avoid
  redirect chains

* docs: reorder Peers nav into enrollment, approval, day-2 flow

Group the five enrollment methods first (Add Peers, Setup Keys,
Bootstrap via Config File, MDM Deployment, Browser Client), then the
Approve Peers admission gate, then running-peer features (SSH, Lazy
Connections, Remote Jobs) and Auto Update last. Approve Peers
previously sat between two enrollment pages.

* docs: cross-link DNS aliases and internal DNS pages, fix tutorial inaccuracies

The two pages solve adjacent problems (NetBird-hosted records vs
forwarding to existing internal DNS) but never pointed at each other.
Add a which-page-do-I-need Note to each.

Also fix defects in the DNS Aliases tutorial found while cross-checking
it against the Custom Zones reference and dashboard source:

- 'Keep this enabled' implied search domain is on by default; it is
  off by default (DNSZoneModal.tsx: enable_search_domain ?? false)
- Step 3 said 'wildcard resource' but the steps add exact-name domain
  resources
- Wrong alt text ('Delete DNS Zone') on the zone-config screenshot
- Add missing meta description and a link to the Custom Zones
  reference

* docs: align MSP portal page with 2026 partner program, rename For Partners nav

Cross-checked the MSP portal page against the 2026 MSP/MSSP Partner
Program document:

- Point the application link at netbird.io/use-cases/msp (the program's
  canonical page) instead of a demo-form URL displayed as netbird.io/msp
- State tenant plan options (Team or Business) and the post-trial
  minimum (Team plan with one user)
- Mention CSV/PDF usage export alongside the API
- Clarify the 3-day trial for existing accounts brought in as tenants:
  it is a window to subscribe the tenant under the MSP account
- Add a subtle msp@netbird.io contact line at the bottom

Also rename the For Partners nav entries by deliverable instead of
audience (the section header already says who it's for): MSP Portal,
Distributor Portal, Deploy with Acronis.

* docs: update CLAUDE.md for agent-network, proxy.js, and tooling gaps

Audited every claim against the current repo. Stack, routing, security,
and convention claims all still hold; four gaps had accumulated:

- Add agent-network/ to the content structure list
- Document src/proxy.js in URL Routing: /api data requests must be
  rewritten there because the config rewrite loses data-request context
  on client-side navigation (Next.js #39669) and strips pageProps
- Add npm run lint:mdx; note npm run gen requires a Go toolchain
- Note fenced mermaid code blocks render as diagrams

* docs: address review findings on PR #906

- Move the MDM deployment screenshot directories to match the new page
  paths; the URL rewrite had updated MDX image references without
  moving the assets, breaking all Intune/Jamf/Kandji images
- Normalize pre-existing double slashes in Jamf and Kandji image URLs
- Align the routing-peers secret example with bootstrap-via-config-file
  (same secret name, so both now use the NB_SETUP_KEY data key)
- DNS aliases: include the routing peer's group in the zone's
  distribution groups. Verified in client source: the DNS route
  interceptor (priority 100) outranks local zone records (priority 75)
  and never falls through, so clients forward routed-domain queries to
  the routing peer, which must receive the zone to answer

CLAUDE.md

@@ -18,7 +18,8 @@ npm run dev              # Start dev server (also runs gen:edit-routes, gen:last
 npm run build            # Production build (also runs gen:edit-routes, gen:last-updated, gen:sitemap)
 npm run start            # Serve the production build (warns under `output: 'standalone'` — safe to ignore locally; prod runs `node server.js` from `.next/standalone`)
 npm run lint             # ESLint (next/core-web-vitals) on src/
-npm run gen              # Regenerate API docs from NetBird OpenAPI spec
+npm run lint:mdx         # Check MDX heading structure (scripts/lint-mdx-headings.mjs)
+npm run gen              # Regenerate API docs from NetBird OpenAPI spec (requires a Go toolchain: runs `go run .` in generator/ to expand the spec)
 npm run gen:edit-routes  # Regenerate edit-on-GitHub routes (auto-runs with dev/build)
 npm run gen:last-updated # Regenerate per-page git last-modified dates (auto-runs with dev/build)
 npm run gen:sitemap      # Regenerate public/sitemap.xml (auto-runs with dev/build)
@@ -42,6 +43,7 @@ Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router
 - `ipa/` - API documentation (served at `/api` via rewrite)
 - `use-cases/` - Tutorials and examples
 - `client/` - Client configuration
+- `agent-network/` - Agent Network product docs (AI/LLM gateway: quickstart, policies, usage & logs, integrations)
 - `help/` - Troubleshooting
 
 ### MDX Page Conventions
@@ -64,6 +66,7 @@ Custom components available in MDX files (see `README.md` for full usage example
 - Media: `<YouTube videoId="...">` (from `@/components/YouTube`)
 - UI: `<Button>` (from `@/components/Button`), `<Badge>`
 - API docs: `<Properties>`, `<Property>`
+- Diagrams: fenced ```mermaid code blocks render as Mermaid diagrams (via `src/components/Mermaid.jsx`)
 
 ### API Documentation Generator
 - `generator/` - TypeScript generator that creates MDX pages from the NetBird OpenAPI spec
@@ -86,4 +89,5 @@ They are imported at build time (e.g. by `mdx/rehype.mjs`). On a fresh clone, ru
 
 - Root `/` rewrites to `/introduction`
 - `/api/*` rewrites to `/ipa/*` (API docs live in `src/pages/ipa/` but are served under `/api`)
+- `src/proxy.js` additionally rewrites `/api` **data requests** (`x-nextjs-data` header / `/_next/data/...` paths) to `/ipa`. The config rewrite loses data-request context on client-side navigation (Next.js issue #39669), which strips pageProps — don't remove or bypass the proxy when touching `/api` routing, and test client-side nav to `/api` pages after any change here.
 - Extensive legacy redirects from `/docs/*` and `/how-to/*` paths in `next.config.mjs`

next.config.mjs

@@ -260,22 +260,22 @@ const nextConfig = {
             },
             {
                 source: '/how-to/secure-remote-webserver-access',
-                destination: '/manage/peers/access-infrastructure/secure-remote-webserver-access',
+                destination: '/manage/peers/ssh',
                 permanent: true,
             },
             {
                 source: '/how-to/setup-keys-add-servers-to-network',
-                destination: '/manage/peers/access-infrastructure/setup-keys-add-servers-to-network',
+                destination: '/manage/peers/register-machines-using-setup-keys',
                 permanent: true,
             },
             {
                 source: '/how-to/access-internal-resources-from-autoscaled-environments',
-                destination: '/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments',
+                destination: '/use-cases/kubernetes',
                 permanent: true,
             },
             {
                 source: '/how-to/peer-approval-for-remote-worker-access',
-                destination: '/manage/peers/access-infrastructure/peer-approval-for-remote-worker-access',
+                destination: '/manage/peers/approve-peers',
                 permanent: true,
             },
             {
@@ -495,19 +495,44 @@ const nextConfig = {
                 destination: '/client/post-quantum-cryptography',
                 permanent: true,
             },
+            {
+                source: '/manage/peers/access-infrastructure/secure-remote-webserver-access',
+                destination: '/manage/peers/ssh',
+                permanent: true,
+            },
+            {
+                source: '/manage/peers/access-infrastructure/setup-keys-add-servers-to-network',
+                destination: '/manage/peers/register-machines-using-setup-keys',
+                permanent: true,
+            },
+            {
+                source: '/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments',
+                destination: '/use-cases/kubernetes',
+                permanent: true,
+            },
+            {
+                source: '/manage/peers/access-infrastructure/peer-approval-for-remote-worker-access',
+                destination: '/manage/peers/approve-peers',
+                permanent: true,
+            },
+            {
+                source: '/manage/integrations/mdm-deployment/:path*',
+                destination: '/manage/peers/mdm-deployment/:path*',
+                permanent: true,
+            },
             {
                 source: '/how-to/jamf-pro-netbird-integration',
-                destination: '/manage/integrations/mdm-deployment/jamf-pro-netbird-integration',
+                destination: '/manage/peers/mdm-deployment/jamf-pro-netbird-integration',
                 permanent: true,
             },
             {
                 source: '/how-to/kandji-netbird-integration',
-                destination: '/manage/integrations/mdm-deployment/kandji-netbird-integration',
+                destination: '/manage/peers/mdm-deployment/kandji-netbird-integration',
                 permanent: true,
             },
             {
                 source: '/how-to/intune-netbird-integration',
-                destination: '/manage/integrations/mdm-deployment/intune-netbird-integration',
+                destination: '/manage/peers/mdm-deployment/intune-netbird-integration',
                 permanent: true,
             },
             {

src/components/NavigationDocs.jsx

@@ -90,7 +90,6 @@ export const docsNavigation = [
                         title: 'Add Peers',
                         href: '/manage/peers/add-machines-to-your-network',
                     },
-                    { title: 'Approve Peers', href: '/manage/peers/approve-peers' },
                     {
                         title: 'Setup Keys',
                         href: '/manage/peers/register-machines-using-setup-keys',
@@ -99,6 +98,32 @@ export const docsNavigation = [
                         title: 'Bootstrap via Config File',
                         href: '/manage/peers/bootstrap-via-config-file',
                     },
+                    {
+                        title: 'MDM Deployment',
+                        isOpen: false,
+                        links: [
+                            {
+                                title: 'Deploy with Group Policy (GPO)',
+                                href: '/manage/peers/mdm-deployment/windows-gpo-deployment',
+                            },
+                            {
+                                title: 'macOS CLI-Only .pkg',
+                                href: '/manage/peers/mdm-deployment/macos-cli-pkg-deployment',
+                            },
+                            {
+                                title: 'Deploy with Jamf Pro',
+                                href: '/manage/peers/mdm-deployment/jamf-pro-netbird-integration',
+                            },
+                            {
+                                title: 'Deploy with Kandji',
+                                href: '/manage/peers/mdm-deployment/kandji-netbird-integration',
+                            },
+                            {
+                                title: 'Deploy with Intune',
+                                href: '/manage/peers/mdm-deployment/intune-netbird-integration',
+                            },
+                        ],
+                    },
                     {
                         title: 'Browser Client',
                         isOpen: false,
@@ -110,31 +135,10 @@ export const docsNavigation = [
                             },
                         ],
                     },
+                    { title: 'Approve Peers', href: '/manage/peers/approve-peers' },
                     { title: 'SSH', href: '/manage/peers/ssh' },
                     { title: 'Lazy Connections', href: '/manage/peers/lazy-connection' },
                     { title: 'Remote Jobs', href: '/manage/peers/remote-jobs' },
-                    {
-                        title: 'Access Infrastructure',
-                        isOpen: true,
-                        links: [
-                            {
-                                title: 'Access Remote Webserver',
-                                href: '/manage/peers/access-infrastructure/secure-remote-webserver-access',
-                            },
-                            {
-                                title: 'Add Servers to the Network',
-                                href: '/manage/peers/access-infrastructure/setup-keys-add-servers-to-network',
-                            },
-                            {
-                                title: 'Access from Kubernetes',
-                                href: '/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments',
-                            },
-                            {
-                                title: 'Peer Approval for Remote Access',
-                                href: '/manage/peers/access-infrastructure/peer-approval-for-remote-worker-access',
-                            },
-                        ],
-                    },
                     { title: 'Auto Update', href: '/manage/peers/auto-update' },
                 ],
             },
@@ -418,39 +422,6 @@ export const docsNavigation = [
                     { title: 'Delete Account', href: '/manage/settings/delete-account' },
                 ],
             },
-            {
-                title: 'Integrations',
-                isOpen: false,
-                links: [
-                    {
-                        title: 'MDM for Deployment',
-                        isOpen: true,
-                        links: [
-                            {
-                                title: 'Deploy with Group Policy (GPO)',
-                                href: '/manage/integrations/mdm-deployment/windows-gpo-deployment',
-                            },
-                            {
-                                title: 'macOS CLI-Only .pkg',
-                                href: '/manage/integrations/mdm-deployment/macos-cli-pkg-deployment',
-                            },
-                            {
-                                title: 'Deploy with Jamf Pro',
-                                href: '/manage/integrations/mdm-deployment/jamf-pro-netbird-integration',
-                            },
-                            {
-                                title: 'Deploy with Kandji',
-                                href: '/manage/integrations/mdm-deployment/kandji-netbird-integration',
-                            },
-                            {
-                                title: 'Deploy with Intune',
-                                href: '/manage/integrations/mdm-deployment/intune-netbird-integration',
-                            },
-                        ],
-                    },
-                ],
-            },
-
             {
                 title: 'Public API',
                 isOpen: false,
@@ -461,15 +432,15 @@ export const docsNavigation = [
                 isOpen: false,
                 links: [
                     {
-                        title: 'Managed Service Providers',
+                        title: 'MSP Portal',
                         href: '/manage/for-partners/msp-portal',
                     },
                     {
-                        title: 'Distributors',
+                        title: 'Distributor Portal',
                         href: '/manage/for-partners/distributor-portal',
                     },
                     {
-                        title: 'Acronis NetBird integration',
+                        title: 'Deploy with Acronis',
                         href: '/manage/for-partners/acronis-integration',
                     },
                 ],

src/pages/client/desktop-app.mdx

@@ -94,7 +94,7 @@ The settings page uses a tabbed layout that groups options by what they control.
 
 ## MDM-Driven UI
 
-If you roll out NetBird through MDM, the app reads the policy in effect on the device and adjusts itself to match, so users only see the options they are allowed to use. For deploying NetBird through an MDM provider, see the [MDM deployment guides](/manage/integrations/mdm-deployment/intune-netbird-integration).
+If you roll out NetBird through MDM, the app reads the policy in effect on the device and adjusts itself to match, so users only see the options they are allowed to use. For deploying NetBird through an MDM provider, see the [MDM deployment guides](/manage/peers/mdm-deployment/intune-netbird-integration).
 
 * **Hide whole views.** `disableAdvancedView` hides the Advanced view of the main window, so managed users only see the compact one.
 * **Gate specific capabilities.** Keys such as `allowServerSSH` control whether the corresponding toggle is available in the app.

src/pages/client/mdm-integration.mdx

@@ -125,6 +125,8 @@ same registry key.
 
 ### Group Policy (on-prem AD / local gpedit)
 
+For a full end-to-end walkthrough — domain Central Store, GPO creation, silent MSI install, and troubleshooting — see [Deploying NetBird with Group Policy (GPO)](/manage/peers/mdm-deployment/windows-gpo-deployment). The steps below cover the minimal local setup.
+
 1. Copy the ADMX/ADML files into the system Policy Definitions store:
    - Place `netbird.admx` in `C:\Windows\PolicyDefinitions\`.
    - Place `netbird.adml` in `C:\Windows\PolicyDefinitions\en-US\`.

src/pages/get-started/install/macos.mdx

@@ -56,7 +56,7 @@ If you need only the CLI client without the desktop UI — for example, on headl
 #### One-command binary install
 
 <Warning>
-    The macOS binary tarballs from GitHub releases are **not Apple code-signed or notarized**. Only the official `.pkg` installer from [pkgs.netbird.io](https://pkgs.netbird.io) contains signed binaries. The unsigned binary will trigger Gatekeeper warnings and may be blocked by MDM policies. For managed fleet deployments, see [Building a CLI-Only .pkg for MDM Deployment](/manage/integrations/mdm-deployment/macos-cli-pkg-deployment) which includes steps for signing the binary with your own Developer ID.
+    The macOS binary tarballs from GitHub releases are **not Apple code-signed or notarized**. Only the official `.pkg` installer from [pkgs.netbird.io](https://pkgs.netbird.io) contains signed binaries. The unsigned binary will trigger Gatekeeper warnings and may be blocked by MDM policies. For managed fleet deployments, see [Building a CLI-Only .pkg for MDM Deployment](/manage/peers/mdm-deployment/macos-cli-pkg-deployment) which includes steps for signing the binary with your own Developer ID.
 </Warning>
 
 The install script supports a binary-only mode that downloads the tarball, extracts the `netbird` binary to `/usr/local/bin/`, and registers the launchd daemon:
@@ -106,7 +106,7 @@ curl -fsSL https://pkgs.netbird.io/install.sh | USE_BIN_INSTALL=true SKIP_UI_APP
 This creates a launchd daemon at `/Library/LaunchDaemons/netbird.plist` that runs as root (required for managing the WireGuard network interface).
 
 <Warning>
-    Automatic updates via the NetBird dashboard do **not** work for binary-only installs. The auto-updater requires the official `.pkg` installer (it checks for the `io.netbird.client` package receipt). For binary installs, you must update manually or push updates through your MDM solution. See [Building a CLI-Only .pkg for MDM Deployment](/manage/integrations/mdm-deployment/macos-cli-pkg-deployment) for a managed approach.
+    Automatic updates via the NetBird dashboard do **not** work for binary-only installs. The auto-updater requires the official `.pkg` installer (it checks for the `io.netbird.client` package receipt). For binary installs, you must update manually or push updates through your MDM solution. See [Building a CLI-Only .pkg for MDM Deployment](/manage/peers/mdm-deployment/macos-cli-pkg-deployment) for a managed approach.
 </Warning>
 
 ## Running NetBird with SSO Login

src/pages/get-started/install/windows.mdx

@@ -59,7 +59,7 @@ netbird up --setup-key <SETUP KEY>
 ```
 
 <Note>
-    For MDM-specific deployment guides, see [Deploy with Intune](/manage/integrations/mdm-deployment/intune-netbird-integration) or [Deploy with Acronis](/manage/for-partners/acronis-integration).
+    For MDM-specific deployment guides, see [Deploy with Intune](/manage/peers/mdm-deployment/intune-netbird-integration) or [Deploy with Acronis](/manage/for-partners/acronis-integration).
 </Note>
 
 ## Running NetBird with SSO Login

src/pages/manage/dns/dns-aliases-for-routed-networks.mdx

@@ -1,11 +1,17 @@
+export const description = 'Give resources behind NetBird routing peers friendly DNS names by pairing Custom DNS Zones with Networks: zone records, routing, policies, and verification.'
+
 # DNS Aliases for Routed Networks
 
-This guide explains how to use Custom DNS Zones with NetBird's Networks to provide easy-to-remember DNS names for resources in private
+This guide explains how to use [Custom DNS Zones](/manage/dns/custom-zones) with NetBird's Networks to provide easy-to-remember DNS names for resources in private
 networks.
 
 
 Custom DNS Zones work seamlessly with NetBird's [Networks](/manage/networks) feature to provide friendly DNS names for resources behind routing peers. This eliminates the need to remember IP addresses when accessing private network resources, creating a professional enterprise-like experience.
 
+<Note>
+In this setup, NetBird hosts the DNS records itself. If you already run internal DNS servers (Active Directory, BIND, Unbound), point NetBird at them instead: see [Internal DNS Servers](/manage/dns/internal-dns-servers).
+</Note>
+
 ## How It Works
 
 ### The Challenge
@@ -64,11 +70,13 @@ First, create a Custom DNS Zone to manage the DNS records for your private servi
 2.  Click **Add Zone**.
 3.  Configure the zone:
     - **Domain**: `netbird.internal`.
-    - **Distribution Groups**: Select the groups that should have access to this DNS zone (e.g., `dev`, `internal-services`).
-    - **Enable Search Domain**: Keep this enabled to allow using short names (e.g., `postgres` instead of `postgres.netbird.internal`).
+    - **Distribution Groups**: Select the groups that should have access to this DNS zone (e.g., `dev`, `internal-services`). Include the **routing peer's group** as well: with [Routing Peer DNS Resolution](/manage/networks/how-routing-peers-work#routing-peer-dns-resolution) enabled (the default), clients forward queries for routed domains to the routing peer, which can only answer from zones it receives.
+    - **Enable Search Domain**: Turn this on (it is off by default) to allow using short names (e.g., `postgres` instead of `postgres.netbird.internal`).
 4.  Click **Add Zone**.
 
-<img src="/docs-static/img/manage/dns/dns-aliases/zone-config.png" alt="Delete DNS Zone" className="imagewrapper-big"/>
+For the full reference on zone settings, record types, and limitations, see [Custom Zones](/manage/dns/custom-zones).
+
+<img src="/docs-static/img/manage/dns/dns-aliases/zone-config.png" alt="Custom DNS Zone configuration" className="imagewrapper-big"/>
 
 ### Step 2: Add DNS Records
 
@@ -106,7 +114,7 @@ To enable access to your private resources, you need to set up a network with ro
 
 #### Add Network Resources
 
-Add a wildcard resource that will match all services in your DNS zone.
+Add a domain resource for each service in your DNS zone.
 
 1. Click **Add Resource** and configure:
    - **Name**: `Internal Wiki`