chore: add terminology Markdown catalog for Copilot review (#11764)

## Problem ZITADEL has inconsistent naming across docs, UI, and API ([#5888](https://github.com/zitadel/zitadel/issues/5888)). We want contributors and Copilot code-review agents to flag discouraged terms and suggest canonical replacements automatically. ## Solution Add a **Markdown terminology catalog** that Copilot agents read natively. ### What's added - **`TERMINOLOGY.md`** (repo root) — full ~35-term canonical table from issue #5888 with: - Action legend: `keep` / `replace` / `remove` / `internal` / `proposed` - Scope legend: `UI` / `Docs` / `API` / `Everywhere` - "Search for (discouraged)" and "Replace with / enforce" columns - Governance section (how to add new terms, ownership) - **`.github/instructions/terminology.instructions.md`** — Copilot `applyTo`-scoped instruction that activates on every PR touching docs/i18n/proto files and tells the agent: - Which files map to which scope - Not to flag identifiers/field names in proto files (only comments/descriptions) - To request catalog updates when new terms are introduced ### What's updated - `.github/copilot-instructions.md` — points to `TERMINOLOGY.md` - `apps/docs/AGENTS.md` — updated reference, removed dead `check-terminology` Nx target entry - `.github/pull_request_template.md` — checklist item updated - `.github/workflows/ready_for_review.yml` — checklist item updated ### Why Markdown over JSON | | Markdown | JSON | |---|---|---| | Copilot reads natively | yes | no (needs parsing context) | | Mirrors AGENTS.md table style | yes | no | | Human-readable without tooling | yes | no | | Mirrors the #5888 issue format | yes | no | | Requires schema / parser | no | yes | ### Why root over `.github/` `.github/` is for GitHub-specific automation files. `TERMINOLOGY.md` is a project-wide convention document — it belongs alongside `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `AGENTS.md` at the repo root. ## How it works in practice When a PR touches `apps/docs/content/**`, `console/src/assets/i18n/**`, `apps/login/locales/**`, or `proto/**/*.proto`, Copilot code review automatically loads `.github/instructions/terminology.instructions.md` and cross-references `TERMINOLOGY.md` to flag discouraged terms. Human reviewers see the terminology checklist in the auto-comment on PR open. ## Checklist - [x] `TERMINOLOGY.md` at repo root with all ~35 terms from #5888 - [x] Plain text action/scope values (no emojis) - [x] Copilot instruction file scoped to correct file patterns - [x] All stale `terminology-rules.json` references removed - [x] No linter/CI step added (guidelines-only approach) Relates to: #5888 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Fabienne Bühler <[email protected]>
2026-10-18 05:52:51 +00:00 · 2026-03-11 16:20:27 +00:00
parent 574e23e834
commit 4586708c06
6 changed files with 102 additions and 0 deletions
@@ -21,5 +21,6 @@ You are working in the ZITADEL monorepo. This codebase uses specific conventions
 - Use verified Nx targets only; if unsure, run `pnpm nx show project <project>`.
 - For backend changes, note we are in transition: relational data is becoming the system of record, while event writes are still required for history/audit.
 - Respect terminology defined in the `Technical Glossary` section of `AGENTS.md` when generating UI text or documentation.
+- For user-facing wording updates across docs/UI/API descriptions, follow the canonical table in `TERMINOLOGY.md` (issue #5888).
 - Distinguish between `apps/login` (Next.js) and `console` (Angular) when suggesting frontend code.
 - For deployment-related work, consult the directory-specific agents files (e.g., `deploy/compose/AGENTS.md`) for invariants, file conventions, and rejected alternatives.
@@ -0,0 +1,16 @@
+---
+applyTo: '{apps/docs/content/**/*.mdx,apps/docs/content/**/*.md,console/src/assets/i18n/*.json,apps/login/locales/*.json,internal/static/i18n/*.yaml,internal/static/i18n/*.yml,proto/**/*.proto}'
+---
+
+When reviewing user-facing naming changes, enforce the canonical terminology table in `TERMINOLOGY.md`.
+
+### How to apply
+- Cross-reference every changed user-facing string against the **Search for (discouraged)** column.
+- If a discouraged term is found, flag it and suggest the canonical term from **Replace with / enforce**.
+- For `proto/**/*.proto` files: check comments and `description:`/`summary:` text only; do not flag identifiers, field names, or enum values.
+- Only apply rules where the **Scope** column matches the file type:
+  - `UI` → `console/src/assets/i18n/`, `apps/login/locales/`
+  - `Docs` → `apps/docs/content/`
+  - `API` → `proto/**`, API description text
+  - `Everywhere` → all of the above
+- If a PR introduces a new policy, setting, or resource term not yet in the table, request that the contributor adds it to `TERMINOLOGY.md`.
@@ -21,6 +21,7 @@ Replace this example text with a concise list of additional changes that this PR
 For example:
 - The docs explicitly describe that the property XY is mandatory
 - Adds missing translations for validations.
+- Terminology updates follow issue #5888 and `TERMINOLOGY.md` (including catalog updates for newly introduced terms).

 # Additional Context

@@ -15,6 +15,7 @@ jobs:
            
              - [ ] I have reviewed my changes and would approve it
              - [ ] Documentations and examples are up-to-date
+              - [ ] Terminology updates follow issue #5888 and TERMINOLOGY.md
              - [ ] Logical behavior changes are tested automatically
              - [ ] No debug or dead code
              - [ ] My code has no repetitions
@@ -0,0 +1,82 @@
+# ZITADEL Canonical Terminology
+
+Authoritative naming reference derived from [issue #5888](https://github.com/zitadel/zitadel/issues/5888).
+All user-facing wording in docs, UI, and API descriptions must follow this table.
+
+## Action values
+
+| Action | Meaning |
+|--------|---------|
+| keep | Already correct — no change needed |
+| replace | Discouraged term found — use the canonical term instead |
+| remove | Term must be removed entirely |
+| internal | Internal use only — must not appear in user-facing text |
+| proposed | Under discussion — agents should flag but not block |
+
+## Scope values
+
+| Scope | Files |
+|-------|-------|
+| UI | Console (`console/src/assets/i18n/`) and Login UI (`apps/login/locales/`) |
+| UI + Docs | UI files plus documentation content (`apps/docs/content/`) |
+| UI dialogs | Subset of UI: modal and confirmation dialog strings |
+| UI section | Subset of UI: labels tied to a specific page section |
+| UI indicator | Subset of UI: inline status or indicator labels |
+| UI notifications | Subset of UI: toast, banner, and notification strings |
+| Docs | Documentation content (`apps/docs/content/`) |
+| API | Proto files and API description/comment text (`proto/**`) |
+| Everywhere | UI + Docs + API |
+| — | Internal only — no user-facing file scope |
+
+## Canonical Terminology Table
+
+| Canonical term | Meaning / explanation | Search for (discouraged) | Replace with / enforce | Action | Scope |
+|---|---|---|---|---|---|
+| Customer Portal | Central hub for all customer interactions for cloud and self-hosting customers | _(none — already canonical)_ | Customer Portal | keep | Everywhere |
+| Management Console | Web interface where customers configure and manage ZITADEL resources. Must be visible as the UI app name. | Console, ZITADEL Console, Admin Console, Administration Console | Management Console | replace | UI |
+| Instance | Private, isolated top-level ZITADEL environment | IAM, System, Type IAM | Instance / Type Instance | replace | Everywhere |
+| Policies | Enforcement rules governing checks and constraints. Use only in enforcement contexts, always scoped (Instance / Organization). | Instance Policies, IAM Policies, Org Policies, Policies (unscoped), Instance Settings (when enforcing), Org Settings (when enforcing) | Instance Policies / Organization Policies | replace | Everywhere |
+| Settings | Resource-specific configuration values (not rules). Use only in configuration contexts, always scoped (Instance / Organization). | Instance Settings, Org Settings, Instance Policies (when config), Org Policies (when config), IAM Policies (when config) | Instance Settings / Organization Settings | replace | Everywhere |
+| Organization | Group of users within an instance | Organisation | Organization | replace | Everywhere |
+| Organization Domain | Domain giving context where a user belongs | Primary Domain, Verified Domains, Org domains, verify your domain | Organization Domain | replace | UI + Docs |
+| User (Human) | User with interactive authentication flows | Human, Human User, User: Type Human | User (Human) | replace | UI + Docs |
+| Service Account | User with non-interactive authentication flows | Machine User, machine user, Service User, Machine Account, Technical Account, User: Type Machine | Service Account | replace | UI + Docs |
+| User | UI display label for user identity | Display Name | User | replace | UI |
+| Project | Container for applications sharing a role context | _(none — already canonical)_ | Project | keep | Everywhere |
+| Project Grant | Delegation of project access to another organization | Grant, Grants, Organization Grant, Delegated Access | Project Grant / Project Grants | replace | UI + Docs |
+| Application | Software or service secured using ZITADEL | _(none — already canonical)_ | Application | keep | Everywhere |
+| Role Assignment | What a user is allowed to do (roles + org + user) | Authorization, external authorization, User Grant, Roles and Authorizations | Role Assignment | replace | Everywhere |
+| Administrator | Role granting administrative privileges (role context only, not as a person label) | Manager, Add Manager, Add a Manager, Membership, Member, Member grants | Administrator / Add Administrator / Add an Administrator | replace | UI + Docs |
+| Organization Administrators | Org-level admin role holders | ZITADEL Organization Managers | Organization Administrators | replace | UI + Docs |
+| Project Administrators | Project-level admin role holders | Project A Managers | Project Administrators | replace | UI + Docs |
+| Administrator Roles | Set of admin roles | Manager Roles, Membership Roles | Administrator Roles | replace | UI + Docs |
+| ZITADEL Administrator Roles | ZITADEL-specific admin role set | ZITADEL Manager Roles, Zitadel Manager Roles, Zitadel Membership Roles, ZITADEL Membership Roles | ZITADEL Administrator Roles | replace | UI + Docs |
+| Permission | Internal permission backing admin roles | _(internal term)_ | _(do not surface in user-facing text)_ | internal | — |
+| Metadata | Key-value custom data attached to resources | Meta Data | Metadata | replace | Everywhere |
+| Custom Domain | Domain identifying a ZITADEL instance (globally unique) | Custom domain, Installed domains, Instance Domains, Zitadel Domain, your_domain, your-domain | Custom Domain | replace | UI + Docs |
+| Trusted Domain | Domain used for API/email contexts | _(none — already canonical)_ | Trusted Domain | keep | Everywhere |
+| Passkey | Passwordless auth using device-bound credentials | passwordless, passwordless login, passwordless auth, Multifactor (fingerprint/security keys), Fingerprint, Security Keys, WebAuthn, Webauthn | Passkey | replace | UI + Docs |
+| TOTP | Time-based one-time password via authenticator app | OTP (authenticator), Authenticator App | TOTP | replace | UI + Docs |
+| U2F | Legacy hardware authentication (deprecated) | U2F | _(remove)_ | remove | Everywhere |
+| OTP Email | One-time password delivered via email | Email OTP | OTP Email | replace | UI + Docs |
+| OTP SMS | One-time password delivered via SMS | SMS OTP | OTP SMS | replace | UI + Docs |
+| Organization ID | Explicit organization identifier | Resource Owner, OrgID, OrganizationID | `organization_id` | replace | API |
+| Explicit object IDs | Explicit identifier per resource type | Resource ID, ResourceID | `user_id` / `project_id` / `application_id` / `instance_id` / `organization_id` | replace | API |
+| Instance ID | Instance identifier label in UI | Resource Id (Instance) | Instance ID | replace | UI + Docs |
+| ID | Generic identifier label in UI | Resource Id | ID | replace | UI |
+| First Name | Personal given name field | Given Name | First Name | replace | Everywhere |
+| Last Name | Personal family name field | Family Name | Last Name | replace | Everywhere |
+| Add Administrator (dialog) | Consistent wording for admin-add dialog | Add Manager, Add a Manager | Add Administrator / Add an Administrator | replace | UI dialogs |
+| Administrator (memberships section) | UI section on the user detail page showing admin memberships — should be labeled "Administrator", not "Memberships" | Memberships | Administrator | replace | UI section |
+| Project Grants (section) | Project grant listing section | Grants | Project Grants | replace | UI section |
+| Internal / External indicator | Shows if a user belongs to the same or a different org | _(missing indicator)_ | internal / external | replace | UI indicator |
+| Password changed | Past-tense wording for password change notification | Password change | Password changed | replace | UI notifications |
+| Object descriptions | All resource descriptions must use end-user language | internal / technical wording | clear end-user language | replace | UI + Docs |
+| Complement Token | Flow type for actions executed during token creation. In UI use "Complement Token"; in API use `flowType = 2` (CustomiseToken). Docs must not show PreUserinfoCreation=3 for this type. | Compliment Token, CustomiseToken, CustomizeToken | Complement Token | replace | Everywhere |
+
+## Governance
+
+- **To add a new term**: open a PR that updates this table and references the decision thread.
+- **Terms under discussion** may be added with action `proposed` — agents will flag but not block.
+- **Ownership**: Docs + Product/UX + API maintainers approve changes to this file.
+- **Source of truth for this table**: [GitHub issue #5888](https://github.com/zitadel/zitadel/issues/5888)
@@ -13,6 +13,7 @@ The **Docs App** (`apps/docs`) hosts the ZITADEL documentation. It has recently
 - **Links**: Use absolute paths or standard MDX linking.
 - **Components**: Use only MDX components that are documented in the official Fumadocs MDX component reference and any project-specific MDX component documentation in this repo; do not introduce or rely on undocumented components.
 - **API Docs**: Changes in `proto/` or API response schemas often require regeneration via docs generation targets.
+- **Terminology**: For user-facing naming changes in docs/UI/API descriptions, follow `TERMINOLOGY.md` (issue #5888 source). Copilot code review will flag discouraged terms automatically on PRs touching these paths.

 ## Verified Nx Targets
 - **Dev Server**: `pnpm nx run @zitadel/docs:dev`