From d5564c1881c2b6b9ebaadefa30889798ecccbab5 Mon Sep 17 00:00:00 2001
From: Wassim Bougarfa <12980387+wassimoo@users.noreply.github.com>
Date: Mon, 8 Jun 2026 15:49:42 +0200
Subject: [PATCH] fix: update installation guides and sidebar paths for kratos

---
 AGENTS.md                             |  2 +
 docs/_common/install.mdx              | 63 ++++++++++++---------------
 docs/identities/get-started/setup.mdx | 32 ++++++++++----
 docs/kratos/install.mdx               |  4 ++
 docs/oel/kratos/install.mdx           | 20 +++++++++
 sidebars-oel.ts                       |  2 +-
 sidebars-oss.ts                       |  1 -
 7 files changed, 78 insertions(+), 46 deletions(-)
 create mode 100644 docs/oel/kratos/install.mdx

diff --git a/AGENTS.md b/AGENTS.md
index ccd4e0ac7e..dc615efa5e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -186,6 +186,8 @@ import MyPartial from "@site/src/components/Shared/kratos/index.mdx"
 - Can’t find a page → check `docs/network`, `docs/oel`, `docs/oss`
 - Duplicate content → always set canonical URLs
 - Adding a page → update the correct sidebar
+- Deleting a page → never delete without adding a Vercel redirect from the old
+  URL to a relevant replacement
 
 ## When in Doubt
 
diff --git a/docs/_common/install.mdx b/docs/_common/install.mdx
index 3b49621fba..7dd0c9dab7 100644
--- a/docs/_common/install.mdx
+++ b/docs/_common/install.mdx
@@ -1,50 +1,41 @@
 Ory software runs on any operating system (FreeBSD, macOS, Linux, Windows, ...) and supports all major CPU platforms (ARM64,
 ARMv7, x86_64, x86, ...).
 
-Ory provides pre-built binaries, Docker Images and support various package managers:
-
-```mdx-code-block
-import TOCInline from '@theme/TOCInline'
-
-<TOCInline toc={toc} />
-```
-
-## Linux
-
 ```mdx-code-block
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
 import Linux from '@site/src/components/Install/Linux'
-
-<Linux repo={props.repo} name={props.name} />
-```
-
-## macOS
-
-```mdx-code-block
 import MacOS from '@site/src/components/Install/MacOS'
-
-<MacOS repo={props.repo} command={props.command} name={props.name} />
-```
-
-## Windows
-
-```mdx-code-block
 import Windows from '@site/src/components/Install/Windows'
-
-<Windows repo={props.repo} name={props.name} />
-```
-
-## Docker
-
-```mdx-code-block
 import Docker from '@site/src/components/Install/Docker'
 
-<Docker repo={props.repo} name={props.name} />
+<Tabs
+  defaultValue="macos"
+  values={[
+    { label: 'macOS', value: 'macos' },
+    { label: 'Linux', value: 'linux' },
+    { label: 'Windows', value: 'windows' },
+    { label: 'Docker', value: 'docker' },
+    { label: 'Kubernetes', value: 'kubernetes' },
+  ]}>
+  <TabItem value="macos">
+    <MacOS repo={props.repo} command={props.command || props.repo} name={props.name} />
+  </TabItem>
+  <TabItem value="linux">
+    <Linux repo={props.repo} name={props.name} />
+  </TabItem>
+  <TabItem value="windows">
+    <Windows repo={props.repo} name={props.name} />
+  </TabItem>
+  <TabItem value="docker">
+    <Docker repo={props.repo} name={props.name} />
+  </TabItem>
+  <TabItem value="kubernetes">
+    A list of available Helm Charts for Kubernetes can be found at <a href="https://k8s.ory.com/helm">k8s.ory.com/helm</a>.
+  </TabItem>
+</Tabs>
 ```
 
-## Kubernetes
-
-A list of available Helm Charts for Kubernetes can be found at [k8s.ory.com/helm](https://k8s.ory.com/helm/).
-
 ## Download Binaries
 
 <p>
diff --git a/docs/identities/get-started/setup.mdx b/docs/identities/get-started/setup.mdx
index 357b8a5030..0591671e91 100644
--- a/docs/identities/get-started/setup.mdx
+++ b/docs/identities/get-started/setup.mdx
@@ -9,6 +9,9 @@ import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
 import CodeBlock from '@theme/CodeBlock'
 import { FrameworkCodeTabs } from '@site/src/components/GuidesComponents'
+import Linux from '@site/src/components/Install/Linux'
+import MacOS from '@site/src/components/Install/MacOS'
+import Windows from '@site/src/components/Install/Windows'
 import nextDevSetup from '!!raw-loader!./_common/code-examples/nextjs/ory.ts'
 import goSetup from '!!raw-loader!./_common/code-examples/go/ory_client.go'
 import jsDevSetup from '!!raw-loader!./_common/code-examples/js/setupDev.js'
@@ -69,16 +72,13 @@ For local development, you'll need to use Ory Tunnel to connect your local appli
   values={[
     {label: 'macOS', value: 'macos'},
     {label: 'Linux', value: 'linux'},
+    {label: 'Windows', value: 'windows'},
   ]}>
 <TabItem value="macos">
 ```
 
-```shell
-# Install Ory CLI using Homebrew
-brew install ory/tap/cli
-
-# Verify installation
-ory help
+```mdx-code-block
+<MacOS repo="cli" command="ory" name="the Ory CLI" />
 ```
 
 ```mdx-code-block
@@ -86,6 +86,19 @@ ory help
 <TabItem value="linux">
 ```
 
+```mdx-code-block
+<Linux repo="ory" name="the Ory CLI" />
+```
+
+```mdx-code-block
+</TabItem>
+<TabItem value="windows">
+```
+
+```mdx-code-block
+<Windows repo="ory" name="the Ory CLI" />
+```
+
 ```mdx-code-block
 </TabItem>
 </Tabs>
@@ -94,10 +107,13 @@ ory help
 After installing the CLI, start the tunnel to connect your local application with Ory's APIs:
 
 ```shell
-# Start the tunnel (replace with your project id)
-ory tunnel --project $PROJECT_ID http://localhost:3000
+ory tunnel --project $ORY_PROJECT_ID --port 4000 http://localhost:3000
 ```
 
+This proxies Ory's APIs on `http://localhost:4000` and forwards all other traffic to your application at `http://localhost:3000`.
+Running the tunnel is required for local development because Ory's session cookies must be set on the same domain as your
+application.
+
 :::tip
 
 To learn more about the Ory Tunnel, read the [dedicated section of the Ory CLI documentation](../../guides/cli/proxy-and-tunnel).
diff --git a/docs/kratos/install.mdx b/docs/kratos/install.mdx
index fa0bec39d7..9362a8cce8 100644
--- a/docs/kratos/install.mdx
+++ b/docs/kratos/install.mdx
@@ -3,6 +3,10 @@ id: install
 title: Installation
 ---
 
+<head>
+  <link rel="canonical" href="https://www.ory.com/docs/oel/kratos/install" />
+</head>
+
 ```mdx-code-block
 import Secure from '../_common/secure.mdx'
 
diff --git a/docs/oel/kratos/install.mdx b/docs/oel/kratos/install.mdx
new file mode 100644
index 0000000000..d4038dfbdc
--- /dev/null
+++ b/docs/oel/kratos/install.mdx
@@ -0,0 +1,20 @@
+---
+id: install
+title: Installation
+---
+
+<head>
+  <link rel="canonical" href="https://www.ory.com/docs/oel/kratos/install" />
+</head>
+
+```mdx-code-block
+import Secure from '@site/docs/_common/secure.mdx'
+
+<Secure />
+```
+
+```mdx-code-block
+import Install from '@site/docs/_common/install.mdx'
+
+<Install repo="kratos" name="Ory Kratos" />
+```
diff --git a/sidebars-oel.ts b/sidebars-oel.ts
index e9bf9182e9..6c6e84902a 100644
--- a/sidebars-oel.ts
+++ b/sidebars-oel.ts
@@ -50,7 +50,7 @@ const oelSidebar = [
         className: "sidebar-icon sidebar-icon-kratos",
         items: [
           "oel/kratos/intro",
-          "kratos/install",
+          "oel/kratos/install",
           "self-hosted/oel/kratos/upgrade",
           "self-hosted/oel/kratos/changelog",
           "oel/kratos/quickstart",
diff --git a/sidebars-oss.ts b/sidebars-oss.ts
index 6f6ae58d1c..409a2339c3 100644
--- a/sidebars-oss.ts
+++ b/sidebars-oss.ts
@@ -60,7 +60,6 @@ const ossSidebar = [
           "oss/kratos/intro",
           "kratos/install",
           "kratos/guides/upgrade",
-          "self-hosted/oel/kratos/changelog",
           "oss/kratos/quickstart",
           {
             type: "category",