chore(agents): add agents files (#11497)

2026-08-17 16:35:14 -05:00 · 2026-02-16 20:45:53 -08:00
parent 61756af7f7
commit db9ebbbb41
13 changed files with 263 additions and 8 deletions
@@ -0,0 +1,21 @@
+# Cursor Rules for ZITADEL
+
+You are working in the ZITADEL monorepo. 
+
+**ALWAYS** read `AGENTS.md` files in this order:
+1. Root `AGENTS.md`
+2. The nearest scoped `AGENTS.md` for the files you are changing
+
+If you touch Go code or run Go tooling, inspect `go.mod` first for the required Go version/toolchain.
+
+Use verified Nx targets only. If a target is unclear or missing, run `pnpm nx show project <project>`.
+
+- **Root Context**: [AGENTS.md](AGENTS.md)
+- **API App**: [apps/api/AGENTS.md](apps/api/AGENTS.md)
+- **Login App**: [apps/login/AGENTS.md](apps/login/AGENTS.md)
+- **Docs Site**: [apps/docs/AGENTS.md](apps/docs/AGENTS.md)
+- **Management Console**: [console/AGENTS.md](console/AGENTS.md)
+- **Backend Internal**: [internal/AGENTS.md](internal/AGENTS.md)
+- **Proto Definitions**: [proto/AGENTS.md](proto/AGENTS.md)
+- **Shared Packages**: [packages/AGENTS.md](packages/AGENTS.md)
+- **Functional UI Tests**: [tests/functional-ui/AGENTS.md](tests/functional-ui/AGENTS.md)
@@ -1 +1,23 @@
-Always respect the terminology defined in the 'Technical Glossary' section of agents.md when generating UI text or documentation.
+# GitHub Copilot Instructions for ZITADEL
+
+You are working in the ZITADEL monorepo. This codebase uses specific conventions for its Go backend and Angular/Next.js frontends.
+
+**CRITICAL**: Read `AGENTS.md` in the root first, then the nearest scoped `AGENTS.md` for changed files.
+
+## Key References
+- `AGENTS.md`: Root architecture map and global commands.
+- `apps/api/AGENTS.md`: API app workflows and backend orchestration targets.
+- `apps/login/AGENTS.md`: Specifics for the Next.js Login UI.
+- `apps/docs/AGENTS.md`: Specifics for the Fumadocs documentation.
+- `console/AGENTS.md`: Specifics for the Angular Console.
+- `internal/AGENTS.md`: Backend domain and event-sourcing boundaries.
+- `proto/AGENTS.md`: API schema and generation guidance.
+- `packages/AGENTS.md`: Shared client/proto package workflows.
+- `tests/functional-ui/AGENTS.md`: Cypress functional UI test workflows.
+
+## Behavior
+- Before Go-related work, inspect `go.mod` for required Go version/toolchain.
+- 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.
+- Distinguish between `apps/login` (Next.js) and `console` (Angular) when suggesting frontend code.
@@ -102,8 +102,7 @@ go.work.sum

 # AI Files
 CLAUDE.md
-AGENTS.md
 .mcp.json
 .gemini/*

-docs_old
+docs_old
@@ -1,3 +1,35 @@
+# ZITADEL Monorepo Guide for AI Agents
+
+## Mission & Context
+ZITADEL is an open-source Identity Management System (IAM) written in Go and Angular/React. It provides secure login, multi-tenancy, and audit trails.
+
+## Read Order
+1. Read this file first.
+2. Read the nearest scoped `AGENTS.md` for the area you edit.
+3. If multiple scopes apply, use the most specific path.
+
+## Repository Structure Map
+- **`apps/`**: Consumer-facing web applications.
+  - **`login`**: Next.js authentication UI. See `apps/login/AGENTS.md`.
+  - **`docs`**: Fumadocs documentation app. See `apps/docs/AGENTS.md`.
+  - **`api`**: Backend Nx app target. See `apps/api/AGENTS.md`.
+- **`console/`**: Angular Management Console. See `console/AGENTS.md`.
+- **`internal/`**: Backend domain and service logic. See `internal/AGENTS.md`.
+- **`proto/`**: API definitions. See `proto/AGENTS.md`.
+- **`packages/`**: Shared TypeScript packages. See `packages/AGENTS.md`.
+- **`tests/functional-ui/`**: Cypress functional UI tests. See `tests/functional-ui/AGENTS.md`.
+
+## Technology Stack & Conventions
+- **Orchestration**: Nx is used for build and task orchestration.
+- **Package Manager**: pnpm.
+- **Backend**:
+  - **Go Version Source of Truth**: Inspect `go.mod` before Go work (`go` and optional `toolchain` directives).
+  - **Communication**: For V2 APIs, connectRPC is the primary transport. gRPC and HTTP/JSON endpoints are also supported.
+  - **Pattern**: The backend is transitioning to a relational design. Events are still persisted in a separate table for history/audit, but events are not the system of record.
+- **Frontend**:
+  - **Console**: Angular + RxJS.
+  - **Login/Docs**: Next.js + React.
+
 ## ZITADEL Domain & Multi-Tenancy Logic

 ### 1. Hierarchy & Ownership
@@ -5,7 +37,7 @@
 ZITADEL follows a strict hierarchical containment model. When generating code, logic, or translations, adhere to this structure:

 - **System (Installation):** The entire ZITADEL deployment. Global settings are applied through runtime configuration files or environment variables. See `cmd/defaults.yaml`.
- **Instance (The "Identity System"):** 
+- **Instance (The "Identity System"):**
  - **Definition:** A logical partition/virtual tenant. It is a "System inside a System."
  - **Isolation:** Data and configurations are strictly isolated between instances.
  - **Translation Rule:** NEVER translate as "Example" or "Case." Use technical terms like "Tenant," "Environment," or the local equivalent of "Logical System Entity."
@@ -43,3 +75,21 @@ If a translation is requested for a language not listed above, follow these prio
 2. **Priority 2 (System Entity):** Use a term that implies a "running process" or "logical environment."
 3. **Priority 3 (Tenant):** If 'Instance' is ambiguous, use the local word for 'Tenant' (e.g., 租户 in Chinese).
 4. **Strict Ban:** NEVER use words that mean "an illustration", "a case", "a sample", or "an example."
+
+## Command Rules
+Run commands from the repository root.
+
+- Use verified Nx targets only.
+- If target availability is unclear, run `pnpm nx show project <project>`.
+- Do not assume all projects have `test`, `lint`, `build`, or `generate` targets.
+- Known exception: `@zitadel/console` has no configured `test` target.
+
+## Verified Common Targets
+- `@zitadel/api`: `prod`, `build`, `generate`, `lint`, `test`, `test-unit`, `test-integration`
+- `@zitadel/login`: `dev`, `build`, `lint`, `test`, `test-unit`, `test-integration`
+- `@zitadel/docs`: `dev`, `build`, `generate`, `check-links`, `check-types`, `test`, `lint`
+- `@zitadel/console`: `dev`, `build`, `generate`, `lint`
+
+## Documentation
+- **Human Guide**: See `CONTRIBUTING.md` for setup and contribution details.
+- **API Design**: See `API_DESIGN.md` for API specific guidelines.
@@ -1,13 +1,13 @@
 # Contributing to Zitadel

-Zitadel is an open-source identity and access management platform built with a modern tech stack including Go (API), Next.js/React (Login), Angular (Console), and Docusaurus (Docs) - all orchestrated through an Nx monorepo with pnpm for efficient development workflows.
+Zitadel is an open-source identity and access management platform built with a modern tech stack including Go (API), Next.js/React (Login), Angular (Console), and Fumadocs (Docs) - all orchestrated through an Nx monorepo with pnpm for efficient development workflows.

 ## Quick Start

 1. Clone the repository: `git clone https://github.com/zitadel/zitadel` or [open it in a local Dev Container](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/zitadel/zitadel) or [create a GitHub Codespace](https://codespaces.new/zitadel/zitadel)
 2. If you cloned the repository to your local machine, install the required development dependencies
   - [Node.js v22.x](https://nodejs.org/en/download/) - Required for UI development and to run development commands `pnpm nx ...`
-   - [Go 1.24.x](https://go.dev/doc/install) - Required for API development
+   - [Go](https://go.dev/doc/install) - Required for API development. Use the version declared in `go.mod`.
   - [Docker](https://docs.docker.com/engine/install/) - Required for supporting services like the development database and for tests.
   - [Cypress runtime dependencies](https://docs.cypress.io/guides/continuous-integration/introduction#Dependencies) - Required for Browser UI tests
   <details>
@@ -129,7 +129,7 @@ The code consists of the following parts:
 | API definitions    | Specifications of the API                          | [Protobuf](https://developers.google.com/protocol-buffers)                                                | [./proto/zitadel](./proto/zitadel)                  | [Contribute to API](#contribute-to-api)             |
 | Management Console            | Frontend the user interacts with after log in      | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org)                               | [./console](./console)                              | [Contribute to Frontend](#contribute-to-frontend)   |
 | Login              | Modern authentication UI built with Next.js        | [Next.js](https://nextjs.org), [React](https://reactjs.org), [TypeScript](https://www.typescriptlang.org) | [./apps/login](./apps/login)                        | [Contribute to Frontend](#contribute-to-frontend)   |
-| Docs               | Project documentation made with docusaurus         | [Docusaurus](https://docusaurus.io/)                                                                      | [./apps/docs](./apps/docs)                          | [Contribute to Frontend](#contribute-to-frontend)   |
+| Docs               | Project documentation made with Fumadocs           | [Fumadocs](https://fumadocs.dev/)                                                                         | [./apps/docs](./apps/docs)                          | [Contribute to Frontend](#contribute-to-frontend)   |
 | translations       | Internationalization files for default languages   | YAML                                                                                                      | [./console](./console) and [./internal](./internal) | [Contribute Translations](#contribute-translations) |

 Please follow the guides to validate and test the code before you contribute.
@@ -368,7 +368,7 @@ Choose your contribution area:

 - **[Login App](#contribute-to-login)** (Next.js/React) - Modern authentication flows
 - **[Console](#contribute-to-console)** (Angular) - Admin dashboard and user management
- **[Docs](#contribute-to-docs)** (Docusaurus) - Project documentation
+- **[Docs](#contribute-to-docs)** (Fumadocs) - Project documentation
 - **[Client Packages](#client-packages)** - Shared libraries for API communication

 ### Project Dependencies
@@ -0,0 +1,22 @@
+# ZITADEL API App Guide for AI Agents
+
+## Context
+The **API App** (`apps/api`) is the Nx application target for building and running the Go backend. Most backend implementation lives in `internal/`, while this project orchestrates build, generate, lint, and test workflows.
+
+## Source of Truth
+- **Go Toolchain**: Inspect root `go.mod` before Go work.
+- **API Design Contract**: Follow `API_DESIGN.md` for service and resource conventions.
+- **Domain Logic Location**: For implementation details, also read `internal/AGENTS.md`.
+
+## Verified Nx Targets
+- **Run API (prod profile)**: `pnpm nx run @zitadel/api:prod`
+- **Build**: `pnpm nx run @zitadel/api:build`
+- **Generate (all)**: `pnpm nx run @zitadel/api:generate`
+- **Lint**: `pnpm nx run @zitadel/api:lint`
+- **Test (all)**: `pnpm nx run @zitadel/api:test`
+- **Test (unit)**: `pnpm nx run @zitadel/api:test-unit`
+- **Test (integration)**: `pnpm nx run @zitadel/api:test-integration`
+
+## Generation Notes
+- `@zitadel/api:generate` can update generated, tracked files (stubs/assets/statik). Run it intentionally.
+- API changes in `proto/` often require regenerating API, package, and docs artifacts.
@@ -0,0 +1,24 @@
+# ZITADEL Docs Guide for AI Agents
+
+## Context
+The **Docs App** (`apps/docs`) hosts the ZITADEL documentation. It has recently migrated to **Fumadocs**.
+
+## Key Technology
+- **Framework**: Fumadocs (built on Next.js).
+- **Content**: MDX (Markdown + React Components).
+- **Orchestration**: Nx.
+
+## Content Conventions
+- **Frontmatter**: Ensure standard Fumadocs frontmatter is used (title, description).
+- **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.
+
+## Verified Nx Targets
+- **Dev Server**: `pnpm nx run @zitadel/docs:dev`
+- **Build**: `pnpm nx run @zitadel/docs:build`
+- **Generate**: `pnpm nx run @zitadel/docs:generate`
+- **Lint**: `pnpm nx run @zitadel/docs:lint`
+- **Check Links**: `pnpm nx run @zitadel/docs:check-links`
+- **Check Types**: `pnpm nx run @zitadel/docs:check-types`
+- **Test**: `pnpm nx run @zitadel/docs:test`
@@ -0,0 +1,24 @@
+# ZITADEL Login App Guide for AI Agents
+
+## Context
+The **Login App** (`apps/login`) provides the user interface for authentication flows (Login, Register, MFA, etc.). It is built with Next.js and React.
+
+## Key Technology
+- **Framework**: Next.js (React).
+- **Styling**: TailwindCSS, configured via `apps/login/tailwind.config.mjs`.
+- **Data Fetching**: Primarily server-side interaction with ZITADEL APIs via `@zitadel/client` or direct gRPC calls where applicable.
+- **Language**: TypeScript.
+
+## Architecture & Conventions
+- **Routing**: Uses the Next.js App Router (routes are defined under `src/app/`).
+- **Composability**: Components should be small and reusable.
+- **State**: Critical authentication state is often managed via URL parameters (Auth Requests) and cookies/sessions.
+- **Scope Rule**: For shared API typings and client behavior, also read `packages/AGENTS.md` and `proto/AGENTS.md`.
+
+## Verified Nx Targets
+- **Dev Server**: `pnpm nx run @zitadel/login:dev`
+- **Build**: `pnpm nx run @zitadel/login:build`
+- **Lint**: `pnpm nx run @zitadel/login:lint`
+- **Test (all)**: `pnpm nx run @zitadel/login:test`
+- **Test (unit)**: `pnpm nx run @zitadel/login:test-unit`
+- **Test (integration)**: `pnpm nx run @zitadel/login:test-integration`
@@ -0,0 +1,23 @@
+# ZITADEL Console Guide for AI Agents
+
+## Context
+The **Management Console** (`console/`) is the administrative interface for ZITADEL. It allows developers and administrators to configure organizations, projects, and users.
+
+## Key Technology
+- **Framework**: Angular.
+- **Language**: TypeScript.
+- **State Management**: Reactive patterns with RxJS.
+- **UI Component Library**: Angular Material (see `console/package.json`, `@angular/material` ^20.2.14).
+
+## Architecture & Conventions
+- **Services**: Business logic should reside in injectable services, not components.
+- **Modules**: Angular Modules (NgModule) are used for grouping features.
+- **gRPC**: Heavy usage of gRPC-web or REST mappings to talk to the ZITADEL API.
+
+## Verified Nx Targets
+- **Dev Server**: `pnpm nx run @zitadel/console:dev`
+- **Build**: `pnpm nx run @zitadel/console:build`
+- **Lint**: `pnpm nx run @zitadel/console:lint`
+- **Generate**: `pnpm nx run @zitadel/console:generate`
+- **Test**: The `@zitadel/console` project currently has no `test` target configured in Nx.
+- **Functional UI Tests**: Use `pnpm nx run @zitadel/functional-ui:test` (see `tests/functional-ui/AGENTS.md`).
@@ -0,0 +1,20 @@
+# ZITADEL Internal Backend Guide for AI Agents
+
+## Context
+`internal/` contains core backend domain logic for ZITADEL: commands, queries, repositories, eventstore integration, API service layers, and supporting infrastructure.
+
+## Source of Truth
+- **Go Toolchain**: Inspect root `go.mod` before Go work.
+- **Architecture Pattern**: Relational data is the system of record; keep existing event writes that provide history/audit trails.
+- **API Contract**: For API-facing schema decisions, follow `API_DESIGN.md` and `proto/AGENTS.md`.
+
+## Boundary Rules
+- Prefer implementing business behavior in command/query layers and repository packages, not in transport handlers.
+- Avoid bypassing established event/repository flows with ad-hoc direct persistence patterns.
+- Keep API/service adapters thin; place reusable domain behavior in internal domain packages.
+
+## Validation Workflow
+- Use API project targets to validate backend changes:
+  - `pnpm nx run @zitadel/api:lint`
+  - `pnpm nx run @zitadel/api:test-unit`
+  - `pnpm nx run @zitadel/api:test-integration`
@@ -0,0 +1,18 @@
+# ZITADEL Packages Guide for AI Agents
+
+## Context
+`packages/` contains shared TypeScript libraries used by frontend applications and external consumers.
+
+## Main Packages
+- **`packages/zitadel-proto`** (`@zitadel/proto`): generated protobuf TypeScript artifacts.
+- **`packages/zitadel-client`** (`@zitadel/client`): higher-level client library built on generated proto/connect types.
+
+## Verified Nx Targets
+- **Proto generation**: `pnpm nx run @zitadel/proto:generate`
+- **Client build**: `pnpm nx run @zitadel/client:build`
+- **Client lint**: `pnpm nx run @zitadel/client:lint`
+- **Client tests**: `pnpm nx run @zitadel/client:test`
+
+## Workflow Notes
+- When changing `proto/`, regenerate `@zitadel/proto` first, then validate/build `@zitadel/client`.
+- Keep package exports and public typings stable unless a breaking release is explicitly intended.
@@ -0,0 +1,17 @@
+# ZITADEL Proto Guide for AI Agents
+
+## Context
+`proto/` defines ZITADEL API contracts. Changes here affect generated clients, backend stubs, and docs API references.
+
+## Source of Truth
+- Follow `API_DESIGN.md` for naming, versioning, deprecations, and resource-oriented API design.
+- Keep changes backward compatible within major versions unless a new major version is introduced.
+
+## Verified Nx Targets
+- **Generate TS Proto Package**: `pnpm nx run @zitadel/proto:generate`
+- **Generate API Assets/Stubs**: `pnpm nx run @zitadel/api:generate`
+- **Generate Docs Artifacts**: `pnpm nx run @zitadel/docs:generate`
+
+## Workflow Notes
+- After proto changes, validate dependent consumers (`@zitadel/client`, `@zitadel/api`, `@zitadel/docs`).
+- If Go code is touched during generation or follow-up fixes, inspect root `go.mod` before running Go tooling.
@@ -0,0 +1,15 @@
+# ZITADEL Functional UI Test Guide for AI Agents
+
+## Context
+`tests/functional-ui` contains Cypress-based end-to-end tests focused on Management Console flows against a running ZITADEL API.
+
+## Verified Nx Targets
+- **Open interactive Cypress runner**: `pnpm nx run @zitadel/functional-ui:open`
+- **Run test suite**: `pnpm nx run @zitadel/functional-ui:test`
+- **Start test DB only**: `pnpm nx run @zitadel/functional-ui:run-db`
+- **Start test API only**: `pnpm nx run @zitadel/functional-ui:run-api`
+- **Stop test infra**: `pnpm nx run @zitadel/functional-ui:stop`
+
+## Workflow Notes
+- Functional UI tests are the primary test path for Console user journeys, since `@zitadel/console` has no Nx `test` target.
+- These tests depend on API build/run orchestration; avoid changing API startup assumptions without updating this suite.