Use AGENTS.md

Allow contributors to use the tool they want, reducing coupling with
copilot

See PeerTube dev position on AI: https://joinpeertube.org/faq#what-is-the-ai-policy-for-peertube-development

.github/copilot-instructions.md

@@ -1,222 +0,0 @@
-# PeerTube Copilot Instructions
-
-## Repository Overview
-
-PeerTube is an open-source, ActivityPub-federated video streaming platform using P2P technology directly in web browsers. It's developed by Framasoft and provides a decentralized alternative to centralized video platforms like YouTube.
-
-**Repository Stats:**
-- **Size**: Large monorepo (~350MB, ~15k files)
-- **Type**: Full-stack web application
-- **Languages**: TypeScript (backend), Angular (frontend), Shell scripts
-- **Target Runtime**: Node.js >=20.x, PostgreSQL >=10.x, Redis >=6.x
-- **Package Manager**: Yarn 1.x (NOT >=2.x)
-- **Architecture**: Express.js API server + Angular SPA client + P2P video delivery
-
-## Critical: Client Directory Exclusion
-
-**🚫 ALWAYS IGNORE `client/` directory** - it contains a separate Angular frontend project with its own build system, dependencies, and development workflow. Focus only on the server-side backend code.
-
-## Build & Development Commands
-
-### Prerequisites (Required)
-1. **Dependencies**: Node.js >=20.x, Yarn 1.x, PostgreSQL >=10.x, Redis >=6.x, FFmpeg >=4.3, Python >=3.8
-2. **PostgreSQL Setup**:
-   ```bash
-   sudo -u postgres createuser -P peertube
-   sudo -u postgres createdb -O peertube peertube_dev
-   sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_dev
-   sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_dev
-   ```
-3. **Services**: Start PostgreSQL and Redis before development
-
-### Installation & Build (Execute in Order)
-```bash
-# 1. ALWAYS install dependencies first (takes ~2-3 minutes)
-yarn install --frozen-lockfile
-
-# 2. Build server (required for most operations, takes ~3-5 minutes)
-npm run build:server
-
-# 3. Optional: Build full application (takes ~10-15 minutes)
-npm run build
-```
-
-**⚠️ Critical Notes:**
-- Always run `yarn install --frozen-lockfile` before any build operation
-- Server build is prerequisite for testing and development
-- Never use `npm install` - always use `yarn`
-- Build failures often indicate missing PostgreSQL extensions or wrong Node.js version
-
-### Development Commands
-```bash
-# Server-only development (recommended for backend work)
-npm run dev:server  # Starts server on localhost:9000 with hot reload
-
-# Full stack development (NOT recommended if only working on server)
-npm run dev         # Starts both server (9000) and client (3000)
-
-# Development credentials:
-# Username: root
-# Password: test
-```
-
-### Testing Commands (Execute in Order)
-```bash
-# 1. Prepare test environment (required before first test run)
-sudo -u postgres createuser $(whoami) --createdb --superuser
-npm run clean:server:test
-
-# 2. Build (required before testing)
-npm run build
-
-# 3. Run specific test suites (recommended over full test)
-npm run ci -- api-1     # API tests part 1
-npm run ci -- api-2     # API tests part 2
-npm run ci -- lint      # Linting only
-npm run ci -- client    # Client tests
-
-# 4. Run single test file
-npm run mocha -- --exit --bail packages/tests/src/api/videos/single-server.ts
-
-# 5. Full test suite (takes ~45-60 minutes, avoid unless necessary)
-npm run test
-```
-
-**⚠️ Test Environment Notes:**
-- Tests require PostgreSQL user with createdb/superuser privileges
-- Some tests need Docker containers for S3/LDAP simulation
-- Test failures often indicate missing system dependencies or DB permissions
-- Set `DISABLE_HTTP_IMPORT_TESTS=true` to skip flaky import tests
-
-### Validation Commands
-```bash
-# Lint code (runs ESLint + OpenAPI validation)
-npm run lint
-
-# Validate OpenAPI spec
-npm run swagger-cli -- validate support/doc/api/openapi.yaml
-
-# Build server
-npm run build:server
-```
-
-## Project Architecture & Layout
-
-### Server-Side Structure (Primary Focus)
-```
-server/core/
-├── controllers/api/     # Express route handlers (add new endpoints here)
-│   ├── index.ts        # Main API router registration
-│   ├── videos/         # Video-related endpoints
-│   └── users/          # User-related endpoints
-├── models/             # Sequelize database models
-│   ├── video/          # Video, channel, playlist models
-│   └── user/           # User, account models
-├── lib/                # Business logic services
-│   ├── job-queue/      # Background job processing
-│   └── emailer.ts      # Email service
-├── middlewares/        # Express middleware
-│   ├── validators/     # Input validation (always required)
-│   └── auth.ts         # Authentication middleware
-├── helpers/            # Utility functions
-└── initializers/       # App startup and constants
-```
-
-### Key Configuration Files
-- `package.json` - Main dependencies and scripts
-- `server/package.json` - Server-specific config
-- `eslint.config.mjs` - Linting rules
-- `tsconfig.base.json` - TypeScript base config
-- `config/default.yaml` - Default app configuration
-- `.mocharc.cjs` - Test runner configuration
-
-### Shared Packages (`packages/`)
-```
-packages/
-├── models/             # Shared TypeScript interfaces (modify for API changes)
-├── core-utils/         # Common utilities
-├── ffmpeg/             # Video processing
-├── server-commands/    # Test helpers
-└── tests/             # Test files
-```
-
-### Scripts Directory (`scripts/`)
-- `scripts/build/` - Build automation
-- `scripts/dev/` - Development helpers
-- `scripts/ci.sh` - Continuous integration runner
-- `scripts/test.sh` - Test runner
-
-## Continuous Integration Pipeline
-
-**GitHub Actions** (`.github/workflows/test.yml`):
-1. **Matrix Strategy**: Tests run in parallel across different suites
-2. **Required Services**: PostgreSQL, Redis, LDAP, S3, Keycloak containers
-3. **Test Suites**: `types-package`, `client`, `api-1` through `api-5`, `transcription`, `cli-plugin`, `lint`, `external-plugins`
-4. **Environment**: Ubuntu 22.04, Node.js 20.x
-5. **Typical Runtime**: 15-30 minutes per suite
-
-**Pre-commit Checks**: ESLint, TypeScript compilation, OpenAPI validation
-
-## Making Code Changes
-
-### Adding New API Endpoint
-1. Create controller in `server/core/controllers/api/`
-2. Add validation middleware in `server/core/middlewares/validators/`
-3. Register route in `server/core/controllers/api/index.ts`
-4. Update shared types in `packages/models/`
-5. Add OpenAPI documentation tags
-6. Write tests in `packages/tests/src/api/`
-
-### Common Patterns to Follow
-```typescript
-// Controller pattern
-import express from 'express'
-import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'
-
-const router = express.Router()
-router.use(apiRateLimiter)  // ALWAYS include rate limiting
-
-router.get('/:id',
-  validationMiddleware,     // ALWAYS validate inputs
-  asyncMiddleware(handler)  // ALWAYS wrap async handlers
-)
-```
-
-### Database Changes
-1. Create/modify Sequelize model in `server/core/models/`
-2. Generate migration in `server/core/initializers/migrations/`
-3. Update shared types in `packages/models/`
-4. Run `npm run build:server` to compile
-
-## Validation Steps Before PR
-
-1. **Build**: `npm run build` (must succeed)
-2. **Lint**: `npm run lint` (must pass without errors)
-5. **OpenAPI**: Validate if API changes made
-
-## Common Error Solutions
-
-**Build Errors:**
-- "Cannot find module": Run `yarn install --frozen-lockfile`
-- "PostgreSQL connection": Check PostgreSQL is running and extensions installed
-- TypeScript errors: Check Node.js version (must be >=20.x)
-
-**Test Errors:**
-- Permission denied: Ensure PostgreSQL user has createdb/superuser rights
-- Port conflicts: Stop other PeerTube instances
-- Import test failures: Set `DISABLE_HTTP_IMPORT_TESTS=true`
-
-**Development Issues:**
-- "Client dist not found": Run `npm run build:client` (only if working on client features)
-- Redis connection: Ensure Redis server is running
-- Hot reload not working: Kill all Node processes and restart
-
-## Trust These Instructions
-
-These instructions have been validated against the current codebase. Only search for additional information if:
-- Commands fail with updated error messages
-- New dependencies are added to package.json
-- Build system changes are detected
-- You need specific implementation details not covered here
-
-Focus on server-side TypeScript development in `server/core/` and ignore the `client/` directory unless explicitly working on frontend integration.

AGENTS.md

@@ -0,0 +1,406 @@
+# Project Overview
+
+PeerTube is an open-source, ActivityPub-federated video streaming platform
+that uses P2P technology directly in web browsers. Developed by Framasoft
+under the AGPL-3.0 license, it provides a decentralized alternative to
+centralized video platforms. The server is a Node.js/Express API with a
+Sequelize ORM (PostgreSQL), background job processing (BullMQ/Redis),
+ActivityPub federation, and an Angular SPA client. Video transcoding is
+handled via FFmpeg, with optional distributed runners.
+
+## Repository Structure
+
+- **apps/** — Standalone CLI applications (`peertube-cli`, `peertube-runner`)
+- **client/** — Angular frontend SPA (separate build system; ignore for
+  backend work)
+- **config/** — YAML configuration files for dev, test, and production
+- **packages/** — Shared workspace packages (monorepo):
+  - `core-utils/` — Shared pure-JS utilities
+  - `ffmpeg/` — FFmpeg wrapper library
+  - `models/` — Shared TypeScript interfaces and API types
+  - `node-utils/` — Node.js-specific helpers
+  - `server-commands/` — HTTP client helpers used by tests
+  - `tests/` — Full test suite (API, CLI, plugins, feeds, etc.)
+  - `transcription/` — Speech-to-text engine integration
+  - `transcription-devtools/` — Transcription benchmarking tools
+  - `types-generator/` — Generates the public `@peertube/peertube-types`
+    package
+  - `typescript-utils/` — Generic TypeScript helpers
+- **scripts/** — Build, CI, dev, release, and i18n shell scripts
+- **server/** — Backend entry point and core application code
+  - `server.ts` — Process entry point
+  - `core/controllers/` — Express route handlers (API, ActivityPub,
+    feeds, tracker)
+  - `core/models/` — Sequelize database models (14 categories)
+  - `core/lib/` — Business logic (transcoding, live, job queue,
+    ActivityPub, plugins, runners, notifications, etc.)
+  - `core/middlewares/` — Auth, rate-limiting, validation, caching, CSP
+  - `core/helpers/` — Utility functions and custom validators
+  - `core/initializers/` — App bootstrap, constants, DB migrations,
+    config loading
+  - `core/types/` — Internal TypeScript type augmentations
+- **support/** — Documentation, Docker, Nginx configs, OpenAPI spec
+
+## Build & Development Commands
+
+### Prerequisites
+
+- Node.js >= 20.x
+- pnpm >= 10.9 (do **not** use npm or yarn for install)
+- PostgreSQL >= 10 with `pg_trgm` and `unaccent` extensions
+- Redis >= 6.x
+- FFmpeg >= 4.3
+- Python >= 3.8 (for some test tooling)
+
+### Install dependencies
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+### Build
+
+```bash
+# Build server only (backend work)
+npm run build:server
+
+# Build full application (server + client)
+npm run build
+
+# Build tests
+npm run build:tests
+
+# Build individual apps
+npm run build:peertube-cli
+npm run build:peertube-runner
+```
+
+### Development
+
+```bash
+# Server-only with hot reload (recommended for backend work)
+npm run dev:server        # http://localhost:9000
+
+# Full stack (server + Angular client)
+npm run dev               # server :9000, client :3000
+
+# Dev credentials: root / test
+```
+
+### Lint & type-check
+
+```bash
+# Full lint (ESLint + OpenAPI validation)
+npm run lint
+
+# ESLint only
+npm run eslint
+
+# Validate OpenAPI spec
+npm run swagger-cli -- validate support/doc/api/openapi.yaml
+
+# TypeScript compilation check
+npm run tsc -b server/tsconfig.json
+```
+
+### Run in production
+
+```bash
+npm run start              # server + client
+npm run start:server       # server only (--no-client)
+```
+
+## Code Style & Conventions
+
+### Formatting (enforced by ESLint)
+
+| Rule                | Value                                 |
+|---------------------|---------------------------------------|
+| Semicolons          | **never** (`@stylistic/semi`)         |
+| Max line length     | 140 characters                        |
+| Quotes              | Single quotes (TypeScript default)    |
+| Array brackets      | Spaces inside `[ 'a', 'b' ]`         |
+| Trailing newline    | Required (`eol-last`)                 |
+| Indentation         | 2 spaces (TypeScript convention)      |
+
+### Naming patterns
+
+- Database models: `VideoModel`, `UserModel` — PascalCase + `Model` suffix
+- Internal type aliases: `MVideo`, `MVideoWithChannel` — `M` prefix for
+  Sequelize model types with specific association requirements
+- Controllers: one file per resource, registered in parent `index.ts`
+- Validators: mirror controller structure under
+  `server/core/middlewares/validators/`
+
+### Controller pattern
+
+```typescript
+import express from 'express'
+import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'
+
+const router = express.Router()
+router.use(apiRateLimiter)  // always include rate limiting
+
+router.get('/:id',
+  validationMiddleware,     // always validate inputs
+  asyncMiddleware(handler)  // always wrap async handlers
+)
+```
+
+### Commit messages
+
+No formal commit-message template.
+
+### ESLint config
+
+Defined in `eslint.config.mjs`. Extends `eslint-config-love` with
+`@stylistic/eslint-plugin`. Applies to `server/**/*.ts`,
+`scripts/**/*.ts`, `packages/**/*.ts`, `apps/**/*.ts`. The `client/`
+directory has its own lint config.
+
+## Architecture Notes
+
+```
+                  ┌──────────────────────────────────────────┐
+                  │            Reverse Proxy (Nginx)         │
+                  └──────────────┬───────────────────────────┘
+                                 │
+              ┌──────────────────▼──────────────────────┐
+              │          Express.js API Server           │
+              │  (server/server.ts → core/controllers/)  │
+              │                                          │
+              │  ┌─────────┐ ┌──────────┐ ┌──────────┐  │
+              │  │  REST   │ │Activity- │ │  Feeds/  │  │
+              │  │  API    │ │  Pub     │ │  oEmbed  │  │
+              │  │  /api/* │ │  /inbox  │ │  /feeds  │  │
+              │  └────┬────┘ └────┬─────┘ └────┬─────┘  │
+              │       │           │             │        │
+              │  ┌────▼───────────▼─────────────▼────┐  │
+              │  │       Middleware Pipeline          │  │
+              │  │  (auth, validators, rate-limit)    │  │
+              │  └────────────────┬───────────────────┘  │
+              │                   │                      │
+              │  ┌────────────────▼───────────────────┐  │
+              │  │        Business Logic (lib/)       │  │
+              │  │  videos, live, transcoding,        │  │
+              │  │  federation, notifications,        │  │
+              │  │  plugins, runners                  │  │
+              │  └──┬──────────┬──────────────┬───┘   │
+              └─────┼──────────┼──────────────┼───────┘
+                    │          │              │
+          ┌────────▼──┐ ┌─────▼─────┐ ┌──────▼──────┐
+          │PostgreSQL │ │   Redis   │ │  FFmpeg /   │
+          │(Sequelize)│ │ (BullMQ   │ │  Runners    │
+          │           │ │  + cache) │ │             │
+          └───────────┘ └───────────┘ └─────────────┘
+```
+
+**Startup sequence** (`server/server.ts`):
+
+1. Register OpenTelemetry tracing
+2. Pre-init checks (config, FFmpeg, Node.js version)
+3. Connect to PostgreSQL, run migrations
+4. Initialize Sequelize models and load i18n
+5. Configure Express middleware stack (proxy trust, CSP, CORS,
+   rate-limiting, OAuth2 auth, express-validator)
+6. Mount route controllers and start listening
+
+**Key data flows**:
+
+- **Video upload**: REST API → validator middleware → `lib/video.ts` →
+  job queue → FFmpeg transcoding → HLS/web-video files → object
+  storage or local filesystem
+- **Federation**: Incoming ActivityPub requests → signature
+  verification → `lib/activitypub/` processors → local DB updates +
+  outgoing fan-out
+- **Live streaming**: RTMP ingest → FFmpeg segmenter → HLS manifest →
+  P2P delivery via WebSocket tracker
+
+## Testing Strategy
+
+### Test framework
+
+- **Mocha** for all server/API tests
+- **GNU Parallel** for running test files concurrently in CI
+- Tests live in `packages/tests/src/` (TypeScript source) and are
+  compiled to `packages/tests/dist/`
+
+### Preparation
+
+```bash
+# Create PostgreSQL superuser for test DB management
+sudo -u postgres createuser $(whoami) --createdb --superuser
+
+# Clean test databases
+npm run clean:server:test
+
+# Build server + tests
+npm run build:server
+npm run build:tests
+```
+
+### Running tests
+
+```bash
+# Full suite (slow, ~45-60 min)
+npm run test
+
+# Run a specific CI suite
+npm run ci -- api-1       # check-params, notifications, search
+npm run ci -- api-2       # live, server plugins, users
+npm run ci -- api-3       # videos, stats
+npm run ci -- api-4       # moderation, redundancy, object-storage,
+                          # activitypub
+npm run ci -- api-5       # transcoding, runners
+npm run ci -- client      # feeds, client, misc-endpoints, plugins
+npm run ci -- cli-plugin  # CLI and plugin tests
+npm run ci -- lint        # ESLint + OpenAPI validation + client lint
+npm run ci -- transcription
+npm run ci -- external-plugins
+
+# Run a single test file
+npm run mocha -- --timeout 30000 --exit --bail \
+  packages/tests/src/api/videos/single-server.ts
+```
+
+### External test dependencies (Docker)
+
+Some tests require these containers:
+
+```bash
+docker run -p 9444:9000 chocobozzz/s3-ninja
+docker run -p 10389:10389 chocobozzz/docker-test-openldap
+docker run -p 8082:8080 \
+  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
+  chocobozzz/peertube-tests-keycloak
+```
+
+### CI pipeline
+
+GitHub Actions (`.github/workflows/test.yml`), Ubuntu 22.04, Node.js
+20.x. Matrix strategy runs suites in parallel: `types-package`,
+`client`, `api-1`–`api-5`, `cli-plugin`, `lint`, `transcription`,
+`external-plugins`.
+
+Services provisioned per job: PostgreSQL 10, Redis, LDAP, S3 Ninja,
+Keycloak.
+
+### Environment variables for tests
+
+| Variable                                   | Purpose                     |
+|--------------------------------------------|-----------------------------|
+| `DISABLE_HTTP_IMPORT_TESTS=true`           | Skip flaky HTTP import tests|
+| `DISABLE_HTTP_YOUTUBE_IMPORT_TESTS=true`   | Skip YouTube import tests   |
+| `ENABLE_OBJECT_STORAGE_TESTS=true`         | Enable S3 tests             |
+
+## Security & Compliance
+
+- **License**: AGPL-3.0 — all network-facing modifications must be
+  published under the same license.
+- **Secrets**: The `secrets.peertube` key in `config/*.yaml` must be
+  generated via `openssl rand -hex 32`. Never commit secrets; use
+  `config/local-*.json` overrides (gitignored) or environment variables.
+- **OAuth2**: Access tokens expire in 1 day; refresh tokens in 2 weeks
+  (configurable in `config/default.yaml`).
+- **Rate limiting**: All API endpoints are rate-limited by default
+  (`apiRateLimiter` middleware). Specific limits per category (login,
+  signup, ActivityPub, etc.) are configured in `config/default.yaml`.
+- **CSP**: Content-Security-Policy headers are configurable and applied
+  via `server/core/middlewares/csp.ts`.
+- **Input validation**: Every controller uses express-validator
+  middleware defined in `server/core/middlewares/validators/`.
+- **Vulnerability reporting**: `peertube-security@framasoft.org` —
+  see `SECURITY.md`.
+- **Dependency scanning**: No automated scanner configuration found in
+  the repo.
+
+## Agent Guardrails
+
+### Files and directories agents must NOT modify
+
+- `config/local-*.json` — User-local config overrides (gitignored)
+- `config/production.yaml.example` — Template; changes need release
+  coordination
+- `server/core/initializers/migrations/` — Existing migration files are
+  immutable once released; only append new ones
+- `pnpm-lock.yaml` — Regenerated by `pnpm install`; never edit manually
+- `support/doc/api/openapi.yaml` — Must stay in sync with controllers;
+  validate with `npm run swagger-cli -- validate`
+
+### Required checks before pushing
+
+1. `npm run build:server` must succeed
+2. `npm run lint` must pass
+3. If API surface changed: `npm run swagger-cli -- validate
+   support/doc/api/openapi.yaml`
+4. If database schema changed: create a new migration file **and**
+   increment `LAST_MIGRATION_VERSION` in
+   `server/core/initializers/constants.ts`
+
+### Boundaries
+
+- Do not run `pnpm install` without `--frozen-lockfile`
+- Do not use `npm install` or `yarn` — this project uses **pnpm**
+- Do not add dependencies without explicit approval
+- Do not modify test Docker images or CI service definitions without
+  review
+- Maximum concurrency for background jobs is configured in constants;
+  do not change without benchmarking
+
+## Extensibility Hooks
+
+### Plugin system
+
+PeerTube supports server and client plugins via a hook-based
+architecture. Plugins register `filter`, `action`, and `static`
+hooks—see `support/doc/plugins/guide.md`.
+
+- Plugin names follow `peertube-plugin-*` (themes: `peertube-theme-*`)
+- Server hooks are registered in `server/core/lib/plugins/`
+- Plugin management API: `/api/v1/plugins`
+- Install/uninstall scripts: `npm run plugin:install`,
+  `npm run plugin:uninstall`
+
+### Configuration
+
+All runtime configuration is in YAML under `config/`. Local overrides
+use `config/local-*.json` files (gitignored). Key env vars:
+
+| Variable              | Purpose                              |
+|-----------------------|--------------------------------------|
+| `NODE_ENV`            | `production`, `development`, `test`  |
+| `NODE_CONFIG_DIR`     | Override config directory             |
+| `LOGGER_LEVEL`        | `debug`, `info`, `warn`, `error`     |
+| `PT_INITIAL_ROOT_PASSWORD` | Set root password on first run  |
+
+### Runners (distributed transcoding)
+
+External `peertube-runner` processes poll the API for transcoding jobs.
+Configured in `server/core/lib/runners/` and managed through the
+`/api/v1/runners` endpoints.
+
+### OpenTelemetry
+
+Tracing and metrics are instrumented via `@opentelemetry/*` packages.
+Export to Jaeger (tracing) or Prometheus (metrics) is configurable in
+`config/default.yaml` under the `open_telemetry` key.
+
+## Further Reading
+
+- [support/doc/development/server.md](support/doc/development/server.md)
+  — Server code conventions and new-feature walkthrough
+- [support/doc/development/tests.md](support/doc/development/tests.md)
+  — Test setup and execution guide
+- [support/doc/plugins/guide.md](support/doc/plugins/guide.md)
+  — Plugin & theme development guide
+- [support/doc/api/openapi.yaml](support/doc/api/openapi.yaml)
+  — OpenAPI 3.0 specification
+- [support/doc/production.md](support/doc/production.md)
+  — Production deployment guide
+- [support/doc/docker.md](support/doc/docker.md)
+  — Docker deployment guide
+- [support/doc/development/lib.md](support/doc/development/lib.md)
+  — Library / business-logic documentation
+- [SECURITY.md](SECURITY.md) — Vulnerability disclosure policy
+- [FAQ.md](FAQ.md) — Frequently asked questions

client/AGENTS.md

@@ -0,0 +1,240 @@
+# Client — Angular Frontend SPA
+
+PeerTube's web client is an Angular single-page application served
+under `/client/`. It communicates with the backend exclusively through
+the REST API (`/api/v1/`). A separate Vite-built embed player lives
+in `src/standalone/` for third-party iframe embedding.
+
+## Directory Structure
+
+- **src/app/** — Main Angular application
+  - `+about/`, `+admin/`, `+home/`, `+login/`, `+signup/`, etc. —
+    Lazy-loaded route modules (prefixed with `+`)
+  - `core/` — Singleton services: auth, routing, plugins, theme,
+    server config, notifications, screen-size helpers
+  - `shared/` — Reusable components & directives organized by domain
+    (`shared-video/`, `shared-forms/`, `shared-moderation/`, etc.)
+  - `header/`, `menu/`, `modal/` — App shell layout components
+  - `helpers/` — Client-side utility functions
+  - `hotkeys/` — Keyboard shortcut definitions
+  - `app.routes.ts` — Top-level route definitions (lazy-loaded)
+  - `app.component.ts` — Root component
+- **src/root-helpers/** — Framework-agnostic helpers (logger, storage,
+  theme manager, translations, plugin manager) shared between the
+  main app and standalone builds
+- **src/standalone/** — Independently built artifacts:
+  - `player/` — PeerTube video player (Vite build, HLS.js + P2P)
+  - `embed-player-api/` — Public npm package for programmatic
+    embed control (`@peertube/embed-api`)
+  - `videos/` — Embed page (`embed.html`) and test harness
+- **src/sass/** — Global SCSS: Bootstrap overrides, PrimeNG theme,
+  utility classes, z-index scale, fonts
+- **src/locale/** — Angular XLIFF translation files
+- **src/assets/** — Static images and assets
+- **src/environments/** — Angular environment configs
+- **e2e/** — End-to-end tests (WebdriverIO + Mocha)
+- **proxy.config.json** — Dev-server proxy to backend (:9000)
+
+## Build & Development Commands
+
+All commands run from the **repository root** unless noted.
+
+### Development
+
+```bash
+# Full stack: server (:9000) + Angular dev server (:3000)
+npm run dev
+
+# Client only (requires a running backend on :9000)
+npm run dev:client
+
+# Embed player only
+npm run dev:embed
+```
+
+The Angular dev server proxies `/api`, `/plugins`, `/themes`,
+`/static`, `/lazy-static`, `/socket.io`, and `/client/assets` to the
+backend at `http://127.0.0.1:9000` (see `proxy.config.json`).
+
+### Build
+
+```bash
+# Full client build (production)
+npm run build:client
+
+# Embed player build
+npm run build:embed
+```
+
+Output goes to `client/dist/` with per-locale sub-directories
+(e.g. `client/dist/en-US/`, `client/dist/fr-FR/`).
+
+### Lint
+
+```bash
+# From repository root
+cd client
+
+# TypeScript + Angular templates (ESLint)
+npm run lint-ts
+
+# SCSS (Stylelint)
+npm run lint-scss
+
+# Both
+npm run lint
+```
+
+### E2E tests
+
+```bash
+# Local browser (from repo root)
+npm run e2e:local
+
+# BrowserStack
+npm run e2e:browserstack
+```
+
+E2E uses **WebdriverIO** with a **Mocha** framework. Config files are
+in `e2e/` (`wdio.local.conf.ts`, `wdio.browserstack.conf.ts`).
+
+## Code Style & Conventions
+
+### TypeScript / ESLint
+
+The client has its own `eslint.config.mjs` extending
+`eslint-config-love` and `angular-eslint`. Key rules match the
+server:
+
+| Rule                | Value                             |
+|---------------------|-----------------------------------|
+| Semicolons          | **never** (`@stylistic/semi`)     |
+| Max line length     | 140 characters                    |
+| Array brackets      | Spaces inside `[ 'a', 'b' ]`     |
+| Trailing newline    | Required (`eol-last`)             |
+| Indentation         | 2 spaces                          |
+
+### Angular-specific rules
+
+| Rule                                     | Value                    |
+|------------------------------------------|--------------------------|
+| Component selector prefix               | `my-` (kebab-case)       |
+| Directive selector prefix               | `my` (camelCase)         |
+| View encapsulation                       | Required (enforced)      |
+
+### SCSS / Stylelint
+
+Configured in `.stylelintrc.json`, extends
+`stylelint-config-sass-guidelines` with `stylelint-order`. Key rules:
+
+- Declaration order: custom properties → declarations → `@include`
+- Max nesting depth: 8
+- Max compound selectors: 9
+- `::ng-deep` pseudo-element allowed
+
+### Naming patterns
+
+- Lazy-loaded route folders: `+feature-name/` (e.g. `+admin/`,
+  `+video-watch/`)
+- Shared modules: `shared-domain/` (e.g. `shared-video/`,
+  `shared-forms/`)
+- Services: PascalCase with `Service` suffix
+  (`AuthService`, `ServerService`)
+- Components: PascalCase with `Component` suffix, selector prefixed
+  `my-` (`my-video-miniature`)
+- Path aliases: `@app/*` → `src/app/*`,
+  `@root-helpers/*` → `src/root-helpers/*`
+
+### Internationalization
+
+- Source locale: `en` (base href `/client/en-US/`)
+- Translation files: XLIFF format in `src/locale/`
+- Merge tool: `@peertube/xliffmerge` (config: `.xliffmerge.json`)
+- Use Angular `$localize` / `i18n` attributes; do NOT use raw strings
+  for user-visible text
+
+## Architecture Notes
+
+```
+┌────────────────────────────────────────────────────────┐
+│                 Angular SPA (client/)                   │
+│                                                         │
+│  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  Routes   │  │  Core        │  │  Shared          │  │
+│  │ (+about,  │  │ (auth, REST, │  │ (forms, video    │  │
+│  │  +admin,  │──│  plugins,    │──│  miniature,      │  │
+│  │  +videos) │  │  server,     │  │  moderation...)  │  │
+│  │           │  │  theme)      │  │                  │  │
+│  └──────────┘  └──────┬───────┘  └──────────────────┘  │
+│                        │                                │
+│  ┌─────────────────────▼────────────────────────────┐   │
+│  │           root-helpers (no Angular dep)           │   │
+│  │  logger, storage, plugins-manager, theme, i18n   │   │
+│  └──────────────────────────────────────────────────┘   │
+│                                                         │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │         standalone/ (Vite builds)               │    │
+│  │  player/ │ embed-player-api/ │ videos/embed     │    │
+│  └─────────────────────────────────────────────────┘    │
+└────────────────────────┬────────────────────────────────┘
+                         │ HTTP (REST API)
+                         ▼
+              ┌──────────────────────┐
+              │  Express Backend     │
+              │  (:9000 /api/v1/*)   │
+              └──────────────────────┘
+```
+
+- **Lazy loading**: Each `+feature/` folder exports route configs
+  loaded via `loadChildren` in `app.routes.ts`
+- **Core services**: Singletons bootstrapped in `main.ts` via
+  `getCoreProviders()` — auth, REST client, server config polling,
+  plugin hooks, theme manager
+- **Plugin hooks**: Client-side plugins register via
+  `HooksService` / `PluginService` in `core/plugins/`
+- **State management**: No dedicated store library; services hold
+  state, components subscribe via RxJS observables
+- **UI framework**: Bootstrap 5 + PrimeNG + ng-bootstrap;
+  global SCSS in `src/sass/`
+- **Video player**: Custom build in `standalone/player/` using
+  Video.js + HLS.js + P2P Media Loader; embedded via
+  `standalone/videos/embed.html`
+
+## Agent Guardrails
+
+### Files agents must NOT modify
+
+- `src/locale/*.xlf` — Generated translation files; updated via
+  `npm run i18n:update` only
+- `dist/` — Build output; never edit manually
+- `node_modules/` — Managed by pnpm
+- `.angular/` — Angular build cache
+
+### Required checks before pushing
+
+1. `cd client && npm run lint` must pass (TS + SCSS)
+2. Production build must succeed: `npm run build:client`
+   (from repo root)
+3. If new user-visible strings added: extract with
+   `npm run i18n:create-custom-files` and verify XLIFF
+
+### Boundaries
+
+- Do not import from `server/` — the client communicates with the
+  backend exclusively via the REST API
+- Do not import Angular-specific code in `root-helpers/` or
+  `standalone/` — these must remain framework-agnostic
+- Shared API types come from `@peertube/peertube-models` and
+  `@peertube/peertube-core-utils` (workspace packages)
+- Do not add new npm dependencies without explicit approval
+
+## Further Reading
+
+- [../support/doc/plugins/guide.md](../support/doc/plugins/guide.md)
+  — Plugin & theme development (client hooks)
+- [src/standalone/embed-player-api/README.md](src/standalone/embed-player-api/README.md)
+  — Embed player API documentation
+- [../support/doc/api/embeds.md](../support/doc/api/embeds.md)
+  — Embed integration guide
+- [../AGENTS.md](../AGENTS.md)
+  — Root project AGENTS.md (server, build, CI, testing)