chore: update PR title convention and semantic types in AGENTS.md and CONTRIBUTING.md (#11620)

Since I and the agents sometimes get confused about which scopes and
types to use in our commits and PRs, I've created an explicit list that
we can verify against our existing `semantic.yml` file.

Co-authored-by: Marco A. <[email protected]>
Co-authored-by: Livio Spring <[email protected]>

.github/semantic.yml

@@ -1,2 +1,61 @@
 # Always validate the PR title, and ignore the commits
 titleOnly: true
+
+# Allowed types — the PR title type must be one of these.
+# This list is the single source of truth referenced by AGENTS.md and CONTRIBUTING.md.
+types:
+  - feat      # new feature
+  - fix       # bug fix
+  - docs      # documentation only (no code change)
+  - refactor  # code restructuring without behaviour change
+  - perf      # performance improvement
+  - test      # adding or fixing tests
+  - build     # build system or tooling
+  - ci        # CI/CD pipeline
+  - chore     # maintenance (deps, config, etc.)
+  - revert    # reverts a previous commit
+
+# Allowed scopes — if a scope is provided it must match one of these.
+# Scopes are optional; omit rather than invent one not on this list.
+# Note: 'docs' is a type, not a scope — use the type 'docs' for documentation changes.
+# This list is the single source of truth referenced by AGENTS.md and CONTRIBUTING.md.
+scopes:
+  # Backend — domain areas
+  - api
+  - session
+  - authz
+  - command
+  - query
+  - eventstore
+  - actions
+  - crypto
+  - domain
+  - feature
+  - idp
+  - notification
+  - oidc
+  - saml
+  - webauthn
+  # Backend — infrastructure
+  - cache
+  - config
+  - database
+  - migration
+  - setup
+  - telemetry
+  - queue
+  # Frontend
+  - console
+  - login
+  # API layer
+  - grpc
+  - proto
+  # Cross-cutting
+  - build
+  - ci
+  - deps
+  - i18n
+  - integration
+  - perf
+  - security
+  - test

AGENTS.md

@@ -90,6 +90,16 @@ Run commands from the repository root.
 - `@zitadel/docs`: `dev`, `build`, `generate`, `check-links`, `check-types`, `test`, `lint`
 - `@zitadel/console`: `dev`, `build`, `generate`, `lint`
 
+## PR Title Convention
+
+PR titles are validated by the Semantic PR app. Format:
+
+`<type>(<scope>): <short summary>`
+
+**Types**: must come from the list in [`.github/semantic.yml`](.github/semantic.yml) under `types:` — e.g. `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
+
+**Scopes**: optional, but if used must come from the list in [`.github/semantic.yml`](.github/semantic.yml) under `scopes:`. When in doubt, omit the scope — do not invent values not on that list.
+
 ## Documentation
 - **Human Guide**: See `CONTRIBUTING.md` for setup and contribution details.
 - **API Design**: See `API_DESIGN.md` for API specific guidelines.

CONTRIBUTING.md

@@ -173,15 +173,13 @@ Make sure you use [semantic release messages format](https://github.com/angular/
 
 #### Type
 
-Must be one of the following:
-
-- **feat**: New Feature
-- **fix**: Bug Fix
-- **docs**: Documentation
+Allowed values are listed in [`.github/semantic.yml`](.github/semantic.yml) under `types:`.
 
 #### Scope
 
-This is optional to indicate which component is affected. If in doubt, leave blank (`<type>: <short summary>`)
+This is optional to indicate which component is affected.
+Allowed values are listed in [`.github/semantic.yml`](.github/semantic.yml) under `scopes:`.
+When in doubt, omit the scope — `<type>: <short summary>` is always valid.
 
 #### Short summary