Skip to content

ActivityPub-federated video streaming platform using P2P directly in your web browser

Use AGENTS.md

Chocobozzz4ccda4656d7f
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
deleted file mode 100644
index a219e7b442..0000000000
--- a/.github/copilot-instructions.md
+++ /dev/null
@@ -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.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..cf100145b2
--- /dev/null
+++ b/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**: `[email protected]` β€”
+ 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
diff --git a/client/AGENTS.md b/client/AGENTS.md
new file mode 100644
index 0000000000..7dab716b32
--- /dev/null
+++ b/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)