ory · aeneasr · Apr 20, 2026 · Apr 22, 2026 · Apr 27, 2026 · Apr 27, 2026
@@ -0,0 +1,5 @@
+reviews:
+  review_status: false
+  # Temporarily exclude MDX files from review processing.
+  path_filters:
+    - "!**/*.mdx"
@@ -19,10 +19,10 @@ jobs:
     runs-on: ubuntu-latest
     name: Find closed references
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2-beta
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
-          node-version: "14"
+          node-version: "24"
       - uses: ory/closed-reference-notifier@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}

@@ -24,7 +24,7 @@ jobs:
     name: Validate PR title
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
       - id: config
         uses: ory/ci/conventional_commit_config@master
         with:

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
       - name: Synchronize Issue Labels
         uses: ory/label-sync-action@v0
         with:

@@ -0,0 +1,194 @@
+# Updating Ory Documentation
+
+## Overview
+
+Ory documentation is being organized by **deployment model**:
+
+- **Ory Network** → `docs/network`
+- **Ory Enterprise License (OEL)** → `docs/oel`
+- **Ory Open Source (OSS)** → `docs/oss`
+
+## Current State (Transitional Phase)
+
+- Most content is still **co-mingled**
+- Only some sections (e.g. Quickstarts) use the new structure
+- The Docs team is actively splitting content
+
+### What you should do
+
+- **Non-migrated sections** → continue using the existing structure
+- **Migrated sections** → follow the new pattern
+- **Do not restructure content yourself** unless it has already been migrated
+
+## How to Tell if Content is Migrated
+
+A section is migrated if:
+
+- The **sidebar** shows routes like:
+  - `docs/network/...`
+  - `docs/oel/...`
+  - `docs/oss/...`
+
+OR
+
+- You **cannot find the page in the old structure** and it exists under one of
+  the deployment folders above
+
+## New Structure (Migrated Sections Only)
+
+### Shared Source Content
+
+- Location: `/src/components/shared/<product>/...`
+- Purpose:
+  - Reusable, deployment-agnostic content
+  - Written once, used across deployments
+
+### Deployment Shell Files
+
+Locations:
+
+- `docs/network`
+- `docs/oel`
+- `docs/oss`
+
+Shell files:
+
+- Import content from `/src/components/shared/...`
+- Represent a page for a specific deployment
+- Are the files added to sidebars
+
+---
+
+## Sidebars
+
+- Each deployment has its **own sidebar**
+
+When adding a page:
+
+- Add the **shell file** (not the shared source file)
+- Only include it in deployments where the feature exists
+
+## Canonical URL Rules (SEO)
+
+When the same content exists across multiple deployments, you must define a
+canonical URL.
+
+### Default (Most Cases)
+
+**Ory Network is canonical**
+
+- Network → self-canonical
+- OEL → canonical points to Network
+- OSS → canonical points to Network
+
+### Self-Hosted Exception
+
+If content is specific to **self-hosted (OEL/OSS)**: **OEL is canonical**
+
+- OEL → self-canonical
+- OSS → canonical points to OEL
+- Network → usually not applicable
+
+## How to Update Content (Migrated Sections)
+
+### 1. Determine deployment availability
+
+- Is this available in:
+  - Network
+  - OEL
+  - OSS
+- Be explicit, even if it’s only available in one for now
+
+### 2. Update content
+
+- Edit shared source when possible:`/src/components/shared/<product>/...`
+- Avoid duplicating content across deployments
+
+**Example (shared source):**
+
+`/src/components/shared/kratos/index.mdx`
+
+```mdx
+Ory Kratos Identities is an API-first identity and user management system...
+
+- Self-service login and registration
+- Multi-factor authentication
+- Account recovery
+```
+
+---
+
+### 3. Wire it into deployments
+
+- Ensure a shell file exists in each relevant deployment:
+  - `docs/network/...`
+  - `docs/oel/...`
+  - `docs/oss/...`
+- Import the shared content into the shell file
+
+**Example (Network shell):**
+
+`/docs/network/kratos/intro.mdx`
+
+```mdx
+---
+id: intro
+title: Introduction to Ory Kratos for Ory Network
+sidebar_label: Introduction
+---
+
+<head>
+  <link rel="canonical" href="https://www.ory.com/docs/network/kratos/intro" />
+</head>
+
+import MyPartial from "@site/src/components/shared/kratos/index.mdx"
+
+<MyPartial />
+```
+
+---
+
+### 4. Update sidebar
+
+- Add the **shell file** (not the shared file) to the correct sidebar
+- Only include it in deployments where the feature exists
+
+### 5. Set canonical URLs
+
+- Follow canonical rules:
+
+**Default:**
+
+- Network → self-canonical
+- OEL / OSS → point to Network
+
+**Self-hosted exception:**
+
+- OEL → self-canonical
+- OSS → point to OEL
+- Canonical is defined in the shell file:
+
+```html
+<link rel="canonical" href="..." />
+```
+
+### Summary
+
+- Edit → `/src/components/shared/...`
+- Expose → `docs/<deployment>/...` shell files
+- Navigate → via sidebars
+- De-duplicate → with canonical URLs
+
+## Rule of Thumb
+
+- Old section → leave as-is
+- Migrated section → use shared content + shell files
+- 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
+
+## When in Doubt
+
+- Check the sidebar first
+- Look for `/src/components/shared/...` usage
+- If unclear, ask the Docs team before making structural changes
@@ -0,0 +1 @@
+See @AGENTS.md
@@ -132,7 +132,7 @@
   "out_of": 2163,
   "page": 1,
   "request_params": {
-    "collection_name": "identities-e70f3b9e-f343-40e6-89f1-de24e459722e",
+    "collection_name": "identities",
     "per_page": 5,
     "q": "*"
   },

@@ -1,17 +1,17 @@
 {
   "id": "d52d5bdb-74b4-4aa0-b706-d1e9c853bd81", // the identity ID
   "organization_id": "org-id-123", // optional, facet
-  "external_id": "external-id-123", // optional
-  "created_at": 1725031437, // UNIX timestamp, facet
-  "updated_at": 1758115258, // UNIX timestamp, facet
+  "external_id": "external-id-123", // optional, indexed
+  "created_at": 1725031437, // UNIX timestamp, facet, sortable
+  "updated_at": 1758115258, // UNIX timestamp, facet, sortable
   "state": "active", // "inactive", "deleted", facet
   "schema_id": "preset://email", // identity schema ID, facet
   "available_aal": "aal1", // "aal2" etc, facet
   "metadata_admin": {
-    "role": "user" // custom admin metadata, indexed, search via `query_by=metadata_admin.role`
+    "role": "user" // custom admin metadata, indexed, facet, search via `query_by=metadata_admin.role`
   },
   "metadata_public": {
-    "foo": "bar" // custom public metadata, indexed, search via `query_by=metadata_public.foo`
+    "foo": "bar" // custom public metadata, indexed, facet, search via `query_by=metadata_public.foo`
   },
   "traits": {
     "email": "wgiho@agpaa.com" // traits based on identity schema, indexed, search via `query_by=traits.email`

@@ -1,6 +1,6 @@
 :::info Professional support?
 
 Ory offers support for self-hosted Ory software through the Ory Enterprise License (OEL). Read more about the OEL
-[here](https://www.ory.com/docs/self-hosted/oel).
+[here](../oel/getting-started/index.mdx).
 
 :::
@@ -1,10 +1,16 @@
 ---
 id: single-sign-on
-title: Single Sign On
+title: Ory Console SSO
 sidebar_label: Single Sign On
 ---
 
-The Ory Console supports Single-Sign-On (SSO) via OpenID Connect (OIDC) or SAML. This allows you to use your existing identity
+:::info
+
+Ory Console SSO is available on [Ory Enterprise](https://www.ory.sh/contact/) plans.
+
+:::
+
+The Ory Console supports Single Sign-On (SSO) via OpenID Connect (OIDC) or SAML. This allows you to use your existing identity
 provider (IdP) to authenticate users of the Ory Console.
 
 Once configured, all users with email addresses matching the enrolled domain will be required to use SSO to log in to the Ory
@@ -36,7 +42,7 @@ Follow these steps to configure SSO for your workspace:
 8. Congratulations! You have successfully set up Single Sign-On for your workspace in Ory Console. You can now use your IdP
    credentials to access the console.
 
-### Restricting access to your workspace
+### Restrict access to your workspace
 
 In addition to forcing all users of your organization to use SSO, you can also restrict access to your workspace or any projects
 within it to specific email domains.

@@ -4,7 +4,7 @@ title: API Design
 ---
 
 This document provides a summary of Ory's REST design with topics like pagination and date formats. If you're interested in Ory's
-API design, check out the [REST API design guidelines](../open-source/guidelines/rest-api-guidelines.md).
+API design, check out the [REST API design guidelines](../oss/guidelines/rest-api-guidelines.md)
 
 ## Date format
 

@@ -2,6 +2,7 @@
 id: go
 title: Integrate authentication into Go
 sidebar_label: Go
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block

@@ -2,6 +2,7 @@
 id: php
 title: Integrate authentication into PHP
 sidebar_label: PHP
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block

@@ -2,6 +2,7 @@
 id: expressjs
 title: Integrate authentication into Node.js / Express.js
 sidebar_label: Node.js / Express.js
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block

@@ -2,6 +2,7 @@
 id: auth-js
 title: Integrate authentication into Auth.js and NextAuth
 sidebar_label: Auth.js / NextAuth
+displayed_sidebar: quickstartsSidebar
 ---
 
 # Integrate authentication into Auth.js and NextAuth

@@ -2,6 +2,7 @@
 id: nextjs-app-router-quickstart
 title: Next.js App Router Quickstart
 sidebar_label: Next.js (App Router)
+displayed_sidebar: quickstartsSidebar
 ---
 
 import Tabs from "@theme/Tabs"

@@ -2,6 +2,7 @@
 id: nextjs-pages-router-quickstart
 title: Next.js Pages Router Quickstart
 sidebar_label: Next.js (Pages Router)
+displayed_sidebar: quickstartsSidebar
 ---
 
 import Tabs from "@theme/Tabs"

@@ -2,6 +2,7 @@
 id: flutter-web-redirect
 title: Integrate authentication into Flutter Web
 sidebar_label: Flutter
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block

@@ -2,6 +2,7 @@
 id: react
 title: Integrate authentication into React + API
 sidebar_label: React
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block

@@ -2,6 +2,7 @@
 id: vue
 title: Integrate authentication into Vue.js + API
 sidebar_label: Vue.js
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block

@@ -2,6 +2,7 @@
 id: react-native
 title: Integrate Authentication into React Native
 sidebar_label: React Native
+displayed_sidebar: quickstartsSidebar
 ---
 
 import CodeFromRemote from "@theme/CodeFromRemote"

@@ -2,6 +2,7 @@
 id: java
 title: Integrate authentication into Java + Spring Boot
 sidebar_label: Java (Spring Boot)
+displayed_sidebar: quickstartsSidebar
 ---
 
 ```mdx-code-block