docs: Add note for updated terminology (#11802)

# Which Problems Are Solved

For existing customers it could be hard to understand the new aligned
terms we have defined, if they are already used to the "old term"

# How the Problems Are Solved

Adding notes at the top of docs pages to state clearliy new and old
terms.

apps/docs/components/terminology-update.tsx

@@ -0,0 +1,23 @@
+import { Callout } from 'fumadocs-ui/components/callout';
+
+interface TermNoteProps {
+    newTerm: string;
+    oldTerms: string[];
+}
+
+export function TerminologyUpdate({ newTerm, oldTerms }: TermNoteProps) {
+    // Formats the list: "A, B and C"
+    const formattedOldTerms = oldTerms.map((term, i) => (
+        <b key={term}>
+            {term}{i < oldTerms.length - 2 ? ', ' : i === oldTerms.length - 2 ? ' or ' : ''}
+        </b>
+    ));
+
+    return (
+        <Callout type="info">
+            <b>Terminology Update:</b> We have streamlined our naming conventions to improve clarity.
+            The term <b>{newTerm}</b> now replaces what was previously referred to as {formattedOldTerms}.
+            These terms all refer to the same underlying functionality.
+        </Callout>
+    );
+}

apps/docs/content/concepts/features/external-user-grant.mdx

@@ -3,6 +3,12 @@ title: External User Role Assignments
 description: "Grant access to projects for external users from other organizations using ZITADEL's external user role assignments"
 ---
 
+<TerminologyUpdate
+    newTerm="Role Assignment"
+    oldTerms={["User Grant", "Authorization"]}
+/>
+
+
 ZITADEL's external user role assignment is a feature that allows you to grant access to projects within your organization to users from other organizations.
 This is useful in scenarios where you want to collaborate with external users without needing them to be part of your organization.
 By using external user role assignments, you can streamline collaboration with external users while maintaining control over access to your projects within ZITADEL.

apps/docs/content/concepts/structure/administrators.mdx

@@ -6,6 +6,12 @@ sidebar_label: Administrators
 
 import AdministratorDescription from "./_administrator_description.mdx";
 
+<TerminologyUpdate
+    newTerm="Administrators"
+    oldTerms={["Members", "Memberships", "Managers"]}
+/>
+
+
 <AdministratorDescription components={props.components}  name="AdministratorDescription" />
 
 Notes:

apps/docs/content/concepts/structure/instance.mdx

@@ -4,6 +4,11 @@ description: "Overview of ZITADEL Instances—the virtual tenants providing full
 sidebar_label: Instances
 ---
 
+<TerminologyUpdate
+    newTerm="Instance"
+    oldTerms={["IAM"]}
+/>
+
 ## Instance Structure
 
 An instance is the top node in ZITADEL's data hierarchy.

apps/docs/content/guides/integrate/retrieve-user-roles.mdx

@@ -4,6 +4,11 @@ description: "Methods for retrieving assigned user roles and authorizations for
 sidebar_label: Retrieve User Roles
 ---
 
+<TerminologyUpdate
+    newTerm="Role Assignment"
+    oldTerms={["User Grant", "Authorization"]}
+/>
+
 This guide explains all the possible ways of retrieving user roles across different organizations and projects using ZITADEL's APIs.
 
 ## What are roles and role assignments in ZITADEL?

apps/docs/content/guides/integrate/service-accounts/authenticate-service-accounts.mdx

@@ -6,6 +6,11 @@ sidebar_label: Authenticate service accounts
 
 import DocCardList from '@/components/docusaurus/doc-card-list';
 
+<TerminologyUpdate
+    newTerm="Service Accounts"
+    oldTerms={["Service User", "Machine Users", "Technical Account"]}
+/>
+
 This guide explains ZITADEL service accounts and their role in facilitating secure machine-to-machine communication within your applications.
 
 ## What are Service Accounts?

apps/docs/content/guides/manage/console/administrators.mdx

@@ -9,6 +9,11 @@ import AddAdministrator from "./_add_administrator.mdx";
 import PermissionTable from '@/components/PermissionTable';
 import permissionData from "../../../../../../cmd/defaults.yaml";
 
+<TerminologyUpdate
+    newTerm="Administrators"
+    oldTerms={["Members", "Memberships", "Managers"]}
+/>
+
 <AdministratorDescription components={props.components}  name="AdministratorDescription" />
 
 To configure administrators in ZITADEL, go to the resource where you like to add it (e.g., Instance, Organization, Project, GrantedProject).

apps/docs/content/guides/manage/console/roles.mdx

@@ -4,6 +4,11 @@ description: "Define custom roles and manage user role assignments within your Z
 sidebar_label: Roles and Role Assignments
 ---
 
+<TerminologyUpdate
+    newTerm="Role Assignment"
+    oldTerms={["User Grant", "Authorization"]}
+/>
+
 If you built out the [POS use case example](./projects-overview#example-scenario), you would probably need an application for administration.
 In this application you would probably have somebody accessing as an accountant and somebody as an administrator, who is somebody with enhanced rights.
 To achieve this, you would have to add this distinction as roles.

apps/docs/content/guides/manage/console/users-overview.mdx

@@ -24,6 +24,12 @@ Users represent actual people who log in via an interactive interface (e.g., a l
 Read more on how to [login users with ZITADEL](/guides/integrate/login/login-users).
 
 ### Service Accounts
+
+<TerminologyUpdate
+    newTerm="Service Accounts"
+    oldTerms={["Service User", "Machine Users", "Technical Account"]}
+/>
+
 Service accounts represent machines, backend services, or IoT devices requiring non-interactive access.
 * **Profile:** Only has a name, description, and username.
 * **Authentication:** Authenticates via **JWT Profile** or **Personal Access Tokens (PAT)**. Both methods support expiration settings.

apps/docs/lib/sidebar-data.ts

@@ -960,8 +960,8 @@ export const apisSidebar: readonly SidebarItem[] = [
           { type: "category", label: "Instance", items: ["reference/api/instance"] },
           { type: "category", label: "Project", items: ["reference/api/project"] },
           { type: "category", label: "Application", items: ["reference/api/application"] },
-          { type: "category", label: "Authorizations", items: ["reference/api/authorization"] },
-          { type: "category", label: "Internal Permissions", items: ["reference/api/internal_permission"] },
+          { type: "category", label: "Role Assignments", items: ["reference/api/authorization"] },
+          { type: "category", label: "ZITADEL Internal Permissions", items: ["reference/api/internal_permission"] },
         ],
       },
       {

apps/docs/mdx-components.tsx

@@ -1,6 +1,7 @@
 import defaultMdxComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
 import { APIPage } from '@/components/api-page';
+import { TerminologyUpdate } from '@/components/terminology-update';
 import { Callout } from 'fumadocs-ui/components/callout';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { Step, Steps } from 'fumadocs-ui/components/steps';
@@ -16,6 +17,7 @@ export function useMDXComponents(components?: MDXComponents): MDXComponents {
     Step,
     Steps,
     APIPage,
+    TerminologyUpdate,
     ...components,
   };
 }

apps/docs/scripts/generate-api-reference.ts

@@ -19,6 +19,9 @@ const ROOT_DIR = join(__dirname, '..');
 const OPENAPI_ROOT = join(ROOT_DIR, 'openapi');
 const CONTENT_ROOT = join(ROOT_DIR, 'content');
 const CONTENT_VERSIONS_ROOT = join(ROOT_DIR, 'content');
+const serviceRenameMap: Record<string, string> = {
+  'Authorization': 'Role Assignment',
+};
 
 async function generateVersionApiDocs(version: string) {
   const sourceRoot = join(OPENAPI_ROOT, version);
@@ -68,13 +71,22 @@ async function generateVersionApiDocs(version: string) {
     });
 
     const indexPath = join(outputDir, 'index.mdx');
-    const title = uniqueService.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ');
+    let originalTitle = uniqueService.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ');
+    let newTitle = serviceRenameMap[originalTitle] ?? originalTitle;
+    const hasBeenRenamed = !!newTitle;
+    const title = newTitle ?? originalTitle;
+    const renameNote = hasBeenRenamed
+        ? `\n> **Terminology Update:** We have streamlined our naming conventions to improve clarity. The term **${originalTitle}** has been replaced with **${title}**. To avoid breaking changes the APIs still make use of the old term. Both terms refer to the same underlying functionality.\n`
+        : '';
+
     const indexContent = `---
 title: ${title} API
 description: Explore the ZITADEL ${title} API reference documentation. Learn how to manage resources, handle authentication, and integrate ${title} services into your application.
 ---
 
 API Reference for ${title}
+
+${renameNote}
 `;
     writeFileSync(indexPath, indexContent);
   }